使用 Skopeo Copy 提升制品

功能概述

制品提升会将已构建的制品从一个受信任的位置移动到另一个位置,例如从开发镜像仓库移动到预发布或生产仓库。对于容器镜像,请使用 skopeo-copy Task 复制镜像,而无需重新构建。

当提升需要人工审核时,请在 skopeo-copy 前添加手动批准步骤。批准步骤会暂停 PipelineRun,直到所需的审批者批准此次提升;只有在批准成功后,复制步骤才会启动。

使用场景

  • 将镜像从开发、测试或预发布仓库提升到生产环境。
  • 在一次可审计的提升运行中提升多个相关镜像。
  • 要求发布经理或发布组批准生产环境提升。
  • 将构建流水线与提升流水线分离,以便从不可变的构建输出中复制生产制品,而不是重新构建。

前提条件

  • 已安装 Tekton Pipelines。
  • 配置的 Hub catalog 中提供 skopeo-copy Task。
  • 已部署 Manual Approval Gate,以支持本指南所示的审批工作流。
  • 已安装 Alauda DevOps Connectors,用于将生产凭证保存在 Connector 中——这是生产目标的推荐方式。
  • 源注册表和目标注册表凭证已作为 Kubernetes Secret 对象,准备在 PipelineRun 运行所在的命名空间中。对于生产目标,凭证保存在 Connector 中,而不是 Secret 中——请参阅将生产凭证保存在 Connector 中。
  • 流水线作者可以创建或更新 Pipeline 资源,并且运行用户可以在目标命名空间中创建 PipelineRun 资源。
  • 你了解基本的 Pipeline、PipelineRun、Task 和 Workspace 概念。

提升流程

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

  1. wait-for-approval:要求指定的审批者批准此次提升。
  2. promote-images:使用 skopeo-copy 复制一个或多个镜像。

将审批策略保留在 Pipeline 定义中是最简单且安全的做法:如果将 approvers、numberOfApprovalsRequired 或审批规则作为 PipelineRun 参数公开,却没有任何验证机制,那么启动运行的人员就可以覆盖审批规则,绕过预期的发布 控制。不同的提升需要不同审批者时,请将 approvers 作为运行参数公开, 同时添加来自 使用 Kyverno 约束制品提升 的审批者防护规则, 该规则会在运行创建前,根据允许列表验证运行提供的审批者。

除此之外,PipelineRun 只应提供每次运行可以合法变更的值,例如源镜像与 目标镜像的映射。

请注意,审批步骤本身只强制执行一项操作:暂停流水线,仅此而已。无论是否经过审批, 目标凭证都是命名空间中任何对象都可以挂载的普通 Secret。将生产凭证保存在 Connector 中 会将原始凭证移出命名空间——运行通过 Connector 借用该凭证,但永远看不到密码——随后,使用 Kyverno 约束制品提升 中的准入防护规则会将该 Connector 限制为 Tekton 控制器根据此模板创建的 Pod 使用,这样 审批步骤就成为进入生产环境的唯一途径。该章节末尾的可选门禁还可以使 Connector 在记录 审批之前暂不提供凭证。

操作步骤

1. 准备注册表凭证

为源注册表创建一个 Secret,并为目标注册表创建另一个 Secret。以下示例使用 kubernetes.io/dockerconfigjson Secret:

请替换此代码块中的:<namespace>、<source-username>、<source-password>、<destination-username>、<destination-password>。

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 绑定到两个工作区,但仅限于 非生产目标。完成将生产凭证保存在 Connector 中 后,生产凭证 根本不应再作为 Secret 存在,因此请将源凭证保存在其自己的 Secret 中;该章节最后会 删除目标 Secret。

对于生产目标,请将 dst-registry-config 视为脚手架,而不是最终状态。它是一个 普通 Secret:无论是否经过审批,命名空间中的每个 Pod 都可以挂载它。 将生产凭证保存在 Connector 中 会用 Connector 替换它,并最终删除此 Secret;在允许流水线使用生产环境之前,请先完成该章节。

