Deploying Manual Approval Gate

Feature Overview

Manual Approval Gate provides the cluster-scoped controller and webhooks that back ApprovalTask custom tasks. Administrators must create and maintain the ManualApprovalGate custom resource (CR) so that platform users can insert manual approvals in their pipelines. This guide explains how to deploy the Manual Approval Gate component in tekton-pipelines, customize runtime options, and uninstall it safely.

Use Cases

  • Enabling manual approvals for all teams in the cluster by provisioning a managed controller.
  • Tweaking controller deployments (for example, replica counts, resource limits, or ConfigMaps) through the Operator's options contract instead of editing manifests.
  • Cleaning up the feature when approval tasks are no longer required.

Prerequisites

  • Alauda DevOps Pipelines v4.7.0 or later with cluster-admin access.
  • kubectl configured against the target cluster.

Steps

1. Create the ManualApprovalGate CR

Save the manifest as manual-approval-gate.yaml and apply it:

apiVersion: operator.tekton.dev/v1alpha1
kind: ManualApprovalGate
metadata:
  name: manual-approval-gate
spec:
  targetNamespace: tekton-pipelines
  options:
    disabled: false
kubectl apply -f manual-approval-gate.yaml
  • spec.targetNamespace determines where controller deployments, webhooks, and ConfigMaps are created. We recommend tekton-pipelines so that the component stays beside other Tekton services, but you can point it to any namespace as long as that namespace exists (or is created) before applying the CR. If you choose another namespace, replace tekton-pipelines with it in the commands and checks below.
  • Use spec.options to override Deployments, ConfigMaps, or image fields without editing generated YAML. For detailed syntax, refer to Adjusting Optional Configuration Items of Subcomponents.

2. Verify controller health

$ kubectl get manualapprovalgates.operator.tekton.dev manual-approval-gate

NAME                   VERSION          READY   REASON
manual-approval-gate   v0.9.0-72b7de52  True
$ kubectl get deployment -n tekton-pipelines | grep manual-approval-gate

manual-approval-gate-controller     1/1     1            1           1h1m
manual-approval-gate-webhook        1/1     1            1           1h1m

The CR's READY condition must report True, and you should see controller and webhook Deployments running in tekton-pipelines.

3. Reconfigure or force a rollout

  • Patch the CR to adjust replicas or other options; the Operator rolls the workloads automatically:

    kubectl patch manualapprovalgate manual-approval-gate \
      --type merge \
      --patch '{"spec":{"options":{"deployments":{"manual-approval-gate-controller":{"spec":{"replicas":2}}}}}}'
  • Check that the Operator applied the value to the Deployment, then wait for the rollout. The first command must print the value from spec.options (2 above); the second returns when the rollout is complete and prints deployment "manual-approval-gate-controller" successfully rolled out:

    kubectl get deployment manual-approval-gate-controller -n tekton-pipelines -o jsonpath='{.spec.replicas}'
    kubectl rollout status deployment/manual-approval-gate-controller -n tekton-pipelines
  • To undo an option, set the previous value explicitly in spec.options (for example "replicas":1) and wait for the rollout as shown above before you remove the entry. Removing the entry alone leaves the last applied value in place.

4. Uninstall Manual Approval Gate

Deleting the CR also deletes every ApprovalTask in the cluster. Before you delete it, list the ApprovalTask objects in all namespaces with their state and make sure that none is still pending. A plain kubectl get approvaltasks -A shows no state, so print it as a column:

kubectl get approvaltasks -A -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,STATE:.status.state

The STATE column shows pending, approved, or rejected.

Completed ApprovalTask objects are the only record of who approved a run (see Recommended Settings). Export the ones you must keep before you delete the CR, for example all of them:

kubectl get approvaltasks -A -o yaml > approvaltasks-backup.yaml

Then delete the CR and check that its Deployments are gone:

kubectl delete manualapprovalgate manual-approval-gate
kubectl get deployment -n tekton-pipelines | grep manual-approval-gate

Deleting the CR removes the Deployments, Services, and Webhooks of Manual Approval Gate. It also deletes the approvaltasks.openshift-pipelines.org CRD, and with it every ApprovalTask in the cluster. Recreating the CR installs the CRD again.

