使用 Buildah 和 Merge-Image 构建跨平台镜像

功能概述

本指南演示如何使用 buildah Task 按架构构建镜像,然后使用 merge-image Task 将它们合并为单个多架构镜像。

典型流程如下:

  1. 构建 linux/amd64 镜像标签(例如 :v1.0.0-amd64)
  2. 构建 linux/arm64 镜像标签(例如 :v1.0.0-arm64)
  3. 将源标签合并为一个或多个目标标签(例如 :v1.0.0、:latest)

使用场景

  • 从单个代码仓库构建并发布多架构镜像。
  • 保留按架构区分的构建输出,同时对外提供统一的发布标签。
  • 在一次合并步骤中重新打标签并发布多个目标标签。

前提条件

  • 已安装 Tekton Pipelines。
  • 已安装 git-clone、buildah(0.9)和 merge-image(0.1)Tasks。
  • 你可以将镜像推送到 registry。
  • registry 凭据已准备为 Kubernetes Secret。
  • 如果你使用基于原生节点的构建(如本指南所示),则集群必须同时提供 amd64 和 arm64 节点。
  • 可选的本地验证工具:crane、jq。

第 1 步:准备 registry 凭据

使用 config.json 创建一个通用 secret:

apiVersion: v1
kind: Secret
metadata:
  name: registry-config
data:
  config.json: <base64-encoded-registry-config-json>

第 2 步:创建 Pipeline 并运行 PipelineRun

在使用前请更新以下值:

  • Git 仓库 URL 和 revision
  • 按架构区分的源镜像标签以及最终目标镜像标签
  • Crane 运行时镜像(如果你需要替换默认值)
  • workspace 和 secret 名称

示例 Pipeline:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: e2e-multiarch-build
spec:
  params:
    - name: git-url
      type: string
      description: Git repository URL
    - name: git-revision
      type: string
      default: main
    - name: image-amd64
      type: string
      description: amd64 image reference
    - name: image-arm64
      type: string
      description: arm64 image reference
    - name: target-image
      type: string
      description: Final multi-architecture image reference
    - name: tls-verify
      type: string
      default: "false"
  workspaces:
    - name: shared-workspace
    - name: git-credentials
    - name: registry-credentials
  tasks:
    - name: git-clone
      params:
        - name: url
          value: $(params.git-url)
        - name: revision
          value: $(params.git-revision)
      taskRef:
        resolver: hub
        params:
          - name: kind
            value: task
          - name: catalog
            value: catalog
          - name: name
            value: git-clone
          - name: version
            value: "0.9"
      workspaces:
        - name: output
          workspace: shared-workspace
        - name: basic-auth
          workspace: git-credentials

    - name: buildah-amd64
      runAfter:
        - git-clone
      taskRef:
        resolver: hub
        params:
          - name: kind
            value: task
          - name: catalog
            value: catalog
          - name: name
            value: buildah
          - name: version
            value: "0.9"
      params:
        - name: IMAGES
          value:
            - $(params.image-amd64)
        - name: DOCKERFILE
          value: ./Dockerfile
        - name: TLS_VERIFY
          value: $(params.tls-verify)
        - name: FORMAT
          value: docker
      workspaces:
        - name: source
          workspace: shared-workspace
        - name: registryconfig
          workspace: registry-credentials

    - name: buildah-arm64
      runAfter:
        - git-clone
      taskRef:
        resolver: hub
        params:
          - name: kind
            value: task
          - name: catalog
            value: catalog
          - name: name
            value: buildah
          - name: version
            value: "0.9"
      params:
        - name: IMAGES
          value:
            - $(params.image-arm64)
        - name: DOCKERFILE
          value: ./Dockerfile
        - name: TLS_VERIFY
          value: $(params.tls-verify)
        - name: FORMAT
          value: docker
      workspaces:
        - name: source
          workspace: shared-workspace
        - name: registryconfig
          workspace: registry-credentials

    - name: merge-image
      runAfter:
        - buildah-amd64
        - buildah-arm64
      taskRef:
        resolver: hub
        params:
          - name: kind
            value: task
          - name: catalog
            value: catalog
          - name: name
            value: merge-image
          - name: version
            value: "0.1"
      params:
        - name: craneImage
          value: registry.alauda.cn:60070/devops/tektoncd/hub/crane:latest
        - name: sourceImages
          value:
            - $(params.image-amd64)
            - $(params.image-arm64)
        - name: targetImages
          value:
            - $(params.target-image)
        - name: tlsVerify
          value: $(params.tls-verify)
      workspaces:
        - name: registry-config
          workspace: registry-credentials