2. 创建提升流水线

以下流水线将审批策略固定在 Pipeline 中,并且仅将 imageMappings、srcTLSVerify 和 dstTLSVerify 公开为运行时输入。 请使用 Identity Provider 中规范的用户和组标识符替换审批者身份。示例中指定了一名发布 经理和一个专用审批者组。如果之后采用可选:仅在审批后释放凭证中的 可选凭证释放门禁,请使此列表与该门禁的 AccessPolicy 所指定的身份完全一致—— 该章节会解释为什么在此处使用更宽泛的列表会导致运行失败,而不是扩大可协助人员的范围。

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
    - name: src-ca-bundle
      optional: true
      description: >-
        CA files for the source registry. Bind it only when that registry presents a
        certificate the copy does not already trust.
    - name: dst-ca-bundle
      optional: true
      description: >-
        CA files for the destination registry. Bind it only when that registry presents a
        certificate the copy does not already trust.
  tasks:
    - name: wait-for-approval
      taskRef:
        apiVersion: openshift-pipelines.org/v1alpha1
        kind: ApprovalTask
      timeout: "24h"
      params:
        - name: approvers
          value:
            - release-manager
            - group:prod-promotion-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
        # Both CA workspaces are passed straight through, one to one, so each run decides what
        # its two hops need. Which side needs a CA is a property of the run — a Connector-backed
        # destination, a private CA on the source — not of the template, and a workspace the run
        # leaves unbound simply keeps system trust.
        - name: src-ca-bundle
          workspace: src-ca-bundle
        - name: dst-ca-bundle
          workspace: dst-ca-bundle

imageMappings 参数为数组中的每一项接受一个 SRC DST 映射。每个 镜像引用都必须包含 skopeo 传输前缀,例如 docker://。 本页后续的所有内容——由 Connector 支持的目标以及使用 Kyverno 约束制品提升中的 防护规则——都基于此参数构建。

最后两个工作区使由 Connector 支持的运行能够保持 TLS 验证开启。 skopeo-copy 将 src-ca-bundle 和 dst-ca-bundle 声明为可选工作区;绑定其中一个工作区时, 它会将该路径作为证书目录传递给 skopeo,其中的每个 *.crt 文件 都会受到信任。模板将两者都公开为可选流水线工作区,但自身不绑定任何一个,因为哪一跳 需要 CA 取决于运行,而不是模板。

对于由 Connector 支持的目标,只有一跳会重新签名。挂载的 .env 确实会将 整个复制过程——包括源拉取和目标推送——都通过 Connectors 的转发代理,但代理只会针对 与 Connector 自身地址匹配的 CONNECT 目标替换其证书,其中也包括主机和端口。 其他所有主机都会原样通过隧道传输,客户端看到的是上游服务器的原始证书。因此,目标 连接呈现 Connectors 的 CA,而源连接呈现源注册表自身的 CA。

这就是为什么下面由 Connector 支持的运行会将 dst-ca-bundle 绑定到与 dst-registry-config 相同的 connectors-csi 卷:该挂载会提供一个 ca.crt 文件,而它正是代理用于重新签名的 CA——从挂载中实时读取,而不是复制到会过期的 ConfigMap 中,因为该 CA 由 cert-manager 签发,有效期为 90 天,并且会轮换。 第二个绑定需要添加一项:configuration.names: registry-config,!ca.cert。该挂载还包含 ca.cert,这是同一证书的 弃用别名,而 skopeo 会将证书目录中的任何 *.cert 文件读取为 客户端证书——随后它会因寻找匹配的 ca.key 而中止,而挂载没有理由包含该文件。 驱动程序的 !<file> 排除项会删除此别名,并保留 ca.crt。

