#Manual Approval Gate для Tekton Pipelines

#Обзор функции

Manual Approval Gate позволяет авторам pipeline приостанавливать PipelineRun, пока назначенные утверждающие не просмотрят и не одобрят операцию. Под капотом контроллер, предоставляемый Operator, создает ресурс ApprovalTask для каждого шага утверждения, отслеживает ответы утверждающих и записывает результат обратно в исходный CustomRun.

#Сценарии использования

• Обязательные контрольные точки с участием человека перед развертыванием в production или выполнением разрушительных операций по обслуживанию.
• Реализация политик одобрения несколькими участниками путем объединения отдельных пользователей и групп с numberOfApprovalsRequired.
• Аудит того, кто одобрил или отклонил изменение, через запрос полей состояния ApprovalTask или вывод CLI.

#Предварительные требования

• Администратор кластера развернул Manual Approval Gate. Если нет, обратитесь к руководству по развертыванию.
• Вы можете создавать или изменять объекты Pipeline/PipelineRun в целевом namespace.
• Утверждающие могут выполнять patch для ресурсов approvaltasks.openshift-pipelines.org (обычно через kubectl) в целевом namespace. Платформы, такие как 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. Контроллер утверждения создает 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: общее состояние gate, например 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:

# 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-операций проверьте запись группы и состояние, чтобы увидеть ответы всех участников:

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

В этом примере оба пользователя, bob и carol, из группы release-managers одобрили запрос. Каждое одобрение от участника группы увеличивает approvalsReceived отдельно, поэтому два одобрения от участников группы считаются как два одобрения в требуемом общем количестве. Поле status.approversResponse показывает подробную информацию об одобрении, включая ответы отдельных участников группы.

Ключевые моменты для одобрений от группы:

• Каждый участник группы должен выполнить две обязательные операции: добавить свою запись в массив users И установить input группы (либо approve, либо reject). При необходимости он также может задать message группы.
• Первый участник группы создает массив users по пути /spec/approvers/<index>/users, используя значение-массив
• Последующие участники добавляются в конец массива с помощью пути /spec/approvers/<index>/users/-, где - добавляет элемент в конец массива
• Каждая запись пользователя в массиве users содержит только поля name и input (внутри записи пользователя нет поля message)
• Поле message на уровне группы является необязательным и общим; оно будет перезаписано последующими ответами, если они укажут новое сообщение
• Каждое одобрение участника группы увеличивает approvalsReceived независимо
• Несколько участников одной и той же группы могут одобрять, и каждое такое одобрение учитывается в требуемом общем количестве
• Поле status.approversResponse отслеживает подробную информацию об одобрении, включая отдельных участников группы
• Используйте --as <username> --as-group <groupname>, чтобы идентифицировать себя как участника группы при выполнении patch

Контроллер переводит соответствующий CustomRun и PipelineRun в состояние Succeeded или Failed соответственно: одобрения накапливаются, пока не будет выполнено numberOfApprovalsRequired, а любое отклонение немедленно приводит к сбою этого участка pipeline.

Подсказка: Используйте --as <username> (обязательно) и --as-group <group> , когда нужно одобрить от имени конкретной личности. Валидационный webhook позволяет изменять только ту запись, которая соответствует этому impersonated user и group. RBAC должен предоставлять вам права impersonation. Например, kubectl patch ... --as bob --as-group release-managers идентифицирует вас как пользователя bob, действующего в группе release-managers.

#4. Увеличьте timeout PipelineRun для длительных утверждений

Если утверждение может занять часы или дни, настройте и PipelineRun.spec.timeouts.pipeline, и PipelineRun.spec.timeouts.tasks так, чтобы они превышали окно утверждения, иначе run завершится до ответа утверждающих. Простой PipelineRun для проверки gate утверждения выглядит следующим образом:

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

Убедитесь, что параметр timeout у задачи утверждения меньше, чем timeout pipeline. Иначе PipelineRun может завершиться раньше, оставив утверждение неразрешенным.

#Результаты выполнения

• kubectl get approvaltasks -o yaml показывает каждый gate утверждения вместе с полем state и полями, связанными с кворумом (столбец approvalsReceived появляется после того, как кто-то ответит).
• Состояние PipelineRun отражает результат утверждения: при одобрении последующие задачи возобновляются; при отклонении run завершается с ошибкой, а причина передается из ApprovalTask.
• Логи dispatch или вывод kubectl get approvaltask -o yaml предоставляют историю утверждений для аудита.

#Устранение неполадок

• Задача утверждения не появляется: убедитесь, что администратор развернул CR ManualApprovalGate и он находится в состоянии READY. Без контроллера объекты CustomRun останутся в ожидании.
• Утверждающим не хватает разрешений: предоставьте им доступ get, list, update и patch к approvaltasks.openshift-pipelines.org в соответствующем namespace.
• Pipeline завершился до окончания утверждения: установите значения PipelineRun.spec.timeouts.pipeline и PipelineRun.spec.timeouts.tasks так, чтобы они покрывали ожидаемое окно утверждения, и убедитесь, что timeout утверждения реалистичен. Иначе run может превысить timeout, даже если утверждающие еще не ответили.
• Застрял в pending даже после утверждений: проверьте status.approversResponse на наличие пользователей, которые изменили свой голос или отклонили запрос. Возможно, потребуется обновить список утверждающих и запустить 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, чтобы узнать точные имена полей.

#Подробнее

• Развертывание Manual Approval Gate от имени администратора
• Внешний репозиторий Manual Approval Gate