示例 PipelineRun:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: e2e-multiarch-build-run
spec:
  pipelineRef:
    name: e2e-multiarch-build
  params:
    - name: git-url
      value: https://github.com/your-org/your-app
    - name: git-revision
      value: main
    - name: image-amd64
      value: registry.example.com/team/app:v1.0.0-amd64
    - name: image-arm64
      value: registry.example.com/team/app:v1.0.0-arm64
    - name: target-image
      value: registry.example.com/team/app:v1.0.0
    - name: tls-verify
      value: "false"
  # Node placement is configured on the run resource.
  taskRunSpecs:
    - pipelineTaskName: buildah-amd64
      podTemplate:
        # Force this task pod onto amd64 nodes.
        nodeSelector:
          kubernetes.io/arch: amd64
    - pipelineTaskName: buildah-arm64
      podTemplate:
        # Force this task pod onto arm64 nodes.
        nodeSelector:
          kubernetes.io/arch: arm64
  workspaces:
    - name: shared-workspace
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi
    - name: git-credentials
      secret:
        secretName: git-credentials
    - name: registry-credentials
      secret:
        # Must match the Secret created in Step 1.
        secretName: registry-config

本示例的关键点:

  • 示例使用了 git-clone、buildah 和 merge-image 的 hub resolver 引用,因此你的集群必须能够解析对应的 catalog Tasks。
  • image-amd64 和 image-arm64 是显式的 Pipeline 参数。这样可以让合并输入更清晰,并且与 merge-image 消费 sourceImages 的方式一致。
  • taskRunSpecs + podTemplate.nodeSelector 配置在 PipelineRun 中;当你的集群包含混合 CPU 架构时,这一点至关重要。它们可确保每个构建任务都运行在对应的节点架构上。
  • 默认情况下,Tekton 使用 coschedule: workspaces,它会创建一个 Affinity Assistant,并尝试将共享同一个基于 PVC 的 workspace 的 TaskRun 调度到同一节点。如果你将 buildah-amd64 和 buildah-arm64 固定到不同架构,这种默认行为会与按任务设置的 nodeSelector 冲突。在这种情况下,请在 TektonConfig 中设置 spec.pipeline.coschedule: disabled,以便 Tekton 不再强制将共享 workspace 的 TaskRun 调度到同一节点。operator 会自动将该设置传播到 feature-flags ConfigMap。
  • 关闭 coschedule 对跨架构调度是必要的,但仅靠这一点还不够。如果共享 workspace 由 ReadWriteOnce PVC 提供支持,Kubernetes 仍然无法在两个不同节点上同时以读写方式挂载该卷。要让 amd64 和 arm64 构建真正并行运行在不同节点上,请使用支持多节点共享的 workspace 后端,例如 ReadWriteMany。
  • sourceImages 应指向按架构区分的标签,而 targetImages 应指向你希望发布的最终多架构标签。
  • registry-credentials workspace 会被 buildah 和 merge-image 复用;workspace 名称映射(registryconfig 与 registry-config)取决于 task 接口,必须与每个 Task 定义保持一致。

第 3 步:验证合并后镜像的平台

在 PipelineRun 成功后,你可以使用 crane、podman 或 skopeo 验证合并后镜像的平台:

使用 crane:

crane manifest registry.example.com/team/app:v1.0.0 \
  | jq -r '.manifests[].platform | "\(.os)/\(.architecture)"'

使用 podman:

podman manifest inspect docker://registry.example.com/team/app:v1.0.0 \
  | jq -r '.manifests[].platform | "\(.os)/\(.architecture)"'

使用 skopeo:

skopeo inspect --raw docker://registry.example.com/team/app:v1.0.0 \
  | jq -r '.manifests[].platform | "\(.os)/\(.architecture)"'

预期输出包括:

  • linux/amd64
  • linux/arm64

故障排查

  • 如果 buildah-amd64 和 buildah-arm64 共享一个基于 PVC 的 workspace,并且被固定到不同架构,请检查 Tekton Pipelines 特性开关 coschedule。 当你需要这些 TaskRun 调度到不同节点时,请在 TektonConfig 中设置 spec.pipeline.coschedule: disabled;默认的 workspaces 模式会尝试通过 Affinity Assistant 将它们共置到同一节点。有关确切的设置位置和行为,请参见 无法在 Tekton 中使用多个 PVC workspaces。
  • 即使设置了 coschedule: disabled,ReadWriteOnce PVC 仍然不能同时从两个不同节点以读写方式挂载。要实现真正并行的跨架构构建,请将共享 workspace 绑定到支持 ReadWriteMany 的存储。
  • 建议将 sourceImages 和 targetImages 保持在同一个 registry 中。允许跨 registry 输入,但 merge-image 会输出警告日志。
  • merge-image 允许跨仓库合并。对于跨 registry 的源镜像或目标镜像,它会继续执行并输出警告日志,因此请确保涉及的每个 registry 都有有效凭据。
  • sourceImages 和 targetImages 必须非空。重复的源引用或重复的源 digest 会被跳过,且至少必须保留一个唯一的源镜像。
  • 对于自签名 registry:
    • buildah:将 CA 文件挂载到 sslcertdir
    • merge-image:将 CA 文件挂载到 ca-bundle,并可选地设置 caFileName
    • 仅在受信任的环境中将 TLS_VERIFY / tlsVerify 设置为 false
  • buildah 参数使用大写形式(例如 IMAGES、CONTAINERFILE),而 merge-image 使用 lower camel case(例如 sourceImages、targetImages)。

相关内容