src-ca-bundle 需要由站点自行填写:当源注册表使用私有 CA 时,将它绑定到包含 源注册表 CA 的 ConfigMap 或 Secret,并将其作为 *.crt 文件;否则不要绑定它——未绑定的工作区不会向信任存储区添加任何 内容,复制会回退到系统信任,而这正是公有信任注册表所需的行为。下一节中的 Secret 支持运行出于这一原因不会绑定任何一个工作区;如果此类运行中的任一注册表使用私有 CA, 请将对应一侧绑定到包含该 CA 的 ConfigMap。

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。

替代方案:将一个镜像提升到多个目标

将一个源镜像提升到多个目标标签无需其他格式:imageMappings 会将其作为由多个 SRC DST 对组成的列表,其中每个目标对应一个源,并重复源镜像。

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-api:1.2.3 docker://prod-registry.example.com/team/app-api:stable

在本页其余内容适用的地方,均保持使用这种格式。下面由 Connector 支持的目标,以及 使用 Kyverno 约束制品提升 中的防护规则,都是基于 imageMappings 构建的:防护规则的内容规则只判断该参数,因此使用下面替代方案的运行不会检查其源、目标和路径;如果部署了要求映射非空的规则,则会直接拒绝该运行。

此替代方案是任务的简单模式——一个 srcImage 和一个 dstImages 列表;上面的流水线不使用此模式,并且只要 imageMappings 非空,任务就会忽略该模式。它适用于不在防护规则范围内的流水线,这类流水线会将一个源镜像复制到少量标签。要采用此方案,请将上面流水线中的整个 promote-images 任务替换为下面的任务——它位于 spec.tasks 下的相同位置,保留任务名称(这样本页后面的命令仍能找到其 TaskRun),并保留 runAfter,因此复制仍会等待审批。同时移除流水线的 imageMappings 参数:现在已经没有任何内容使用它,而且由于声明时未提供默认值,停止提供该参数的运行会失败,并显示 ParameterMissing。

tasks:
  - 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: srcTransport
        value: registry
      - name: srcImage
        value: dev-registry.example.com/team/app-api:1.2.3
      - name: dstTransport
        value: registry
      - name: srcTLSVerify
        value: $(params.srcTLSVerify)
      - name: dstTLSVerify
        value: $(params.dstTLSVerify)
      - name: dstImages
        value:
          - prod-registry.example.com/team/app-api:1.2.3
          - prod-registry.example.com/team/app-api:stable
    workspaces:
      - name: src-registry-config
        workspace: src-registry-config
      - name: dst-registry-config
        workspace: dst-registry-config
      # Same CA plumbing as the reviewed template above: both CA workspaces are passed
      # through one to one, and the run binds whichever side needs a CA the copy does not
      # already trust. Both TLS switches can stay "true" either way.
      - name: src-ca-bundle
        workspace: src-ca-bundle
      - name: dst-ca-bundle
        workspace: dst-ca-bundle

仅当流水线不在防护规则范围内时,才使用此格式。在防护规则范围内,以及提升运行包含多个源镜像时,请使用 imageMappings。

将生产凭证保存在 Connector 中

使用普通的 dockerconfigjson Secret 时,审批步骤只是编排:任何能够读取 Secret 或在命名空间中创建 Pod 的人,都可以获取 dst-registry-config 并推送到生产环境,无论是否经过审批。Alauda DevOps Connectors 会将原始凭证移出流水线的命名空间:生产凭证只存在于保存在流水线用户无法读取的命名空间中的 Connector 内,运行中的 Pod 通过 connectors-csi driver 跨命名空间借用该凭证,而 Pod 永远不会看到密码——挂载内容携带代理设置和运行的短期令牌,Connectors proxy 在请求注册表的过程中注入真实凭证。这样拆分的确切收益在于:流水线用户可以在防护规则和可选关卡规定的条件下挂载凭证,但永远无法读取它。概念页面

Connectors CSI Driver

