使用 Skopeo Copy 提升制品
目录
功能概述使用场景前提条件提升流程操作步骤1. 准备注册表凭证2. 创建提升流水线3. 启动提升运行替代方案:将一个镜像提升到多个目标将生产凭证保存在 Connector 中1. 将目标凭证移入 Connector2. 将运行的目标工作区绑定到 Connector可选:仅在审批后释放凭证1. 启用审批 feature flag2. 要求审批——由你指定的身份审批3. 运行时会发生什么操作结果故障排除了解更多功能概述
制品提升会将已构建的制品从一个受信任的位置移动到另一个位置,例如从开发镜像仓库移动到预发布或生产仓库。对于容器镜像,请使用 skopeo-copy Task 复制镜像,而无需重新构建。
当提升需要人工审核时,请在 skopeo-copy 前添加手动批准步骤。批准步骤会暂停 PipelineRun,直到所需的审批者批准此次提升;只有在批准成功后,复制步骤才会启动。
使用场景
- 将镜像从开发、测试或预发布仓库提升到生产环境。
- 在一次可审计的提升运行中提升多个相关镜像。
- 要求发布经理或发布组批准生产环境提升。
- 将构建流水线与提升流水线分离,以便从不可变的构建输出中复制生产制品,而不是重新构建。
前提条件
- 已安装
Tekton Pipelines。 - 配置的 Hub catalog 中提供
skopeo-copyTask。 - 已部署
Manual Approval Gate,以支持本指南所示的审批工作流。 - 已安装 Alauda DevOps Connectors,用于将生产凭证保存在 Connector 中——这是生产目标的推荐方式。
- 源注册表和目标注册表凭证已作为 Kubernetes
Secret对象,准备在PipelineRun运行所在的命名空间中。对于生产目标,凭证保存在Connector中,而不是Secret中——请参阅将生产凭证保存在 Connector 中。 - 流水线作者可以创建或更新
Pipeline资源,并且运行用户可以在目标命名空间中创建PipelineRun资源。 - 你了解基本的
Pipeline、PipelineRun、Task和Workspace概念。
提升流程
典型的镜像提升流水线包含两个阶段:
wait-for-approval:要求指定的审批者批准此次提升。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>。
如果同一凭证可以访问两个注册表,则可以将同一个 Secret 绑定到两个工作区,但仅限于 非生产目标。完成将生产凭证保存在 Connector 中 后,生产凭证 根本不应再作为 Secret 存在,因此请将源凭证保存在其自己的 Secret 中;该章节最后会 删除目标 Secret。
对于生产目标,请将 dst-registry-config 视为脚手架,而不是最终状态。它是一个
普通 Secret:无论是否经过审批,命名空间中的每个 Pod 都可以挂载它。
将生产凭证保存在 Connector 中 会用 Connector
替换它,并最终删除此 Secret;在允许流水线使用生产环境之前,请先完成该章节。
2. 创建提升流水线
以下流水线将审批策略固定在 Pipeline 中,并且仅将
imageMappings、srcTLSVerify 和 dstTLSVerify 公开为运行时输入。
请使用 Identity Provider 中规范的用户和组标识符替换审批者身份。示例中指定了一名发布
经理和一个专用审批者组。如果之后采用可选:仅在审批后释放凭证中的
可选凭证释放门禁,请使此列表与该门禁的 AccessPolicy 所指定的身份完全一致——
该章节会解释为什么在此处使用更宽泛的列表会导致运行失败,而不是扩大可协助人员的范围。
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:
将 timeouts.pipeline 和 timeouts.tasks 设置得足够长,以覆盖预期的审批
窗口。审批任务的超时时间应短于 PipelineRun 超时时间。在此示例中,审批任务
最多可以等待 24h,而整个 PipelineRun 最多可以运行
72h。
替代方案:将一个镜像提升到多个目标
将一个源镜像提升到多个目标标签无需其他格式:imageMappings
会将其作为由多个 SRC DST 对组成的列表,其中每个目标对应一个源,并重复源镜像。
在本页其余内容适用的地方,均保持使用这种格式。下面由 Connector 支持的目标,以及
使用 Kyverno 约束制品提升 中的防护规则,都是基于 imageMappings 构建的:防护规则的内容规则只判断该参数,因此使用下面替代方案的运行不会检查其源、目标和路径;如果部署了要求映射非空的规则,则会直接拒绝该运行。
此替代方案是任务的简单模式——一个 srcImage 和一个 dstImages 列表;上面的流水线不使用此模式,并且只要 imageMappings 非空,任务就会忽略该模式。它适用于不在防护规则范围内的流水线,这类流水线会将一个源镜像复制到少量标签。要采用此方案,请将上面流水线中的整个 promote-images 任务替换为下面的任务——它位于 spec.tasks 下的相同位置,保留任务名称(这样本页后面的命令仍能找到其 TaskRun),并保留 runAfter,因此复制仍会等待审批。同时移除流水线的 imageMappings 参数:现在已经没有任何内容使用它,而且由于声明时未提供默认值,停止提供该参数的运行会失败,并显示 ParameterMissing。
仅当流水线不在防护规则范围内时,才使用此格式。在防护规则范围内,以及提升运行包含多个源镜像时,请使用 imageMappings。
将生产凭证保存在 Connector 中
使用普通的 dockerconfigjson Secret 时,审批步骤只是编排:任何能够读取 Secret 或在命名空间中创建 Pod 的人,都可以获取 dst-registry-config 并推送到生产环境,无论是否经过审批。Alauda DevOps Connectors 会将原始凭证移出流水线的命名空间:生产凭证只存在于保存在流水线用户无法读取的命名空间中的 Connector 内,运行中的 Pod 通过 connectors-csi driver 跨命名空间借用该凭证,而 Pod 永远不会看到密码——挂载内容携带代理设置和运行的短期令牌,Connectors proxy 在请求注册表的过程中注入真实凭证。这样拆分的确切收益在于:流水线用户可以在防护规则和可选关卡规定的条件下挂载凭证,但永远无法读取它。概念页面
介绍了相关机制;本节将上面的提升流水线迁移到该机制上。
请准确理解此方案的作用和局限。它会从流水线命名空间中移除密码的所有副本,因此不挂载 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>。
然后允许提升运行挂载它。只有当 Pod 的 service account 有权在 Connector 所在的命名空间中 get 该 Connector 时,connectors-csi driver 才会发布卷;请仅向流水线的 service account 授予该权限,不要扩大授权范围:
替换此代码块中的:<connector-namespace>、<namespace>、<pipeline-service-account>。
2. 将运行的目标工作区绑定到 Connector
将运行的目标工作区绑定到 Connector,而不是 Secret:
替换此代码块中的:<connector-namespace>。
完整的
PipelineRun:使用 Connector 支持的目标(可直接复制粘贴)
替换此代码块中的:<connector-namespace>,以及本页示例中的运行值——Connector 名称 prod-registry 和 imageMappings 条目——替换为你自己的值。src-ca-bundle 绑定用于源注册表使用私有 CA 的情况;移除该绑定后,源将像任何受公有信任的注册表一样,使用系统信任进行验证。
备用方案:改为关闭开关。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 和
介绍了相关机制。
在决定之前,请先了解两点。第一,此关卡不会增加第二次审批:审批者仍只需对运行的 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>。
启用它们是集群范围的变更,而不是对该 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>。
被引用的两个 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>。
这里的 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>。
启用此关卡后,强制执行发生在凭证层面,而不是流水线定义中。来自使用 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>。
如需查看审批审计详细信息,请检查生成的 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。
了解更多
- 使用 Kyverno 约束制品提升 — 使用准入策略为此流水线保留生产 registry Connector,并固定提升操作可以复制的内容及其目标位置。
- 使用 hub resolver 指定远程任务
- Connectors CSI Driver — 介绍运行如何挂载 Connector 以及挂载内容。
- Connectors Approval & Permission Gating — 介绍可选凭证释放关卡背后的功能,其中 AccessPolicy 和 AccessRequest 分别涵盖其所基于的两个资源。