Manual Approval Gate for Tekton Pipelines
目录
功能概览使用场景前提条件步骤1. 在 Pipeline 中声明审批步骤numberOfApprovalsRequired 参数2. 监控审批状态3. 批准或拒绝用户批准组批准4. 延长 PipelineRun 超时时间以处理长时间审批操作结果ApprovalTask 生命周期故障排除用户和组标识符了解更多功能概览
Manual Approval Gate 允许 Pipeline 编写者暂停 PipelineRun,直到指定的审批者审查并批准该操作。在后台,由 Operator 提供的控制器会为每个审批步骤创建一个 ApprovalTask 资源,跟踪审批者的响应,并将结果写回发起该操作的 CustomRun。
使用场景
- 在部署到生产环境或执行破坏性维护之前强制执行人工检查点。
- 通过将个人和组与
numberOfApprovalsRequired结合,实现多人审批策略。 - 通过查询
ApprovalTask状态字段或 CLI 输出,审计批准或拒绝变更的人员。
前提条件
- 集群管理员已部署
Manual Approval Gate。如果尚未部署,请参阅部署指南。 - 你可以在目标命名空间中创建或编辑
Pipeline/PipelineRun对象。 - 审批者可以在目标命名空间中修补
approvaltasks.openshift-pipelines.org资源(通常通过kubectl)。 jqCLI,用于读取以下步骤中的ApprovalTask字段。
步骤
1. 在 Pipeline 中声明审批步骤
当 Pipeline 到达 wait-for-approval 时,Tekton 会发出一个 CustomRun。审批控制器会根据你的参数创建一个 ApprovalTask,并使 PipelineRun 保持待处理状态,直到达到法定人数或发生拒绝。
numberOfApprovalsRequired 参数
审批按不同用户名分别计数。对于 group: 审批者,其每个批准的组成员都会单独计数,因此该值可能大于 approvers 中条目的数量。
如果 numberOfApprovalsRequired 大于实际能够批准的用户数,则不会报告错误。ApprovalTask 会一直处于待处理状态,直到审批者拒绝它或审批超时;超时时,控制器会将 ApprovalTask 标记为 rejected,并使 CustomRun 失败。
这适用于审批步骤的 timeout。如果整个 PipelineRun 先超时,Tekton 会取消审批步骤,但 ApprovalTask 会保持为 pending,其 CustomRun 会使 Succeeded 条件保持为 Unknown,直到自创建 ApprovalTask 起经过审批超时时间。然后,控制器会将 ApprovalTask 标记为 rejected,并使 CustomRun 失败,即使没有人拒绝它。审批超时是步骤的 CustomRun 的 spec.timeout,如果该字段为空,则为 60 分钟。当步骤设置了 timeout(例如上面的 "24h")时,该字段会保存该值,除非 PipelineRun 的某个 taskRunSpecs 条目为该步骤设置了另一个 timeout;如果步骤没有 timeout,则读取 CustomRun 上的该字段。在处理待处理的 ApprovalTask 之前,请检查 PipelineRun 状态。
然后启动 Pipeline 的 PipelineRun。其超时时间必须长于审批窗口(请参阅步骤 4)。将以下 YAML 保存为 deploy-with-approval-run.yaml,并在 Pipeline 所在的命名空间中创建它:
当运行到达 wait-for-approval 时,会出现 ApprovalTask deploy-with-approval-run-wait-for-approval。以下步骤使用此名称。
2. 监控审批状态
上述输出已缩略,显示的是任何人响应之前的 ApprovalTask:State 为 pending。首次响应后会出现 Approvers Response,而 Approvals Received 只有在首次批准后才会出现:它统计批准次数,单独的拒绝不会使其增加。
重要的状态字段:
status.state:总体门控状态,例如pending、approved或rejected。status.approvalsRequired/status.approvalsReceived:法定人数跟踪(已接收数量统计批准次数,并且仅在首次批准后出现;单独的拒绝不会使其增加)。status.approversResponse:每个用户/组的结果及消息,便于审计。
3. 批准或拒绝
用户批准
首先检查审批者列表,以确定正确的索引:
以下示例使用 --as(以及 --as-group)来展示哪个身份发送每个请求。使用自己的凭据运行命令的审批者可以省略这些标志;请参阅本步骤末尾的提示。
以用户身份批准:
以用户身份拒绝:
组批准
下面的组操作演练需要两次批准。在开始步骤 1 中的 PipelineRun 之前,将 Pipeline 中的 numberOfApprovalsRequired 设置为 "2"。使用步骤 1 中的值 "1" 时,首次批准会完成 ApprovalTask(state: approved)。如果你已经运行过步骤 1,请先删除该运行,因为步骤 1 会使用固定名称 deploy-with-approval-run 创建它。然后等待 kubectl get approvaltasks.openshift-pipelines.org 不再列出 deploy-with-approval-run-wait-for-approval:
将组配置为审批者后,该组的个人成员可以通过将其响应添加到组条目下的 users 数组来提交批准。多个组成员可以独立批准,每次批准都会计入 approvalsReceived 总数。
最初,组审批者条目没有 users 字段:
第一位组成员会创建 users 数组,并将组的 input 设置为批准:
后续组成员会追加到现有的 users 数组,并更新组的 input:
以组成员身份拒绝:
在 bob 和 carol 执行修补后,检查组条目和状态,以查看所有成员的响应:
在此示例中,release-managers 组中的 bob 和 carol 都已批准。每个组成员的批准都会单独增加 approvalsReceived,因此两名组成员的批准会计为所需总数中的两次批准。status.approversResponse 显示详细的批准信息,包括各个组成员的响应。
组批准的要点:
- 每个组成员必须执行两个必需操作:将其条目添加到
users数组,并设置组的input(即approve或reject)。此外,还可以设置组的message - 第一位组成员使用路径
/spec/approvers/<index>/users和数组值创建users数组 - 后续成员使用路径
/spec/approvers/<index>/users/-追加到数组,其中-会追加到数组末尾 users数组中的用户条目包含name和input,也可以包含其自身的message。该消息会显示在status.approversResponse中该成员的groupMembers条目中;上面的输出中的条目没有消息,因为修补操作没有设置消息- 组级别的
message字段是可选且共享的;如果后续响应提供了新消息,该字段将被覆盖 - 每个组成员的批准都会独立增加
approvalsReceived - 同一组中的多个成员可以批准,并且每次批准都会计入所需总数
status.approversResponse字段跟踪详细的批准信息,包括各个组成员- 每个组成员都使用自己的身份执行修补:webhook 会将请求的用户名和组与审批者条目进行匹配
控制器会根据情况将相应的 CustomRun 和 PipelineRun 设置为 Succeeded 或 Failed:批准会不断累积,直到满足 numberOfApprovalsRequired;而任何拒绝都会立即使 Pipeline 的该部分失败。
提示:审批者应以自己的身份修补
ApprovalTask。验证 webhook 会读取请求的用户名和组,并且只允许你修改与其匹配的条目。只有在你作为其他身份操作时(例如进行测试),才使用--as <username>和--as-group <group>;这需要 RBAC 中的模拟权限。例如,kubectl patch ... --as bob --as-group release-managers会以用户bob(属于release-managers组)的身份发送请求。
4. 延长 PipelineRun 超时时间以处理长时间审批
使用审批步骤的 timeout 字段设置审批窗口(步骤 1 中的 timeout: "24h")。如果审批可能需要数小时或数天,则应将 PipelineRun.spec.timeouts.pipeline 和 PipelineRun.spec.timeouts.tasks 设置为足够长,以涵盖审批步骤之前运行的任务、审批步骤 timeout 以及之后运行的任务:两者都从 PipelineRun 开始时计时,而 timeouts.tasks 会涵盖所有非 finally 任务。步骤 1 中的 PipelineRun 会将两者都设置为 72h,从而为 "24h" 审批步骤周围的其他任务留出 48 小时。
如果 PipelineRun 超时时间较短,PipelineRun 可能会先过期,使审批处于未解决状态。
操作结果
kubectl get approvaltasks -o yaml显示每个审批门及其state和与法定人数相关的字段(status.approvalsReceived字段统计审批次数,并在首次审批后出现)。PipelineRun状态反映审批结果:审批通过后,下游任务会恢复运行;审批被拒绝后,PipelineRun失败(Succeeded为False,原因为Failed)。审批步骤的CustomRun显示Approval Task denied,而ApprovalTask的status.approversResponse会显示拒绝者及其消息。- Dispatch 日志或
kubectl get approvaltask -o yaml输出提供用于审计的审批历史。ApprovalTask会与其PipelineRun一起删除;请参阅 ApprovalTask 生命周期。
ApprovalTask 生命周期
控制器会为每个 CustomRun 创建一个名称和命名空间均相同的 ApprovalTask,并将该 CustomRun 设置为其控制器所有者。反过来,CustomRun 由 PipelineRun 所有。由于此所有权链(PipelineRun → CustomRun → ApprovalTask),当删除 PipelineRun 时,Kubernetes 垃圾回收会删除 ApprovalTask。审批控制器不会单独保留或清理 ApprovalTask 对象。
因此,保留在 ApprovalTask 上的审批记录(例如 status.approversResponse)只要 PipelineRun 存在就会存在。当 PipelineRun 被手动删除,或通过 ttlSecondsAfterFinished 或历史记录限制被 Tekton Pruner 删除时,ApprovalTask 也会随之删除。要保留审批记录以供审计:
- 在
PipelineRun被清理之前导出ApprovalTask对象,例如使用kubectl get approvaltask <name> -n <namespace> -o yaml,或 - 延长运行审批 Pipeline 的命名空间的清理保留期限。
故障排除
- 审批任务始终未出现: 首先运行
kubectl get customruns -n <namespace>。如果其中没有列出审批步骤对应的任何CustomRun,则PipelineRun尚未执行到该步骤,例如该步骤之前运行的任务仍在运行或已失败;请检查PipelineRun状态。如果CustomRun存在,但kubectl get approvaltasks.openshift-pipelines.org -n <namespace>没有列出名称相同的ApprovalTask,请让集群管理员确认ManualApprovalGateCR 的状态为READY(kubectl get manualapprovalgate会在READY列中显示True)。该 CR 的作用域为集群级别,Operator 随附的角色不允许 Pipeline 作者读取它。如果没有控制器,CustomRun对象会一直处于待处理状态。 - 审批者缺少权限: 如果 API server 对审批者的
kubectl patch返回Forbidden,请授予其对相关命名空间中approvaltasks.openshift-pipelines.org的get、list、update和patch访问权限。如果 admission webhook 因User does not exist in the approval list或User can only update their own approval input拒绝请求,则 RBAC 无法解决此问题:请检查审批者条目是否使用 User and group identifiers 中所述的标识符,并确认补丁只修改审批者自己的条目。 - Pipeline 在审批完成前结束: 将
PipelineRun.spec.timeouts.pipeline和PipelineRun.spec.timeouts.tasks都设置为覆盖预期的审批时间窗口,并确保审批timeout设置合理。否则,即使审批者尚未响应,该运行也可能超时。 - 审批完成后仍处于待处理状态: 在
kubectl get approvaltask <name> -n <namespace> -o yaml中比较status.approvalsReceived与status.approvalsRequired。审批会按不同用户名分别计数:同时作为用户审批者和审批组成员的用户只计数一次。当某个用户作为两种角色之一的审批已记录在status.approversResponse中时,webhook 会使用User has already approved拒绝该用户作为另一种角色的审批。组成员的审批仅在该组的input为approve时计数。请从其他审批者处收集缺少的审批。
用户和组标识符
Manual Approval Gate 依赖于您平台的 Identity Provider 来匹配审批者名称。请始终使用 Identity Provider 提供的规范标识符,而不是 UI 显示名称。例如,在 Alauda Container Platform 上:
添加用户审批者时,对于本地用户,请使用 USERNAME 列(例如 admin)。对于来自 LDAP 或 OIDC 连接器的用户,请以该用户身份运行 kubectl auth whoami,并使用其输出的 Username。
对于在控制台中创建的组,在引用组审批者(例如 group:g-v9mfs)时,请使用 NAME 列(例如 g-v9mfs),而不是显示名称。对于来自 LDAP 或 OIDC 连接器的组,请以该组成员身份运行 kubectl auth whoami,并使用 Groups 中显示的组名称。其他平台会提供类似的资源,请参阅 Identity service 文档以了解确切的字段名称。
了解更多
- 以管理员身份部署
Manual Approval Gate - Manual Approval Gate 上游仓库
- 使用 Skopeo Copy 提升工件 — 展示在从一个 registry 向另一个 registry 复制镜像之前设置审批门禁