Deploying Manual Approval Gate
TOC
Feature OverviewUse CasesPrerequisitesSteps1. Create theManualApprovalGate CR2. Verify controller health3. Reconfigure or force a rollout4. Uninstall Manual Approval GateOperation ResultsTroubleshootingRecommended SettingsLearn MoreFeature 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
optionscontract instead of editing manifests. - Cleaning up the feature when approval tasks are no longer required.
Prerequisites
Alauda DevOps Pipelinesv4.7.0 or later with cluster-admin access.kubectlconfigured against the target cluster.
Steps
1. Create the ManualApprovalGate CR
Save the manifest as manual-approval-gate.yaml and apply it:
spec.targetNamespacedetermines where controller deployments, webhooks, and ConfigMaps are created. We recommendtekton-pipelinesso 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, replacetekton-pipelineswith it in the commands and checks below.- Use
spec.optionsto 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
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:
-
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(2above); the second returns when the rollout is complete and printsdeployment "manual-approval-gate-controller" successfully rolled out: -
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:
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:
Then delete the CR and check that its Deployments are gone:
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 manualapprovalgatesshows the instance withREADY=True,VERSION=<release>, and an emptyREASON. TheREASONcolumn shows the message of theReadycondition, which is empty when the instance is ready.kubectl get pods -n tekton-pipelines | grep manual-approval-gatelists controller and webhook pods inRunningstate.- After deletion,
kubectl get pods,services -n tekton-pipelines | grep manual-approvalprints nothing, and theapprovaltasks.openshift-pipelines.orgCRD and everyApprovalTaskhave been deleted. Recreating the CR installs the CRD again.
Troubleshooting
ManualApprovalGateCR showsREADYFalse: TheREASONcolumn shows the message of theReadycondition, for exampleInstaller set not ready: <message>. Runkubectl describe manualapprovalgate manual-approval-gateto check events, then review Operator logs (kubectl logs -n tekton-operator deploy/tekton-operator --all-containers). Mis-typed fields inspec.optionsor 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-gatelists the controller and webhook Pods inRunningstate. ApprovalTaskresources not created: Ensure theManualApprovalGateCR still exists withREADY=True. If it was deleted or is failing, reinstall it before users rerun pipelines.
Recommended Settings
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.