介绍了相关机制;本节将上面的提升流水线迁移到该机制上。

请准确理解此方案的作用和局限。它会从流水线命名空间中移除密码的所有副本,因此不挂载 Connector 就无法向生产环境推送。它本身不会决定哪些 Pod 可以挂载它——任何以有权 get 该 Connector 的 service account 运行的 Pod 都可以挂载;而在流水线命名空间中,这意味着使用该运行的 service account 的每个 Pod 都可以挂载。这正是 使用 Kyverno 约束制品提升 中的准入防护规则所补充的内容:它们将 Connector 限定给 Tekton controller 为此模板的运行创建的 Pod,从而使审批步骤成为唯一的通行方式。对于生产目标,请一并采用这两项机制。本节末尾的可选关卡还可以让 driver 在记录运行审批之前暂不提供凭证;但对于上述结构而言,这并非必需。

1. 将目标凭证移入 Connector

在流水线用户无法读取其 Secret 的命名空间中,为生产注册表创建一个 OCI 类别的 Connector——该命名空间应由凭证所有者拥有,如下面的 <connector-namespace>。Connector 的 Secret 必须位于 Connector 自身的命名空间中,这也是为什么要将 Connector 一起迁移,而不是只迁移 Secret:

替换此代码块中的:<connector-namespace>、<destination-username>、<destination-password>。

apiVersion: v1
kind: Secret
metadata:
  name: prod-registry-auth
  namespace: <connector-namespace>
type: cpaas.io/distribution-registry-token
stringData:
  username: <destination-username>
  password: <destination-password>
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: prod-registry
  namespace: <connector-namespace>
spec:
  connectorClassName: oci
  address: https://prod-registry.example.com
  auth:
    name: tokenAuth
    secretRef:
      name: prod-registry-auth
      namespace: <connector-namespace>

然后允许提升运行挂载它。只有当 Pod 的 service account 有权在 Connector 所在的命名空间中 get 该 Connector 时,connectors-csi driver 才会发布卷;请仅向流水线的 service account 授予该权限,不要扩大授权范围:

替换此代码块中的:<connector-namespace>、<namespace>、<pipeline-service-account>。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: prod-registry-mount
  namespace: <connector-namespace>
rules:
  - apiGroups:
      - connectors.alauda.io
    resources:
      - connectors
    resourceNames:
      - prod-registry
    verbs:
      - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: prod-registry-mount
  namespace: <connector-namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: prod-registry-mount
subjects:
  # One entry per namespace promotion runs are created in; the service account is
  # `default` unless the promotion runs set `taskRunTemplate.serviceAccountName`.
  - kind: ServiceAccount
    name: <pipeline-service-account>
    namespace: <namespace>

2. 将运行的目标工作区绑定到 Connector

将运行的目标工作区绑定到 Connector,而不是 Secret:

替换此代码块中的:<connector-namespace>。

workspaces:
  - name: src-registry-config
    secret:
      secretName: src-registry-config
  - name: dst-registry-config
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connector.namespace: <connector-namespace>
        connector.name: prod-registry
        configuration.names: registry-config
  # The mount's built-in ca.crt is the Connectors proxy CA that re-signs the destination
  # connection, so the same mount is also the destination CA workspace.
  # !ca.cert drops the mount's deprecated alias of that file: skopeo reads any *.cert in a
  # certificate directory as a client certificate and aborts asking for a matching ca.key.
  - name: dst-ca-bundle
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connector.namespace: <connector-namespace>
        connector.name: prod-registry
        configuration.names: registry-config,!ca.cert
完整的

PipelineRun:使用 Connector 支持的目标(可直接复制粘贴)

