Manual Approval Gate for Tekton Pipelines

功能概览

Manual Approval Gate 允许 Pipeline 编写者暂停 PipelineRun,直到指定的审批者审查并批准该操作。在后台,由 Operator 提供的控制器会为每个审批步骤创建一个 ApprovalTask 资源,跟踪审批者的响应,并将结果写回发起该操作的 CustomRun。

使用场景

  • 在部署到生产环境或执行破坏性维护之前强制执行人工检查点。
  • 通过将个人和组与 numberOfApprovalsRequired 结合,实现多人审批策略。
  • 通过查询 ApprovalTask 状态字段或 CLI 输出,审计批准或拒绝变更的人员。

前提条件

  • 集群管理员已部署 Manual Approval Gate。如果尚未部署,请参阅部署指南。
  • 你可以在目标命名空间中创建或编辑 Pipeline/PipelineRun 对象。
  • 审批者可以在目标命名空间中修补 approvaltasks.openshift-pipelines.org 资源(通常通过 kubectl)。
  • jq CLI,用于读取以下步骤中的 ApprovalTask 字段。

步骤

1. 在 Pipeline 中声明审批步骤

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: deploy-with-approval
spec:
  tasks:
    - name: build
      taskRef:
        name: build-bundle     # Placeholder Task; replace with your build logic
    - name: wait-for-approval
      runAfter:
        - build
      taskRef:
        apiVersion: openshift-pipelines.org/v1alpha1
        kind: ApprovalTask
      timeout: "24h"
      params:
        - name: approvers
          value:
            - alice
            - group:release-managers
        - name: numberOfApprovalsRequired
          value: "1"
        - name: description
          value: "Approve promotion into production"
    - name: deploy
      runAfter:
        - wait-for-approval
      taskRef:
        name: deploy-prod     # Placeholder Task; replace with your deployment logic

当 Pipeline 到达 wait-for-approval 时,Tekton 会发出一个 CustomRun。审批控制器会根据你的参数创建一个 ApprovalTask,并使 PipelineRun 保持待处理状态,直到达到法定人数或发生拒绝。

numberOfApprovalsRequired 参数

属性值
类型包含整数的字符串,例如 "2"
默认值省略该参数时为 "1"
验证必须是大于 0 的整数。否则,CustomRun 会因验证错误而失败。
上限无。该值不会与 approvers 中条目的数量进行比较。

审批按不同用户名分别计数。对于 group: 审批者,其每个批准的组成员都会单独计数,因此该值可能大于 approvers 中条目的数量。

WARNING

如果 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 所在的命名空间中创建它:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: deploy-with-approval-run
spec:
  pipelineRef:
    name: deploy-with-approval
  timeouts:
    pipeline: 72h
    tasks: 72h
kubectl create -f deploy-with-approval-run.yaml

当运行到达 wait-for-approval 时,会出现 ApprovalTask deploy-with-approval-run-wait-for-approval。以下步骤使用此名称。

2. 监控审批状态

$ kubectl get approvaltasks.openshift-pipelines.org

NAME                                         AGE
deploy-with-approval-run-wait-for-approval   4m16s
$ kubectl describe approvaltask deploy-with-approval-run-wait-for-approval
Name:         deploy-with-approval-run-wait-for-approval
Status:
  Approvals Required:  1
  Approvers:
    alice
    release-managers
  State:  pending
Events:   <none>

上述输出已缩略,显示的是任何人响应之前的 ApprovalTask:State 为 pending。首次响应后会出现 Approvers Response,而 Approvals Received 只有在首次批准后才会出现:它统计批准次数,单独的拒绝不会使其增加。

重要的状态字段:

  • status.state:总体门控状态,例如 pending、approved 或 rejected。
  • status.approvalsRequired / status.approvalsReceived:法定人数跟踪(已接收数量统计批准次数,并且仅在首次批准后出现;单独的拒绝不会使其增加)。
  • status.approversResponse:每个用户/组的结果及消息,便于审计。

3. 批准或拒绝

用户批准

首先检查审批者列表,以确定正确的索引:

$ kubectl get approvaltask deploy-with-approval-run-wait-for-approval -o json | jq '.spec.approvers'
[
  {
    "input": "pending",
    "name": "alice",
    "type": "User"
  },
  {
    "input": "pending",
    "name": "release-managers",
    "type": "Group"
  }
]

以下示例使用 --as(以及 --as-group)来展示哪个身份发送每个请求。使用自己的凭据运行命令的审批者可以省略这些标志;请参阅本步骤末尾的提示。

