OPA Gatekeeper: Kubernetes admission policy with constraints and audit

What Gatekeeper adds on top of plain OPA

Running OPA as a Kubernetes admission controller with the kube-mgmt sidecar is the pattern the README calls Gatekeeper v1.0. Gatekeeper keeps OPA as the policy engine but changes how policy reaches the cluster. Instead of loading Rego files into a sidecar, you install custom resource definitions and create Kubernetes objects that the controller reconciles into the policy engine.

The README lists what that buys: an extensible, parameterized policy library, CRDs for instantiating that library (constraints), CRDs for extending it (constraint templates), CRDs for mutation, audit, and external data support. The important word is parameterized. A constraint template defines the Rego and the schema of its parameters; a constraint is an instance of that template with concrete values. A cluster administrator can publish one template and let application teams create constraints that only fill in a parameter, without any team writing Rego or owning the controller.

The audience follows from that split. Platform and security teams that need a single enforcement point across many namespaces, and that want policy objects auditable through the Kubernetes API, are the intended users. A single team running one cluster with a handful of rules is not, and the README does not argue otherwise.

Constraint templates, constraints and the admission path

The repository layout shows where the pieces live. apis/ holds the CRD Go types, pkg/ holds the controller logic, config/ and deploy/ hold manifests, charts/ holds the Helm chart, and cmd/ holds the binaries. The Dockerfile builds a single Go binary called manager and runs it on a distroless static base image as user 65532:65532, with ENTRYPOINT ["/manager"]. That binary is the controller that watches the CRDs.

At admission time a request to the API server is sent to the Gatekeeper webhook. The controller evaluates the applicable constraints, which are the constraint objects whose match rules select the resource, using the Rego from the corresponding constraint template. A violation produces a denial with the message defined in the template, or a warning, depending on the enforcement action. Mutation runs in the same request path for the mutation CRDs.

Audit is the second path. The README lists audit functionality as one of the additions over sidecar OPA. Audit evaluates existing objects in the cluster against the same constraints, so resources created before a constraint existed are still reported. That is the mechanism that makes the constraint model workable: enforcement applies to new writes, and audit tells you what is already non-compliant.

The go.mod pins the engine to github.com/open-policy-agent/opa v1.17.1 and pulls in k8s.io/api, k8s.io/apiserver and k8s.io/client-go at v0.36.4, plus github.com/open-policy-agent/frameworks/constraint. Policy evaluation is therefore tied to the OPA version the release was built against, not to whatever OPA binary you happen to have installed.

Installing Gatekeeper and writing a first constraint

The README does not contain install commands. It says to check the installation instructions on the Gatekeeper website to deploy the components, and the Makefile shows the published image repositories: openpolicyagent/gatekeeper, openpolicyagent/gatekeeper-crds and openpolicyagent/gator, with matching ghcr.io/open-policy-agent/... names. Use the website's install page for the current manifest or Helm command rather than copying a version from this article.

Once the controller is running, the first real use is a constraint template plus a constraint. The policy library linked from the README holds ready-made constraint templates and sample constraints, so the usual first step is to take a template from there instead of writing Rego. A constraint is a normal Kubernetes object, so it is created with kubectl and validated by the CRDs the install step registered.

To see what is currently non-compliant without blocking anything, run an audit. The gator binary is built from the same repository (see gator.Dockerfile and the GATOR_REPOSITORY variables in the Makefile) and is intended for working with constraints outside the cluster, which is useful for checking a template before it reaches admission.

The Makefile defines GATOR_REPOSITORY ?= openpolicyagent/gator and GATOR_IMG := $(GATOR_REPOSITORY):latest, so the gator image is published alongside the controller. Building it locally is a Go build against the same module shown in go.mod.

Where Gatekeeper is the wrong choice

The admission webhook sits in the request path. If the controller is unavailable, requests that match its webhook rules are affected, which is why the failure policy and namespace exclusions on the webhook configuration matter as much as the Rego. The README does not document rollback, so there is no stated procedure for reverting a constraint that turned out to block legitimate workloads. Plan for that by testing constraints in audit or warn mode before enforcing them.

Kubernetes now ships ValidatingAdmissionPolicy, and this repository tracks it: the Makefile has GENERATE_VAP ?= true, GENERATE_VAPBINDING ?= true and SYNC_VAP_ENFORCEMENT_SCOPE ?= true, and demo/k8s-validating-admission-policy/ exists in the tree. If your rules are few, static and expressible in CEL, the built-in mechanism avoids running a second webhook at all. Gatekeeper's advantage is the parameterized template model, the library, mutation and audit, not admission control as such.

A third case is policy that has nothing to do with Kubernetes admission. Gatekeeper is a controller for a cluster; using it to police CI pipelines or cloud APIs is a different problem with different tools.

How Gatekeeper compares with Kyverno

Kyverno is the closest alternative in the same slot: a Kubernetes-native policy engine that also installs as an admission controller and also supports validation, mutation and reporting. The difference is the policy language. Kyverno policies are Kubernetes resources written in YAML with its own declarative rule syntax, so a cluster administrator never sees Rego. Gatekeeper keeps Rego as the evaluation language and wraps it: the constraint template holds the Rego and the parameter schema, and users create constraints.

That trade-off cuts both ways. Kyverno's YAML is easier to read for teams without Rego experience, but the expressiveness ceiling is the rule syntax. Gatekeeper inherits OPA's full language, and the go.mod shows OPA v1.17.1 as a direct dependency, so anything expressible in Rego is available inside a template. The cost is that someone has to write and maintain that Rego, and constraint templates are cluster-scoped objects with a schema that has to be versioned carefully.

If your organization already runs OPA for other decisions and wants one language across them, Gatekeeper keeps that consistency. If your team has never written Rego and your rules fit declarative YAML, Kyverno asks less of you.

Maintenance, release cadence and licence

The repository is not archived, and the last push was on 2026-09-21. Recent releases are v3.23.1 on 2026-08-27, v3.23.0 on 2026-07-09, and v3.24.0-beta.0 on 2026-07-13. The Makefile sets VERSION := v3.24.0-beta.0, so the tree is ahead of the latest stable tag, which is normal for a project that tags from a release branch.

Upgrade cost is dominated by two things. First, the CRDs: gatekeeper-crds is published as its own image, which means CRD updates are a separate step from the controller image, and skipping it can leave the controller expecting fields the API server will not accept. Second, the OPA version: the engine is pinned in go.mod, so a Gatekeeper upgrade can move the Rego language version underneath your templates. Check the release notes for the OPA version before upgrading a cluster with many templates.

The licence is Apache-2.0, declared in the LICENSE file at the repository root, with a NOTICE file alongside it. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. This is a description of the repository contents, not legal advice; if you redistribute the images or embed the code, have counsel read the NOTICE and the licence text.

Editorial conclusion

Adopt Gatekeeper when you need parameterized policy objects that cluster users can instantiate without writing Rego, plus audit of existing resources. Do not adopt it if a single validating admission policy covers your rule set, or if you cannot run a second admission webhook in the request path. Before rollout, read the install page on the Gatekeeper website, check the chart values in charts/, and confirm which OPA version the release you deploy was built against.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. open-policy-agent/gatekeeper on GitHub
3. Project website
4. README
5. Releases