替换此代码块中的:<connector-namespace>,以及本页示例中的运行值——Connector 名称 prod-registry 和 imageMappings 条目——替换为你自己的值。src-ca-bundle 绑定用于源注册表使用私有 CA 的情况;移除该绑定后,源将像任何受公有信任的注册表一样,使用系统信任进行验证。

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: promote-artifacts-prod-connector-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
    # The mounted configuration routes both connections through Connectors Proxy, but the
    # proxy re-signs only the destination one — every other host is tunnelled through and keeps
    # its own certificate. Verification stays on for both: dst-ca-bundle below carries the
    # mount's ca.crt, the CA the proxy signs with, and the source is verified against system
    # trust or against the CA bound to src-ca-bundle.
    - name: srcTLSVerify
      value: "true"
    - name: dstTLSVerify
      value: "true"
  workspaces:
    - name: src-registry-config
      secret:
        secretName: src-registry-config
    # Only when the source registry uses a private CA: a ConfigMap holding it as a *.crt file.
    # Leave this binding out for a source with a publicly trusted certificate.
    - name: src-ca-bundle
      configMap:
        name: src-registry-ca
    - name: dst-registry-config
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.namespace: <connector-namespace>
          connector.name: prod-registry
          configuration.names: registry-config
    # The same mount again: its built-in ca.crt is the Connectors proxy CA that re-signs the
    # destination connection, and it stays current on its own as that CA rotates.
    # !ca.cert drops the mount's deprecated alias of that file: skopeo reads any *.cert in a
    # certificate directory as a client certificate and aborts asking for a matching ca.key.
    - name: dst-ca-bundle
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.namespace: <connector-namespace>
          connector.name: prod-registry
          configuration.names: registry-config,!ca.cert

备用方案:改为关闭开关。Tekton 中关于 OCI forward proxy 的 Connectors 文档会传递 --tls-verify=false,因为代理会对其拦截的连接重新签名。这两个开关相互独立,因此请分别处理。dstTLSVerify: "false" 是无法将 Connector 挂载绑定为目标 CA 工作区的模板的备用方案——文档所涵盖的就是这种情况。srcTLSVerify: "false" 仅适用于有意使用不安全或自签名访问、且你不会提供其 CA 的源注册表;代理目标永远不会使其成为必需,因为源端跳转会通过隧道传输,并呈现源注册表自己的证书。两者都不是复制粘贴路径:上面的运行会在目标端信任代理 CA,并让源端继续使用系统信任。

运行以这种方式正常工作后,请删除旧的 dst-registry-config Secret:只要原始凭证仍作为 Secret 存在,任何能够读取该 Secret 的人都可以绕过所有关卡。上面已经处理了一个副作用:挂载的配置会将复制路由到 Connectors Proxy,由它使用 Connectors CA 对目标连接重新签名;运行会将同一挂载(去除其 ca.cert 别名)绑定到任务的 dst-ca-bundle 工作区,因此推送会信任挂载中的 ca.crt,而 dstTLSVerify 会保持为 "true"。源连接会原样通过隧道传输,并继续使用源注册表自己的证书,因此 srcTLSVerify 也会保持为 "true",并根据系统信任或绑定到 src-ca-bundle 的 CA 进行验证。如果你还部署了提升防护规则,这两个工作区已经位于规则 10 的 allowedCopyWorkspaces 列表中,因此无需进一步审核模板。

可选:仅在审批后释放凭证

Connector 上的 AccessPolicy 可以让 driver 一次只向一个 Pod 释放凭证——只有在该 Pod 对应的运行获得审批后,并且审批身份是策略本身指定的身份时才会释放。概念页面 Connectors Approval & Permission Gating、 AccessPolicy 和

AccessRequest

介绍了相关机制。

在决定之前,请先了解两点。第一,此关卡不会增加第二次审批:审批者仍只需对运行的 ApprovalTask 执行一次操作——关卡创建的 AccessRequest 会根据同一次审批自动解析,关卡只决定这一次操作是否释放凭证。第二,这是一个集群范围的变更:它需要两个会改变集群中每个 Connector 行为的 feature flag,并且在启用它们之前,所有已经使用 Connectors 的命名空间都必须做好准备——即下面的步骤 1。请将其用于这样的生产目标:凭证所有者不是流水线所有者,并且希望在凭证层面拥有最终决定权;对于其他情况,由防护规则保护的模板自身审批者就是关卡。

