使用 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。

提升流程

典型的镜像提升流水线包含两个阶段:

  1. wait-for-approval:要求指定审批人批准此次提升。
  2. 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。

了解更多