使用 Buildah 和 Merge-Image 构建跨平台镜像
功能概述
本指南演示如何使用 buildah Task 按架构构建镜像,然后使用 merge-image Task 将它们合并为单个多架构镜像。
典型流程如下:
- 构建
linux/amd64镜像标签(例如:v1.0.0-amd64) - 构建
linux/arm64镜像标签(例如:v1.0.0-arm64) - 将源标签合并为一个或多个目标标签(例如
: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:
第 2 步:创建 Pipeline 并运行 PipelineRun
在使用前请更新以下值:
- Git 仓库 URL 和 revision
- 按架构区分的源镜像标签以及最终目标镜像标签
- Crane 运行时镜像(如果你需要替换默认值)
- workspace 和 secret 名称
示例 Pipeline:
示例 PipelineRun:
本示例的关键点:
- 示例使用了
git-clone、buildah和merge-image的 hub resolver 引用,因此你的集群必须能够解析对应的 catalogTasks。 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-flagsConfigMap。 - 关闭
coschedule对跨架构调度是必要的,但仅靠这一点还不够。如果共享 workspace 由ReadWriteOncePVC 提供支持,Kubernetes 仍然无法在两个不同节点上同时以读写方式挂载该卷。要让 amd64 和 arm64 构建真正并行运行在不同节点上,请使用支持多节点共享的 workspace 后端,例如ReadWriteMany。 sourceImages应指向按架构区分的标签,而targetImages应指向你希望发布的最终多架构标签。registry-credentialsworkspace 会被buildah和merge-image复用;workspace 名称映射(registryconfig与registry-config)取决于 task 接口,必须与每个Task定义保持一致。
第 3 步:验证合并后镜像的平台
在 PipelineRun 成功后,你可以使用 crane、podman 或 skopeo 验证合并后镜像的平台:
使用 crane:
使用 podman:
使用 skopeo:
预期输出包括:
linux/amd64linux/arm64
故障排查
- 如果
buildah-amd64和buildah-arm64共享一个基于 PVC 的 workspace,并且被固定到不同架构,请检查 Tekton Pipelines 特性开关coschedule。 当你需要这些 TaskRun 调度到不同节点时,请在TektonConfig中设置spec.pipeline.coschedule: disabled;默认的workspaces模式会尝试通过 Affinity Assistant 将它们共置到同一节点。有关确切的设置位置和行为,请参见 无法在 Tekton 中使用多个 PVC workspaces。 - 即使设置了
coschedule: disabled,ReadWriteOncePVC 仍然不能同时从两个不同节点以读写方式挂载。要实现真正并行的跨架构构建,请将共享 workspace 绑定到支持ReadWriteMany的存储。 - 建议将
sourceImages和targetImages保持在同一个 registry 中。允许跨 registry 输入,但merge-image会输出警告日志。 merge-image允许跨仓库合并。对于跨 registry 的源镜像或目标镜像,它会继续执行并输出警告日志,因此请确保涉及的每个 registry 都有有效凭据。sourceImages和targetImages必须非空。重复的源引用或重复的源 digest 会被跳过,且至少必须保留一个唯一的源镜像。- 对于自签名 registry:
buildah:将 CA 文件挂载到sslcertdirmerge-image:将 CA 文件挂载到ca-bundle,并可选地设置caFileName- 仅在受信任的环境中将
TLS_VERIFY/tlsVerify设置为false
buildah参数使用大写形式(例如IMAGES、CONTAINERFILE),而merge-image使用 lower camel case(例如sourceImages、targetImages)。