`Tekton Pipelines` 的 `Manual Approval Gate`

功能概述

Manual Approval Gate 允许流水线作者暂停一个 PipelineRun，直到指定的审批人审核并批准该操作。背后由 Operator 提供的控制器为每个审批步骤创建一个 ApprovalTask 资源，跟踪审批人的响应，并将结果写回到发起的 CustomRun。

使用场景

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

前提条件

集群管理员已部署 Manual Approval Gate。如果未部署，请参阅部署指南。
你可以在目标命名空间中创建或编辑 Pipeline/PipelineRun 对象。
审批人可以在目标命名空间中对 approvaltasks.openshift-pipelines.org 资源进行 patch（通常通过 kubectl）。例如 Alauda Container Platform 默认授予此权限；仅当你显式移除内置权限时才需自定义 RBAC。

操作步骤

1. 在流水线中声明审批步骤

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: deploy-with-approval
spec:
  tasks:
    - name: build
      taskRef:
        name: build-bundle     # 占位 Task；请替换为你的构建逻辑
    - 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     # 占位 Task；请替换为你的部署逻辑

当流水线执行到 wait-for-approval 时，Tekton 会发出一个 CustomRun。审批控制器根据你的参数创建一个 ApprovalTask，并保持 PipelineRun 处于挂起状态，直到达到法定人数或发生拒绝。

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.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'
[
  {
    "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：

# release-managers 组的第一位成员 (bob) 批准
$ 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：

# release-managers 组的第二位成员 (carol) 也批准
$ 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"}
    ]'

以组成员身份拒绝：

# release-managers 组的一位成员 (david) 拒绝
$ 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 后，检查组条目和状态以查看所有成员的响应：

$ 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 字段跟踪详细的审批信息，包括各个组成员。
使用 --as <username> --as-group <groupname> 来以组成员身份进行 patch。

控制器会相应地将对应的 CustomRun 和 PipelineRun 设置为 Succeeded 或 Failed：审批累计直到满足 numberOfApprovalsRequired，任何拒绝都会立即使该流水线段失败。

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

4. 延长 `PipelineRun` 超时时间以适应长时间审批

如果审批可能耗时数小时或数天，请配置 PipelineRun.spec.timeouts.pipeline 和 PipelineRun.spec.timeouts.tasks，使其超过审批窗口，避免在审批人响应前运行终止。一个简单的用于测试审批关卡的 PipelineRun 如下：

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

确保审批任务的 timeout 参数短于流水线超时，否则 PipelineRun 可能先过期，导致审批未解决。

操作结果

kubectl get approvaltasks -o yaml 显示每个审批关卡的 state 和法定人数相关字段（approvalsReceived 列在有人响应后出现）。
PipelineRun 状态反映审批结果：批准后下游任务继续执行；拒绝则运行失败，失败原因从 ApprovalTask 传递。
调度日志或 kubectl get approvaltask -o yaml 输出提供审批历史，便于审计。

故障排查

审批任务从未出现： 确认管理员安装的 ManualApprovalGate CR 是否处于 READY 状态。没有控制器，CustomRun 对象会一直挂起。
审批人缺少权限： 授予他们在相关命名空间对 approvaltasks.openshift-pipelines.org 的 get、list、update 和 patch 权限。
流水线在审批完成前结束： 设置 PipelineRun.spec.timeouts.pipeline 和 PipelineRun.spec.timeouts.tasks 覆盖预期审批时间窗口，且确保审批 timeout 合理。否则即使审批人未响应，运行也可能超时。
审批后仍卡在 pending 状态： 检查 status.approversResponse，查看是否有用户更改投票或拒绝。你可能需要更新审批人列表并重新运行流水线。

用户和组标识符

Manual Approval Gate 依赖平台的 Identity 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）。其他平台也会暴露类似资源——请查阅身份服务文档以获取准确字段名。

`Tekton Pipelines` 的 `Manual Approval Gate`

目录

功能概述

使用场景

前提条件

操作步骤

1. 在流水线中声明审批步骤

2. 监控审批状态

3. 审批或拒绝

用户审批

组审批

4. 延长 `PipelineRun` 超时时间以适应长时间审批

操作结果

故障排查

用户和组标识符

了解更多

#Tekton Pipelines 的 Manual Approval Gate

#目录

#功能概述

#使用场景

#前提条件

#操作步骤

#1. 在流水线中声明审批步骤

#2. 监控审批状态

#3. 审批或拒绝

#用户审批

#组审批

#4. 延长 PipelineRun 超时时间以适应长时间审批

#操作结果

#故障排查

#用户和组标识符

#了解更多

`Tekton Pipelines` 的 `Manual Approval Gate`

目录

功能概述

使用场景

前提条件

操作步骤

1. 在流水线中声明审批步骤

2. 监控审批状态

3. 审批或拒绝

用户审批

组审批

4. 延长 `PipelineRun` 超时时间以适应长时间审批

操作结果

故障排查

用户和组标识符

了解更多