Operation Results

  • kubectl get manualapprovalgates shows the instance with READY=True, VERSION=<release>, and an empty REASON. The REASON column shows the message of the Ready condition, which is empty when the instance is ready.
  • kubectl get pods -n tekton-pipelines | grep manual-approval-gate lists controller and webhook pods in Running state.
  • After deletion, kubectl get pods,services -n tekton-pipelines | grep manual-approval prints nothing, and the approvaltasks.openshift-pipelines.org CRD and every ApprovalTask have been deleted. Recreating the CR installs the CRD again.

Troubleshooting

  • ManualApprovalGate CR shows READY False: The REASON column shows the message of the Ready condition, for example Installer set not ready: <message>. Run kubectl describe manualapprovalgate manual-approval-gate to check events, then review Operator logs (kubectl logs -n tekton-operator deploy/tekton-operator --all-containers). Mis-typed fields in spec.options or insufficient privileges are the most common root causes.
  • Controller/webhook pods crash looping: Read the log of the last failed container of a failing Pod, for example kubectl logs <pod-name> -n tekton-pipelines --previous, to see whether a TLS Secret or a ConfigMap that the process reads is missing. Reapplying an unchanged CR does not change it, and the Operator reconciles the installed objects on events of their Deployments, StatefulSets, ClusterRoles, ClusterRoleBindings and ServiceAccounts, not of ConfigMaps or Secrets, so do not expect a reapply to recreate a missing object. The Operator creates a missing ConfigMap or Secret of the installation again when it next reconciles the installed objects, which an event of one of the listed kinds starts, for example a status change of the crash-looping Deployment. After the object is back and the Pods have restarted, kubectl get pods -n tekton-pipelines | grep manual-approval-gate lists the controller and webhook Pods in Running state.
  • ApprovalTask resources not created: Ensure the ManualApprovalGate CR still exists with READY=True. If it was deleted or is failing, reinstall it before users rerun pipelines.

When to enable. Deploy Manual Approval Gate when releases must record who approved them, for example before promotion into production. The controller and webhooks are cluster-scoped and serve every namespace, so the platform administrator installs one ManualApprovalGate CR for the whole cluster.

Recommended values. Create a single manual-approval-gate CR with spec.targetNamespace: tekton-pipelines, as shown in the Steps section, and change runtime settings only through spec.options. For the approval steps that pipeline authors add (see Manual Approval Gate for Tekton Pipelines), declare approvers as named users or groups (group:<name>) using the canonical identifiers described in User and group identifiers. Set numberOfApprovalsRequired according to the release policy (the usage example uses "1"); each approving group member counts as one approval. Size PipelineRun.spec.timeouts.pipeline and PipelineRun.spec.timeouts.tasks to cover the tasks that run before the approval step, the full approval window (the approval step timeout, for example "24h"), and the tasks that run after it: both are measured from the start of the PipelineRun (status.startTime), and timeouts.tasks covers all non-finally tasks (see the Timeout section of PipelineRuns). For example, 72h for both leaves 48 hours for the other tasks around a "24h" approval step. If you also set timeouts.finally, set timeouts.pipeline to at least timeouts.tasks plus timeouts.finally. If the PipelineRun times out while the approval step is pending, Tekton cancels the approval step, but the ApprovalTask stays pending until the approval timeout (the spec.timeout of the step's CustomRun, or 60 minutes when that field is empty) has passed since the ApprovalTask was created; then the controller marks it rejected and fails the CustomRun, although nobody rejected it. Check the PipelineRun status before you act on a pending approval; Manual Approval Gate for Tekton Pipelines describes which value the CustomRun holds. Read the approval record from status.approversResponse of the ApprovalTask. The ApprovalTask is deleted together with its PipelineRun. Tekton Results stores PipelineRuns, TaskRuns and CustomRuns but not ApprovalTask objects; the stored CustomRun of an approval step keeps its final state, not who approved, so export the record before the run is pruned if it must be kept longer.

Prerequisites. Alauda DevOps Pipelines v4.7.0 or later, and cluster-wide rights to create the ManualApprovalGate CR, such as cluster-admin (a namespace admin cannot create it). Approvers must be able to patch approvaltasks.openshift-pipelines.org resources in the namespaces where approval steps run. Approver user and group names must match the identifiers exposed by the platform's identity provider.

Learn More