1. 启用审批 feature flag

受审批控制的访问需要两个默认关闭的 feature flag: enable-connectors-approval 和 enable-connector-proxy-permissions。在 operator 管理的安装中,两者都设置在 ConnectorsConfig 资源上——operator 会根据该资源协调 ConnectorsCore,因此直接在 ConnectorsCore 上修补的 flag 会被静默恢复:

替换此代码块中的:<name>、<connectors-operator-namespace>。

kubectl get connectorsconfigs -A
kubectl patch connectorsconfig <name> -n <connectors-operator-namespace> --type=merge \
  -p '{"spec":{"components":{"core":{"spec":{"featureFlags":{"enable-connectors-approval":"true","enable-connector-proxy-permissions":"true"}}}}}}'

# Confirm both flags propagated:
kubectl get connectorscore -A \
  -o jsonpath='{range .items[*]}{.metadata.name}{": "}{.spec.featureFlags.enable-connectors-approval}{" "}{.spec.featureFlags.enable-connector-proxy-permissions}{"\n"}{end}'

启用它们是集群范围的变更,而不是对该 Connector 的变更:两者启用后,集群中的每个 connectors-csi 挂载都会通过 Connector 的 connectors/proxy 权限进行授权;而挂载了未获授权 Connector 的工作负载不会明确报错——其挂载中只会携带一个 .error.json 标记,随后因缺少凭证而失败。因此,在启用前,请盘点当前挂载 Connector 的工作负载,并为每个 Connector 授予它们该权限,但不包括你即将设置关卡的生产 Connector;当前操作步骤见 Connectors Approval & Permission Gating。 无论该操作步骤具体如何执行,都必须遵守两项约束。不要为生产 Connector 授予长期有效的 connectors/proxy 授权——Connector 部分步骤 1 中的 get 授权仍需保留,这是挂载所需的权限;connectors/proxy 是关卡按运行释放的权限,而 driver 的检查只是普通权限检查,因此为其授予长期有效的授权后,无需任何审批即可满足检查,步骤 2 中的关卡也永远不会生效。不要让任何提升运行跨越切换过程:在 flag 变更与步骤 2 完成之间,其复制 Pod 只会挂载一个 .error.json 标记并失败,因此请在下一次提升开始前完成步骤 2,或者先使用 Kyverno 指南中推出部分的命令排空正在运行的运行。

2. 要求审批——由你指定的身份审批

Connector 命名空间中的 AccessPolicy 不会授予默认访问权限;内置检查确认运行的 ApprovalTask 已得到策略指定身份的审批后,它才会按 Pod 释放凭证:

替换此代码块中的:<connector-namespace>。

apiVersion: connectors.alauda.io/v1alpha1
kind: AccessPolicy
metadata:
  name: prod-registry-approval
  namespace: <connector-namespace>
spec:
  connector:
    names:
      - prod-registry
  checkGrantedPermission:
    spec:
      checks:
        - name: manual-approval
          ref:
            configMap:
              name: connectors-approvals-in-pipeline
          params:
            - name: approvers
              value:
                - release-manager
                - group:prod-promotion-approvers
            - name: numberOfApprovalsRequired
              value: "1"
      roleTemplate:
        ref:
          configMap:
            name: connectors-use-connectors-proxy-in-pod

被引用的两个 ConfigMap 由 Alauda DevOps Connectors 安装在其自己的系统命名空间中。省略 approvers 参数会保留旧行为——对 ApprovalTask 的任何审批都会释放凭证;设置该参数后,只有指定身份自身的审批才会计入。

