使用 Skopeo Copy 提升 Artifact
功能概述
Artifact 提升是指将已构建的 artifact 从一个受信任的位置移动到另一个位置,例如从开发镜像仓库移动到预发布或生产仓库。对于容器镜像,请使用 skopeo-copy Task 在不重新构建的情况下复制镜像。
当提升需要人工审核时,请在 skopeo-copy 之前放置一个手动审批步骤。审批步骤会暂停 PipelineRun,直到所需审批人批准该提升;复制步骤仅在审批成功后启动。
使用场景
- 将镜像从开发、测试或预发布仓库提升到生产环境。
- 在一次可审计的提升运行中提升多个相关镜像。
- 要求发布经理或发布组批准生产提升。
- 将构建流水线与提升流水线分离,使生产 artifact 从不可变的构建输出中复制,而不是重新构建。
前提条件
- 已安装
Tekton Pipelines。
skopeo-copy Task 可从已配置的 Hub catalog 中获取。
- 已部署
Manual Approval Gate,用于本指南中展示的审批工作流。有关审批配置和操作详情,请参阅 Manual Approval Gate。
- 源注册表和目标注册表凭证已准备为 Kubernetes
Secret 对象,并位于 PipelineRun 运行的命名空间中。
- 流水线作者可以创建或更新
Pipeline 资源,运行用户可以在目标命名空间中创建 PipelineRun 资源。
- 你了解基本的
Pipeline、PipelineRun、Task 和 Workspace 概念。如有需要,请查看 Pipeline、PipelineRun、Task 和 Workspace。
提升流程
典型的镜像提升流水线包含两个阶段:
wait-for-approval:要求指定审批人批准此次提升。
promote-images:使用 skopeo-copy 复制一个或多个镜像。
请将审批策略保留在 Pipeline 定义中。不要将 approvers、numberOfApprovalsRequired 或审批规则等审批策略参数暴露为 PipelineRun 参数。如果这些值在运行时可被修改,流水线执行者可能会覆盖默认审批规则,从而绕过预期的发布控制。
PipelineRun 只应提供每次运行时合法会变化的值,例如源镜像与目标镜像的映射。
步骤
1. 准备注册表凭证
为源注册表创建一个 secret,为目标注册表再创建一个 secret。以下示例使用 kubernetes.io/dockerconfigjson secrets:
kubectl create secret docker-registry src-registry-config \
-n <namespace> \
--docker-server=dev-registry.example.com \
--docker-username=<source-username> \
--docker-password=<source-password>
kubectl create secret docker-registry dst-registry-config \
-n <namespace> \
--docker-server=prod-registry.example.com \
--docker-username=<destination-username> \
--docker-password=<destination-password>
如果同一凭证可访问两个注册表,你可以将同一个 secret 绑定到两个 workspace。
2. 创建提升流水线
下面的流水线将审批策略固定在 Pipeline 中,并且仅将 imageMappings、srcTLSVerify 和 dstTLSVerify 作为运行时输入暴露。请将 release-manager 和 group:release-approvers 替换为来自你的 Identity Provider 的规范用户和组标识符。有关标识符详情,请参阅 User and group identifiers。
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
name: promote-artifacts-with-approval
spec:
params:
- name: imageMappings
type: array
description: Source-to-destination image mappings for this promotion run.
- name: srcTLSVerify
type: string
default: "true"
description: Enable TLS verification for the source registry.
- name: dstTLSVerify
type: string
default: "true"
description: Enable TLS verification for the destination registry.
workspaces:
- name: src-registry-config
- name: dst-registry-config
tasks:
- name: wait-for-approval
taskRef:
apiVersion: openshift-pipelines.org/v1alpha1
kind: ApprovalTask
timeout: "24h"
params:
- name: approvers
value:
- release-manager
- group:release-approvers
- name: numberOfApprovalsRequired
value: "1"
- name: description
value: "Approve artifact promotion to the production registry."
- name: promote-images
runAfter:
- wait-for-approval
taskRef:
resolver: hub
params:
- name: catalog
value: catalog
- name: kind
value: task
- name: name
value: skopeo-copy
- name: version
value: "0.1"
params:
- name: imageMappings
value:
- $(params.imageMappings[*])
- name: srcTLSVerify
value: $(params.srcTLSVerify)
- name: dstTLSVerify
value: $(params.dstTLSVerify)
workspaces:
- name: src-registry-config
workspace: src-registry-config
- name: dst-registry-config
workspace: dst-registry-config
imageMappings 参数接受每个数组项一个 SRC DST 映射。每个镜像引用都必须包含 skopeo 传输前缀,例如 docker://。当 imageMappings 不为空时,skopeo-copy 会将其用于批量提升,并忽略 srcImage 和 dstImages。
3. 启动提升运行
创建一个 PipelineRun 并提供需要提升的镜像。对于多个镜像,请将每一对源到目标的映射放入 imageMappings:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: promote-artifacts-prod-run
spec:
pipelineRef:
name: promote-artifacts-with-approval
timeouts:
pipeline: 72h
tasks: 72h
params:
- name: imageMappings
value:
- docker://dev-registry.example.com/team/app-api:1.2.3 docker://prod-registry.example.com/team/app-api:1.2.3
- docker://dev-registry.example.com/team/app-worker:1.2.3 docker://prod-registry.example.com/team/app-worker:1.2.3
- name: srcTLSVerify
value: "true"
- name: dstTLSVerify
value: "true"
workspaces:
- name: src-registry-config
secret:
secretName: src-registry-config
- name: dst-registry-config
secret:
secretName: dst-registry-config
将 timeouts.pipeline 和 timeouts.tasks 设置得足够长,以覆盖预期的审批窗口。审批任务超时时间应短于 PipelineRun 超时时间。在此示例中,审批任务最多可等待 24h,而整个 PipelineRun 最长可运行 72h。
替代方案:将一个镜像提升到多个目标
如果你要将一个源镜像提升到一个或多个目标标签,也可以使用 srcImage 和 dstImages,而不是 imageMappings:
tasks:
- name: promote-image
taskRef:
resolver: hub
params:
- name: catalog
value: catalog
- name: kind
value: task
- name: name
value: skopeo-copy
- name: version
value: "0.1"
params:
- name: srcTransport
value: registry
- name: srcImage
value: dev-registry.example.com/team/app-api:1.2.3
- name: dstTransport
value: registry
- name: dstImages
value:
- prod-registry.example.com/team/app-api:1.2.3
- prod-registry.example.com/team/app-api:stable
仅当一个源镜像需要一个或多个目标标签时使用此形式。当一次提升运行包含多个源镜像时,请使用 imageMappings。
运行结果
PipelineRun 会在 wait-for-approval 处停止,直到所需审批人或组完成批准。
- 如果审批被拒绝,
PipelineRun 会失败,且提升复制不会开始。
- 如果审批成功,
skopeo-copy 会将每个映射复制到目标注册表。
skopeo-copy 会为成功的注册表目标输出基于 digest 的结果,包括 IMAGES、dst-IMAGE_URL、dst-IMAGE_DIGEST、dst-image-urls 和 dst-image-tag。
使用以下命令检查运行情况:
kubectl get pipelinerun promote-artifacts-prod-run -n <namespace>
kubectl get approvaltask promote-artifacts-prod-run-wait-for-approval \
-n <namespace> \
-o jsonpath='{.status.state}{"\n"}'
PROMOTE_TASKRUN="$(kubectl get taskrun \
-n <namespace> \
-l tekton.dev/pipelineRun=promote-artifacts-prod-run,tekton.dev/pipelineTask=promote-images \
-o jsonpath='{.items[0].metadata.name}')"
kubectl get taskrun "${PROMOTE_TASKRUN}" \
-n <namespace> \
-o jsonpath='{range .status.results[*]}{.name}: {.value}{"\n"}{end}'
PROMOTE_POD="$(kubectl get taskrun "${PROMOTE_TASKRUN}" \
-n <namespace> \
-o jsonpath='{.status.podName}')"
kubectl logs "${PROMOTE_POD}" -n <namespace> -c step-copy-images
如需查看审批审计详情,请检查生成的 ApprovalTask 上的 status.approversResponse。
故障排查
- 提升在未预期的门禁前就开始了: 确认
skopeo-copy task 具有 runAfter: [wait-for-approval],或以其他方式依赖审批任务。
- 运行用户可以更改审批人: 从
PipelineRun 参数中移除审批策略值,并将其保留在受保护的 Pipeline 定义中。
- 审批任务始终不出现: 确认已安装并就绪
Manual Approval Gate,然后检查 CustomRun 和 ApprovalTask 资源。
- 注册表认证失败: 验证源和目标 secrets 是否包含
imageMappings 中所用注册表的凭证。
- 内部注册表的 TLS 验证失败: 优先挂载正确的 CA bundle。仅当受信任的内部注册表故意使用不安全访问或自签名证书时,才将
srcTLSVerify 或 dstTLSVerify 设置为 "false"。
- 只有部分映射被复制: 检查
promote-images TaskRun 日志。每个 imageMappings 项都必须恰好包含两个引用:SRC DST。
了解更多