以用户身份批准:

kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as alice \
    -p='[
      {"op":"replace","path":"/spec/approvers/0/input","value":"approve"},
      {"op":"replace","path":"/spec/approvers/0/message","value":"QA complete"}
    ]'

以用户身份拒绝:

kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as alice \
    -p='[
      {"op":"replace","path":"/spec/approvers/0/input","value":"reject"},
      {"op":"replace","path":"/spec/approvers/0/message","value":"Found regression"}
    ]'

组批准

下面的组操作演练需要两次批准。在开始步骤 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:

kubectl delete pipelinerun deploy-with-approval-run

将组配置为审批者后,该组的个人成员可以通过将其响应添加到组条目下的 users 数组来提交批准。多个组成员可以独立批准,每次批准都会计入 approvalsReceived 总数。

最初,组审批者条目没有 users 字段:

spec:
  approvers:
  - name: alice
    type: User
    input: pending
  - name: release-managers
    type: Group
    input: pending
  numberOfApprovalsRequired: 2

第一位组成员会创建 users 数组,并将组的 input 设置为批准:

# First member (bob) from release-managers group approves
kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as bob \
    --as-group release-managers \
    -p='[
      {"op":"add","path":"/spec/approvers/1/users","value":[{"name":"bob","input":"approve"}]},
      {"op":"replace","path":"/spec/approvers/1/input","value":"approve"},
      {"op":"replace","path":"/spec/approvers/1/message","value":"Approved by bob"}
    ]'

后续组成员会追加到现有的 users 数组,并更新组的 input:

# Second member (carol) from release-managers group also approves
kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as carol \
    --as-group release-managers \
    -p='[
      {"op":"add","path":"/spec/approvers/1/users/-","value":{"name":"carol","input":"approve"}},
      {"op":"replace","path":"/spec/approvers/1/input","value":"approve"},
      {"op":"replace","path":"/spec/approvers/1/message","value":"Approved by carol"}
    ]'

以组成员身份拒绝:

# A member (david) from release-managers group rejects
kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as david \
    --as-group release-managers \
    -p='[
      {"op":"add","path":"/spec/approvers/1/users/-","value":{"name":"david","input":"reject"}},
      {"op":"replace","path":"/spec/approvers/1/input","value":"reject"},
      {"op":"replace","path":"/spec/approvers/1/message","value":"Security concerns found"}
    ]'

在 bob 和 carol 执行修补后,检查组条目和状态,以查看所有成员的响应:

$ kubectl get approvaltask deploy-with-approval-run-wait-for-approval -o json | jq '{spec: .spec.approvers[1], status: .status}'
{
  "spec": {
    "input": "approve",
    "message": "Approved by carol",
    "name": "release-managers",
    "type": "Group",
    "users": [
      {
        "input": "approve",
        "name": "bob"
      },
      {
        "input": "approve",
        "name": "carol"
      }
    ]
  },
  "status": {
    "approvalsReceived": 2,
    "approvalsRequired": 2,
    "approvers": [
      "alice",
      "release-managers"
    ],
    "approversResponse": [
      {
        "groupMembers": [
          {
            "name": "bob",
            "response": "approved"
          },
          {
            "name": "carol",
            "response": "approved"
          }
        ],
        "message": "Approved by carol",
        "name": "release-managers",
        "response": "approved",
        "type": "Group"
      }
    ],
    "startTime": "2025-11-18T14:07:48Z",
    "state": "approved"
  }
}

在此示例中,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,请让集群管理员确认 ManualApprovalGate CR 的状态为 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 上:

$ kubectl get users.auth.alauda.io
NAME                               TYPE    USERNAME   AGE
21232f297a57a5a743894a0e4a801fc3   local   admin      19d

添加用户审批者时,对于本地用户,请使用 USERNAME 列(例如 admin)。对于来自 LDAP 或 OIDC 连接器的用户,请以该用户身份运行 kubectl auth whoami,并使用其输出的 Username。

$ kubectl get groups.auth.alauda.io
NAME      DISPLAYNAME   CONNTYPE   CONNID   AGE
g-v9mfs   test-group    local      local    19d

对于在控制台中创建的组,在引用组审批者(例如 group:g-v9mfs)时,请使用 NAME 列(例如 g-v9mfs),而不是显示名称。对于来自 LDAP 或 OIDC 连接器的组,请以该组成员身份运行 kubectl auth whoami,并使用 Groups 中显示的组名称。其他平台会提供类似的资源,请参阅 Identity service 文档以了解确切的字段名称。

了解更多