必须满足一项约定:策略指定的每个身份也必须出现在模板的 approvers 列表中——并且建议让两个列表保持一致,如上面的流水线和策略所示。检查会读取 ApprovalTask 记录的响应,而这些响应会反映模板的审批者条目——策略中的用户名只有在该用户以自己的身份审批时才算满足;group: 条目只有在同一组的成员通过该组审批时才算满足,并且每个审批成员都会单独计入 numberOfApprovalsRequired。模板列表比策略列表更宽是一种陷阱,而不是便利:当只要求一次审批时,第一个响应就会完成 ApprovalTask,因此模板列表中存在但不在策略中的人员进行审批,会使运行因 ApproverMismatch 失败(见下一节),而不是等待正确的人员。列表保持一致时,ApproverMismatch 只能意味着篡改。

应根据所有权关系选择结构。当同一团队同时拥有流水线和凭证时,省略 approvers 参数——此时身份控制由模板自身的 approvers 列表负责,也就没有第二个列表需要保持一致。当凭证所有者不是流水线所有者时,请在策略中指定身份:策略是 Connector 命名空间中的对象,因此无论模板指定了什么身份,凭证侧都保留最终决定权。

在信任此关卡之前,请确认提升运行的 service account 没有对生产 Connector 的长期代理访问权限——在切换之前留下的长期代理授权,可能让 driver 无需任何审批就释放凭证。该检查会覆盖你指定的 service account;除此之外,请将生产 Connector 从其命名空间中的所有长期有效 connectors/proxy 授权中排除——包括任何指定它的 Role/RoleBinding 或 defaultPermission 策略。Connector 部分步骤 1 中仅用于获取的授权不属于这些授权:它需要保留,因为挂载需要它。请在没有提升运行正在进行时执行此操作(已审批的运行会持有临时的 Pod 绑定授权,直到其 Pod 完成):

替换此代码块中的:<connector-namespace>、<namespace>、<pipeline-service-account>。

# Expect: no -- repeat for every service account the promotion runs use: `default` unless a
# run sets `taskRunTemplate.serviceAccountName`, in which case that one.
kubectl auth can-i '*' connectors.connectors.alauda.io/prod-registry --subresource=proxy \
  --as=system:serviceaccount:<namespace>:<pipeline-service-account> -n <connector-namespace>

这里的 yes 表示某个长期有效的授权覆盖了该 Connector:找到指定它的 Role/RoleBinding 或 defaultPermission 策略,并将生产 Connector 从中移除。

3. 运行时会发生什么

下面的流程已在真实集群上实时验证,其中包括 Connector 和 PipelineRun:

  • 等待审批:复制 Pod 在挂载卷时等待,为其创建的 AccessRequest 报告 AccessCheckReady: Unknown,原因是 Pending。
  • 获得策略指定身份的审批:系统会创建临时的 Pod 绑定 Role/RoleBinding,挂载出现,复制继续进行,并在 Pod 完成时清理该权限。
  • 已审批,但审批者不在策略指定身份之列:检查失败,原因是 ApproverMismatch(approved, but policy requires N distinct approval(s) from [...]);driver 会挂载 .error.json 文件而不是配置,复制步骤会迅速失败。仅在流水线侧审批不会释放任何内容。
  • 已拒绝:流水线会在审批任务处停止;复制步骤永远不会启动。

检查 Connector 命名空间中的运行时记录:

替换此代码块中的:<connector-namespace>、<access-request-name>。

kubectl get accessrequests -n <connector-namespace>
kubectl get accessrequest <access-request-name> -n <connector-namespace> \
  -o jsonpath='{range .status.policies[*].matchedChecks[*]}{.condition.reason}{": "}{.condition.message}{"\n"}{end}'

启用此关卡后,强制执行发生在凭证层面,而不是流水线定义中。来自使用 Kyverno 约束制品提升的准入防护规则仍负责减轻审批者的工作——提交给他们的请求已经确认使用经过审核的模板,并且只复制已批准的制品。

