--- title: "How to Install OPA Gatekeeper on Kubernetes with Helm" description: "Install OPA Gatekeeper with Helm, write Rego constraint templates, audit existing resources in dryrun mode and block privileged pods and untrusted registries." category: "Container Security" language: en source: https://cubepath.com/docs/container-security/open-policy-agent-gatekeeper-installation updated: 2026-09-25 --- # How to Install OPA Gatekeeper on Kubernetes with Helm OPA Gatekeeper is a Kubernetes admission controller built on Open Policy Agent. It checks every object sent to the API server against policies you write in the Rego language and rejects the ones that break them, for example namespaces without an owner label, privileged pods or images from unknown registries. In this tutorial you will install Gatekeeper with Helm, write three policies, audit the resources that already exist in `dryrun` mode, and then switch the policies to enforcement. ## Prerequisites To follow this tutorial you need: - A Kubernetes cluster running a currently supported version, such as a CubePath managed Kubernetes cluster or any other conformant cluster. - `kubectl` configured with cluster-admin permissions. - Helm 3 installed on the machine where you run `kubectl`. - `jq`, used to read audit results (`sudo apt install -y jq` on Ubuntu). Use a test cluster first. An incorrect policy in `deny` mode can block deployments cluster-wide. ## How Gatekeeper policies work Gatekeeper splits a policy into two objects: - A **ConstraintTemplate** contains the Rego logic and defines a new resource kind, for example `K8sRequiredLabels`, with the parameters it accepts. - A **Constraint** is an instance of that kind. It says which resources the policy applies to (`match`), with which parameters, and what happens on a violation (`enforcementAction`). `enforcementAction` accepts three values: | Value | Effect on new requests | Reported by audit | |---|---|---| | `dryrun` | Allowed | Yes | | `warn` | Allowed, `kubectl` prints a warning | Yes | | `deny` | Rejected | Yes | Besides checking new requests, Gatekeeper's audit controller periodically evaluates existing resources and records violations in each constraint's status. That is how you find out what would break before you enforce anything. ## Step 1 - Installing Gatekeeper with Helm Add the official chart repository: ```bash helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts helm repo update ``` Install Gatekeeper into its own namespace: ```bash helm install gatekeeper gatekeeper/gatekeeper \ --namespace gatekeeper-system --create-namespace ``` Wait for the controller and the audit deployment to become ready: ```bash kubectl -n gatekeeper-system rollout status deploy/gatekeeper-controller-manager kubectl -n gatekeeper-system rollout status deploy/gatekeeper-audit kubectl -n gatekeeper-system get pods ``` ```output NAME READY STATUS RESTARTS AGE gatekeeper-audit-6d8c9f7b5c-x2kqm 1/1 Running 0 60s gatekeeper-controller-manager-7f5c6b8d4f-4hj9l 1/1 Running 0 60s gatekeeper-controller-manager-7f5c6b8d4f-9wz2t 1/1 Running 0 60s gatekeeper-controller-manager-7f5c6b8d4f-t7m8p 1/1 Running 0 60s ``` Confirm that the admission webhook is registered with the API server: ```bash kubectl get validatingwebhookconfigurations gatekeeper-validating-webhook-configuration ``` The Helm chart exempts the `gatekeeper-system` namespace from its own policies, so a bad policy cannot lock Gatekeeper out. ## Step 2 - Requiring labels on namespaces The first policy requires every namespace to carry `team` and `environment` labels, so ownership is always known. Create the template, which is the standard example from the Gatekeeper documentation: ```bash nano k8srequiredlabels-template.yaml ``` ```yaml apiVersion: templates.gatekeeper.sh/v1 kind: ConstraintTemplate metadata: name: k8srequiredlabels spec: crd: spec: names: kind: K8sRequiredLabels validation: openAPIV3Schema: type: object properties: labels: type: array items: type: string targets: - target: admission.k8s.gatekeeper.sh rego: | package k8srequiredlabels violation[{"msg": msg, "details": {"missing_labels": missing}}] { provided := {label | input.review.object.metadata.labels[label]} required := {label | label := input.parameters.labels[_]} missing := required - provided count(missing) > 0 msg := sprintf("missing required labels: %v", [missing]) } ``` `input.review.object` is the object being created or updated, and `input.parameters` holds the values from the constraint. Each time the `violation` rule produces a result, the request is in violation. Apply it and check that Gatekeeper created the new kind: ```bash kubectl apply -f k8srequiredlabels-template.yaml kubectl get constrainttemplate k8srequiredlabels ``` ```output NAME AGE k8srequiredlabels 5s ``` Now create a constraint that applies the template to namespaces, starting in `dryrun` mode. System namespaces are excluded because you do not control their labels: ```bash nano ns-require-owner.yaml ``` ```yaml apiVersion: constraints.gatekeeper.sh/v1beta1 kind: K8sRequiredLabels metadata: name: ns-require-owner spec: enforcementAction: dryrun match: kinds: - apiGroups: [""] kinds: ["Namespace"] excludedNamespaces: - "kube-*" - default - gatekeeper-system parameters: labels: ["team", "environment"] ``` ```bash kubectl apply -f ns-require-owner.yaml ``` ## Step 3 - Reviewing audit results The audit controller runs every 60 seconds by default. After a minute, see how many existing objects violate the constraint: ```bash kubectl get k8srequiredlabels ns-require-owner ``` ```output NAME ENFORCEMENT-ACTION TOTAL-VIOLATIONS ns-require-owner dryrun 3 ``` List the offending resources: ```bash kubectl get k8srequiredlabels ns-require-owner -o json | jq -r '.status.violations[] | "\(.name): \(.message)"' ``` ```output monitoring: missing required labels: {"environment", "team"} staging: missing required labels: {"environment"} web: missing required labels: {"environment", "team"} ``` Fix the existing namespaces before enforcing the policy, for example: ```bash kubectl label namespace monitoring team=platform environment=production ``` To see all constraints and their violation counts at once, run `kubectl get constraints`. ## Step 4 - Enforcing the policy Once `TOTAL-VIOLATIONS` reaches zero, or only lists namespaces you accept, change `enforcementAction: dryrun` to `enforcementAction: deny` in `ns-require-owner.yaml` and apply it again: ```bash kubectl apply -f ns-require-owner.yaml ``` Test it by creating a namespace without labels: ```bash kubectl create namespace test-no-labels ``` ```output Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [ns-require-owner] missing required labels: {"environment", "team"} ``` A namespace with the labels is accepted: ```bash kubectl apply -f - <<'EOF' apiVersion: v1 kind: Namespace metadata: name: test-labeled labels: team: platform environment: dev EOF ``` ```output namespace/test-labeled created ``` ## Step 5 - Blocking privileged containers A privileged container has almost full access to the node, so it should be the exception. This template checks regular containers, init containers and ephemeral debug containers of every pod: ```bash nano k8sprivileged-template.yaml ``` ```yaml apiVersion: templates.gatekeeper.sh/v1 kind: ConstraintTemplate metadata: name: k8sprivilegedcontainer spec: crd: spec: names: kind: K8sPrivilegedContainer targets: - target: admission.k8s.gatekeeper.sh rego: | package k8sprivilegedcontainer violation[{"msg": msg}] { c := input_containers[_] c.securityContext.privileged msg := sprintf("privileged container is not allowed: %v", [c.name]) } input_containers[c] { c := input.review.object.spec.containers[_] } input_containers[c] { c := input.review.object.spec.initContainers[_] } input_containers[c] { c := input.review.object.spec.ephemeralContainers[_] } ``` The constraint matches `Pod` objects. Deployments, StatefulSets and Jobs create their pods through controllers, and those pods pass through the same admission check, so matching pods covers every workload type: ```bash nano no-privileged.yaml ``` ```yaml apiVersion: constraints.gatekeeper.sh/v1beta1 kind: K8sPrivilegedContainer metadata: name: no-privileged-containers spec: enforcementAction: dryrun match: kinds: - apiGroups: [""] kinds: ["Pod"] excludedNamespaces: - "kube-*" - gatekeeper-system ``` ```bash kubectl apply -f k8sprivileged-template.yaml kubectl apply -f no-privileged.yaml ``` Check the audit results as in Step 3. CNI plugins, storage drivers and monitoring agents often run privileged in their own namespaces; add those namespaces to `excludedNamespaces` after reviewing them. Then switch to `deny`, apply, and test: ```bash kubectl run priv-test --image=busybox:1.37 --restart=Never \ --overrides='{"spec":{"containers":[{"name":"priv-test","image":"busybox:1.37","command":["sleep","60"],"securityContext":{"privileged":true}}]}}' ``` ```output Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [no-privileged-containers] privileged container is not allowed: priv-test ``` When a Deployment's pods are rejected, `kubectl apply` of the Deployment still succeeds, but no pods appear. The rejection is recorded in the ReplicaSet events, visible with `kubectl describe replicaset -l app=your_app`. ## Step 6 - Allowing images only from trusted registries The last policy only admits images whose name starts with an approved prefix, so workloads cannot pull arbitrary images from public registries: ```bash nano k8sallowedrepos-template.yaml ``` ```yaml apiVersion: templates.gatekeeper.sh/v1 kind: ConstraintTemplate metadata: name: k8sallowedrepos spec: crd: spec: names: kind: K8sAllowedRepos validation: openAPIV3Schema: type: object properties: repos: type: array items: type: string targets: - target: admission.k8s.gatekeeper.sh rego: | package k8sallowedrepos violation[{"msg": msg}] { c := input_containers[_] not allowed(c.image) msg := sprintf("image %v of container %v is not from an allowed registry", [c.image, c.name]) } allowed(image) { startswith(image, input.parameters.repos[_]) } input_containers[c] { c := input.review.object.spec.containers[_] } input_containers[c] { c := input.review.object.spec.initContainers[_] } ``` Create the constraint with your registry prefixes. Always end each prefix with `/`: without it, `registry.example.com` would also allow `registry.example.com.attacker.net/image`. ```bash nano allowed-repos.yaml ``` ```yaml apiVersion: constraints.gatekeeper.sh/v1beta1 kind: K8sAllowedRepos metadata: name: allowed-repos spec: enforcementAction: dryrun match: kinds: - apiGroups: [""] kinds: ["Pod"] excludedNamespaces: - "kube-*" - gatekeeper-system parameters: repos: - "registry.example.com/" - "ghcr.io/your_org/" ``` ```bash kubectl apply -f k8sallowedrepos-template.yaml kubectl apply -f allowed-repos.yaml ``` The check compares the image string exactly as written in the manifest. An image written as `nginx:1.27` does not start with `docker.io/`, so if you allow Docker Hub images you must list them in the form your manifests use, or require fully qualified names. Review the audit results, then switch to `deny` and test with an image from an unlisted registry: ```bash kubectl run repo-test --image=nginx:1.27 --restart=Never ``` ```output Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [allowed-repos] image nginx:1.27 of container repo-test is not from an allowed registry ``` ## Step 7 - Managing exceptions Keep exceptions in the constraint's `match` block so they are visible and reviewed like any other change: - `excludedNamespaces` skips named namespaces; it accepts a trailing `*` as a prefix wildcard. - `namespaces` limits the constraint to the listed namespaces only. - `namespaceSelector` selects namespaces by label, which lets teams opt in, for example with `matchLabels: {policy-enforcement: "true"}`. - `labelSelector` selects individual objects by their own labels. When all matchers are present, an object must satisfy each of them to be checked. Prefer narrow exceptions (one namespace) over weakening the Rego logic. ## Troubleshooting **Requests are not being rejected.** Check that the constraint uses `enforcementAction: deny`, that its `match` actually covers the resource and namespace, and that the template compiled. `kubectl get constrainttemplate k8sallowedrepos -o yaml` shows `status.byPod[].errors` if the Rego has a syntax error. **A constraint cannot be created: `no matches for kind`.** The template has not finished creating its CRD, or it failed to compile. Wait a few seconds after applying the template, check its status, and apply the constraint again. **Everything is blocked after a bad policy.** Switch the constraint back to `dryrun`, or delete it with `kubectl delete k8sallowedrepos allowed-repos`. Gatekeeper's own namespace is exempt, so it keeps running. **Audit shows no violations even though some exist.** The audit runs every 60 seconds and reports up to 20 violations per constraint by default; `TOTAL-VIOLATIONS` still shows the full count. Check the audit logs with `kubectl -n gatekeeper-system logs deploy/gatekeeper-audit --tail 50`. **Testing Rego before applying it.** The Gatekeeper project provides the `gator` CLI, which runs templates and constraints against sample objects locally, so you can test policies in CI before they reach the cluster. ## Conclusion Gatekeeper is now running in your cluster with three policies: required ownership labels on namespaces, no privileged containers, and images only from approved registries, each introduced in `dryrun`, cleaned up through audit results, and then enforced. The same workflow applies to any new policy. As next steps, explore the maintained policies in the Gatekeeper policy library before writing your own, add `gator` tests to the repository that stores your constraints, and manage templates and constraints through GitOps so every change is reviewed.