用于 `Tekton Pipelines` 的 `Manual Approval Gate`

功能概述

Manual Approval Gate 允许 pipeline 作者暂停 PipelineRun，直到指定的审批人审查并批准该操作。其底层实现是：Operator 提供的 controller 会为每个审批步骤创建一个 ApprovalTask 资源，跟踪审批人的响应，并将结果写回到最初的 CustomRun。

使用场景

在部署到生产环境或执行破坏性维护操作之前，强制执行人工检查点。
通过结合个人和组，并使用 numberOfApprovalsRequired，实现多人审批策略。
通过查询 ApprovalTask 的 status 字段或 CLI 输出，审计是谁批准或拒绝了变更。

前提条件

集群管理员已部署 Manual Approval Gate。如果没有，请参考部署指南。
你可以在目标 namespace 中创建或编辑 Pipeline/PipelineRun 对象。
审批人可以在目标 namespace 中对 approvaltasks.openshift-pipelines.org 资源执行 patch 操作（通常通过 kubectl）。像 Alauda Container Platform 这样的平台默认授予此能力；只有在你显式移除了内置权限时，才需要自定义 RBAC。

步骤

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。审批 controller 会使用你的参数创建一个 ApprovalTask，并保持 PipelineRun 处于 pending 状态，直到满足法定人数或发生拒绝。

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 Received:  1
  Approvals Required:  1
  Approvers:
    alice
    release-managers
  Approvers Response:
    Name:      alice
    Response:  approved
    Type:      User
  Start Time:  2025-11-17T10:37:01Z
  State:       approved
Events:        <none>

重要的 status 字段：

status.state：整体 gate 状态，例如 pending、approved 或 rejected。
status.approvalsRequired / status.approvalsReceived：法定人数跟踪（received 计数仅在至少有一个审批人响应后出现）。
status.approversResponse：按用户/组记录结果及消息，便于审计。

3. 批准或拒绝

用户审批

首先，检查 approvers 列表以确定正确的索引：

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

作为用户进行批准：

$ 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"}
    ]'

组审批

当某个组被配置为审批人时，该组的单个成员可以通过将自己的响应添加到该组条目下的 users 数组中来提交审批。多个组成员可以独立审批，每次审批都会计入 approvalsReceived 总数。

初始时，组审批人条目没有 users 字段：

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

第一位组成员会创建 users 数组，并将该组的 input 设置为 approve：

# 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"}
    ]'

完成这些 patch 后，检查组条目和 status，即可查看所有成员的响应：

$ 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": [
          {
            "message": "Approved by carol",
            "name": "bob",
            "response": "approved"
          },
          {
            "message": "Approved by carol",
            "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 字段）
组级别的 message 字段是可选且共享的；如果后续响应提供了新的消息，它会被覆盖
每位组成员的审批都会独立增加 approvalsReceived
同一组的多个成员都可以批准，并且每次批准都会计入所需总数
status.approversResponse 字段会跟踪详细的审批信息，包括单个组成员
在 patch 时使用 --as <username> --as-group <groupname> 来将自己标识为组成员

controller 会相应地将对应的 CustomRun 和 PipelineRun 设置为 Succeeded 或 Failed：审批会持续累积，直到满足 numberOfApprovalsRequired；而任何一次拒绝都会立即使该 pipeline 阶段失败。

提示： 当你需要以特定身份进行审批时，请使用 --as <username>（必需）和 --as-group <group>。validation webhook 只允许你修改与该模拟身份用户和组相匹配的条目。RBAC 必须授予你 impersonation 权限。例如，kubectl patch ... --as bob --as-group release-managers 表示你以用户 bob 的身份在 release-managers 组内执行操作。

4. 为较长审批延长 `PipelineRun` 超时

如果审批可能需要数小时或数天，请将 PipelineRun.spec.timeouts.pipeline 和 PipelineRun.spec.timeouts.tasks 都配置为超过审批窗口的时间，以便在审批人响应之前运行不会终止。用于演示审批 gate 的简单 PipelineRun 如下所示：

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

确保审批 task 的 timeout 参数短于 pipeline timeout。否则，PipelineRun 可能会先过期，导致审批无法完成。

操作结果

kubectl get approvaltasks -o yaml 会显示每个审批 gate 的 state 和与法定人数相关的字段（在有人响应后，approvalsReceived 列才会出现）。
PipelineRun status 会反映审批结果：批准时，下游任务会继续执行；拒绝时，运行会失败，并且原因会从 ApprovalTask 传递下来。
Dispatch 日志或 kubectl get approvaltask -o yaml 输出可提供审批历史，用于审计。

故障排查

审批 task 从未出现： 确认管理员安装的 ManualApprovalGate CR 处于 READY 状态。没有 controller，CustomRun 对象会一直处于 pending。
审批人缺少权限： 为他们授予在相关 namespace 中对 approvaltasks.openshift-pipelines.org 的 get、list、update 和 patch 访问权限。
Pipeline 在审批完成前结束： 将 PipelineRun.spec.timeouts.pipeline 和 PipelineRun.spec.timeouts.tasks 都设置为覆盖预期的审批窗口，并确保审批 timeout 是合理的。否则，即使审批人尚未响应，运行也可能超时。
即使已审批仍卡在 pending： 检查 status.approversResponse，查看是否有用户更改了投票或进行了拒绝。你可能需要更新 approver 列表并重新运行 pipeline。

用户和组标识

Manual Approval Gate 依赖平台的 identity provider 来匹配审批人名称。请始终使用 provider 暴露的标准标识符，而不是 UI 中显示的名称。例如，在 Alauda Container Platform 上：

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

在添加用户审批人时，请使用 USERNAME 列（例如 admin）。

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

在引用组审批人时，请使用 NAME 列（例如 g-v9mfs）（例如，group:g-v9mfs）。其他平台也会暴露类似资源——请查阅 identity service 文档以获取确切的字段名称。

用于 `Tekton Pipelines` 的 `Manual Approval Gate`

目录

功能概述

使用场景

前提条件

步骤

1. 在 pipeline 中声明审批步骤

2. 监控审批状态

3. 批准或拒绝

用户审批

组审批

4. 为较长审批延长 `PipelineRun` 超时

操作结果

故障排查

用户和组标识

了解更多

#用于 Tekton Pipelines 的 Manual Approval Gate

#目录

#功能概述

#使用场景

#前提条件

#步骤

#1. 在 pipeline 中声明审批步骤

#2. 监控审批状态

#3. 批准或拒绝

#用户审批

#组审批

#4. 为较长审批延长 PipelineRun 超时

#操作结果

#故障排查

#用户和组标识

#了解更多

用于 `Tekton Pipelines` 的 `Manual Approval Gate`

目录

功能概述

使用场景

前提条件

步骤

1. 在 pipeline 中声明审批步骤

2. 监控审批状态

3. 批准或拒绝

用户审批

组审批

4. 为较长审批延长 `PipelineRun` 超时

操作结果

故障排查

用户和组标识

了解更多