操作结果

  • PipelineRun 会在 wait-for-approval 处暂停,直到所需的审批者或组批准该操作。
  • 如果审批被拒绝,PipelineRun 会失败,且不会开始提升复制。
  • 如果审批成功,skopeo-copy 会将每个映射复制到目标 registry。启用可选:仅在审批后释放凭证中的可选关卡后,还需满足一个条件:审批必须来自 AccessPolicy 指定的身份,否则凭证会被保留,复制步骤会在 AccessRequest 上因 ApproverMismatch 而失败。
  • skopeo-copy 会为成功的 registry 目标生成面向 digest 的结果,其中包括 IMAGES、dst-IMAGE_URL、dst-IMAGE_DIGEST、dst-image-urls 和 dst-image-tag。

使用以下命令检查运行。它们指定了由 Secret 支持的示例运行;对于由 Connector 支持的运行,请将以下命令中的相应值全部替换为 promote-artifacts-prod-connector-run。

请在此代码块中将相应内容替换为:<namespace>。

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 任务包含 runAfter: [wait-for-approval],或以其他方式依赖审批任务。
  • 运行用户可以更改审批者:不要将审批策略值放入 PipelineRun 参数中,或部署使用 Kyverno 约束制品提升中的审批者防护规则,以便在准入时验证运行提供的审批者。
  • 审批任务始终未出现:确认 Manual Approval Gate 已安装且就绪,然后检查 CustomRun 和 ApprovalTask 资源。
  • Registry 身份验证失败:验证源和目标 Secret 中包含 imageMappings 所使用 registry 的凭证。对于目标工作区是 Connector 挂载的运行,无需检查目标 Secret——请验证 Connector 为 Ready;启用可选关卡时,还要确认 AccessRequest 显示凭证已授予。
  • 复制 Pod 在挂载卷时一直等待:启用可选关卡后,这是审批关卡正常工作的表现——Connector 命名空间中的 AccessRequest 会报告 AccessCheckReady: Unknown / Pending,直到运行的 ApprovalTask 获得批准。如果 PipelineRun 中完全不存在 ApprovalTask,请求会一直处于待处理状态,直到运行超时。
  • 审批已通过,但复制立即失败(已启用可选关卡):读取 AccessRequest 的检查条件。ApproverMismatch 表示任务已获批准,但审批者不在 AccessPolicy 指定的身份之列——凭证被保留,挂载内容中携带的是 .error.json 标记,而不是配置。
  • 内部 registry 的 TLS 验证失败:优先挂载正确的 CA bundle,并查看复制的哪一侧失败。目标上的 x509: certificate signed by unknown authority 表示缺少 dst-ca-bundle 绑定——由 Connector 支持的运行会将 Connector 挂载绑定到该绑定;如果没有该绑定,复制会看到 Connectors 的代理证书,但找不到匹配的 CA。源上的相同错误表示缺少源 registry 的 CA:该跳转通过隧道传输,因此会呈现 registry 自身的证书,而 CA 必须通过运行中的 src-ca-bundle 提供。仅对于有意使用不安全访问或自签名证书的可信内部 registry,或作为无法在该侧绑定工作区的模板的后备方案,才将 srcTLSVerify 或 dstTLSVerify 设置为 "false"。这两个开关彼此独立——关闭其中一个并不表示另一个也被关闭。
  • 复制因 missing key ca.key for client certificate ca.cert 失败:Connector 挂载被绑定为 CA 工作区,但其 configuration.names 中没有 !ca.cert,因此 skopeo 读取了该挂载已弃用的 ca.cert 别名,并将其作为客户端证书而不是 CA 读取。请添加排除项,如上面的 dst-ca-bundle 绑定所示。
  • 仅复制了部分映射:检查 promote-images 的 TaskRun 日志。每个 imageMappings 项必须恰好包含两个引用:SRC DST。

了解更多