Enable Proxy Permission Checks and Approval Gating
The recommended settings in Connectors Proxy keep the tools' long-lived credentials out of pipelines with the default feature flag settings: workloads reach the tools through Connectors Proxy with a short-lived token, and read (get) permission on a Connector is enough to use it. This guide adds two optional controls on top of that setup:
- Proxy permission checks (
enable-connector-proxy-permissions): using a Connector throughConnectors Proxyrequires theconnectors/proxypermission, not only read permission on the Connector. - Approval gating (
enable-connectors-approval): a sensitive Connector is released to a workload only after the checks of anAccessPolicypass, for example an approved TektonApprovalTaskin the samePipelineRun.
For the concepts, see Connectors Permission Model and Connectors Approval & Permission Gating.
TOC
When to UsePrerequisitesStepsStep 1: Prepare Grants for Connectors Not Behind ApprovalStep 2: Enable Approval GatingStep 3: Create the AccessPolicy ResourcesStep 4: Enable Proxy Permission ChecksVerifyRoll BackWhen to Use
Use this guide when the use of Connectors through Connectors Proxy must be governed by platform permissions, or when sensitive Connectors, such as a production registry, may be used only after approval.
Consider the impact before you start:
- Both flags default to
"false". They live in one shared ConfigMap and apply to the whole Connectors installation, not to a single Connector or project (see Feature Flags). Enable the two flags together. - With
enable-connectors-approvalenabled, read permission on a Connector is no longer enough to mount it. The CSI Driver checks theconnectors/proxypermission with verb*; a grant of onlygetonconnectors/proxydoes not satisfy it. A mount without that permission contains only a.error.jsonfile, so the workload fails instead of receiving configuration. - With
enable-connector-proxy-permissionsalso enabled, the proxy applies the same check to every request. - Every workload that mounts Connectors is affected, so prepare the grants first and follow the order in Steps.
Prerequisites
-
The
ConnectorsCorecomponent is installed. It creates theconnectors-configConfigMap that stores the flags. -
You can edit the
ConnectorsConfigresource.ConnectorsConfigis a cluster singleton, so do not create a second one. Find the existing resource and its namespace: -
Pipelines run under named ServiceAccounts, so that grants and
AccessPolicyresources can bind them. -
Workloads mount Connectors through the Connectors CSI Driver.
-
For approval with the built-in
connectors-approvals-in-pipelinecheck, each pipeline that uses an approval-gated Connector has a TektonApprovalTaskin the samePipelineRun, before the task that mounts the Connector.
Steps
Follow this order. Mounts change behavior as soon as enable-connectors-approval is enabled, and the AccessPolicy admission webhook rejects new AccessPolicy resources while that flag is disabled. So the grants that do not depend on AccessPolicy come first, and the AccessPolicy resources follow the flag immediately.
Change the flags only in ConnectorsConfig, as described in Update a Feature Flag. Do not edit the connectors-config ConfigMap or the managed ConnectorsCore resource directly. In the commands below, replace <name> and <namespace> with the values from kubectl get connectorsconfig -A.
Step 1: Prepare Grants for Connectors Not Behind Approval
List the ServiceAccounts that mount Connectors which will not be behind approval. Grant each of them the connectors/proxy permission with verb * on those Connectors, in addition to the read permission they already have. A grant of only get on connectors/proxy does not satisfy the CSI check.
Kubernetes RBAC grants can be created at any time. For example, the following Role and RoleBinding, created in the namespace of the Connector, let the builder ServiceAccount of <workload-namespace> use the <connector-name> Connector:
Do not grant connectors/proxy on Connectors that will be behind approval. A workload that already has the connectors/proxy permission for a Connector needs no AccessRequest (see AccessRequest), so approval would not gate it. Workloads that mount approval-gated Connectors are authorized through the approval check of the AccessPolicy you create in Step 3, so their mounts fail until that AccessPolicy exists.
Step 2: Enable Approval Gating
Set enable-connectors-approval to "true":
From now on, a mount without the connectors/proxy permission contains only .error.json. Continue with Step 3 right away, and do not start runs that mount approval-gated Connectors until it is done.
Step 3: Create the AccessPolicy Resources
Create the AccessPolicy resources in the namespaces of the Connectors they protect.
For each sensitive Connector:
-
Find and remove the default and direct
connectors/proxygrants that cover it: RBAC grants such as the ones in Step 1, andspec.defaultPermissionof anyAccessPolicythat matches it.spec.defaultPermissiongrants proxy access immediately, without any approval check (see AccessPolicy). Approval gates a Connector only when nothing else grants proxy access to it. -
Create an
AccessPolicywhose approval check setsapprovers, maintained by administrators. Withoutapprovers, any approvedApprovalTaskin thePipelineRunis sufficient, so a user who can create or modify the pipeline can set theApprovalTaskapprovers and approve the run. See Restricting Who Can Approve.For example, the following policy releases the
prod-harborConnector only after a member of therelease-managersgroup approves:
For project-level Connectors that the pipelines of a project use without approval, you can now grant proxy use per project with an AccessPolicy in the namespace of the Connectors, instead of the RBAC grants from Step 1. Bind the pipeline ServiceAccounts through a cpaas.io/project namespace selector (see AccessPolicy). That selector matches only the member namespaces of the project; the project's own namespace carries the cpaas.io/inner-namespace label instead (see Connector Resource Levels and Permissions). If workloads also run in the project namespace, bind them explicitly with a second serviceAccounts entry whose namespaceSelector.names lists that namespace:
Do not match an approval-gated Connector with such a policy.
Before you rely on spec.defaultPermission, make sure that each ServiceAccount it binds already has get permission on Connectors in the namespace of the Connector; a grant limited to specific Connector names is not enough. ServiceAccounts without it are left out of the generated RoleBinding while the AccessPolicy still reports Ready, and only the controller log records the skipped subject.
Step 4: Enable Proxy Permission Checks
Set enable-connector-proxy-permissions to "true":
The proxy then applies the same connectors/proxy check to every request.
Verify
- Run a pipeline that mounts a Connector which is not behind approval. The mount contains the configuration files.
- Run a pipeline that uses an approval-gated Connector. While its
ApprovalTaskis pending, the task that mounts the Connector waits. After a designated approver approves, the mount contains the configuration files.
An unauthorized mount contains only .error.json, and the workload fails later because it has no configuration. When an ApprovalTask is rejected, the tasks that run after it in the PipelineRun do not run. To find the cause of an unauthorized mount:
- List the mount path with
ls -Aand read.error.json. - Check the events of the Pod with
kubectl describe pod <pod-name> -n <workload-namespace>. - Check the conditions of the
AccessRequestfor the Pod. ReasonNoAccessPolicyMatchedon theAccessPolicyMatchedcondition means that noAccessPolicymatched the request, so the workload has no grant for the Connector. For the other conditions and reasons, see AccessRequest and Connectors Approval & Permission Gating.
Roll Back
Set both flags back to "false" in ConnectorsConfig:
With both flags disabled, the approval flow is not active and read permission on a Connector is again enough to use it through Connectors Proxy. Approval-gated Connectors are then usable by any workload with read permission on them, so review who has read permission on sensitive Connectors before you roll back.