gatekeeper-library: a community policy set for Kubernetes admission control

A policy corpus, and the distinction that makes it usable

The OPA Gatekeeper Library is described as a community-owned library of policies for the OPA Gatekeeper project. The homepage is a documentation site, and the package is also listed on Artifact Hub as gatekeeper-policies. It is Apache-2.0 licensed and the repository carries a SECURITY.md, an AGENTS.md, a catalog.yaml and a go.work file alongside the library, src, mutation, scripts, website and artifacthub directories.

The library has two halves, and the documentation is careful to say that mutation policies are examples rather than ready to use. Validation policies are the main event. Gatekeeper validates cluster resources against validation policies, and the ones in this library are defined as ConstraintTemplates and Constraints. A ConstraintTemplate can be applied directly to a cluster, and Constraints are then applied on top to customise the policy to a specific need.

That two-object model is the whole design, and it is the reason the library is usable rather than merely demonstrative. A ConstraintTemplate is the reusable rule, expressed as a Rego policy plus a schema for its parameters. A Constraint is a small object that instantiates that template with your own parameter values, and it is the Constraint you keep in version control, because it is the part that differs between teams.

So the workflow is: pick a template that covers a rule you want, write a Constraint that sets the parameters for your cluster, and apply both. You are expected to end up with a directory of Constraints that belongs to you, and the library is the source you copy from.

The topic list names cncf, gatekeeper, opa, policy, policy-library, kubernetes and hacktoberfest, which is a fair summary of what this is: a policy corpus maintained in the open, with the maintainers and contributors spread across the Gatekeeper user base.

Installing with kustomize, and the path to a subset of policies

There are two documented installation routes, kustomize and kubectl, and the kustomize route is the one designed for teams that want their own constraints alongside the library's.

You create a kustomization.yaml listing the library as a remote resource:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- github.com/open-policy-agent/gatekeeper-library/library
# You can optionally install a subset by specifying a subfolder, or specify a commit SHA
# - github.com/open-policy-agent/gatekeeper-library/library/pod-security-policy?ref=0c82f402fb3594097a90d15215ae223267f5b955
- constraints.yaml

Two things are worth pulling out of that. The commented line shows that you can point at a subfolder instead of the whole library, and that you can pin a commit SHA with a ref parameter, which is the difference between a reproducible admission policy and one that changes under you. And the second resource is your own constraints.yaml, which lives in the same directory.

Your constraints go in a file called constraints.yaml in that same directory, and example constraints can be found in the samples folders. The whole thing is applied with:

kustomize build . | kubectl apply -f -

The kubectl route avoids kustomize entirely and is simpler for a single policy. Each directory under library/ contains a template.yaml and a constraint.yaml, and you apply them directly:

cd library/general/httpsonly/
kubectl apply -f template.yaml
kubectl apply -f samples/ingress-https-only/constraint.yaml
kubectl apply -f library/general/httpsonly/sync.yaml # optional: when GK is running with OPA cache

That last line is the one to understand. The sync.yaml file is optional and applies only when Gatekeeper is running with the OPA cache, because that cache needs to be told about the data the policy reads. It is a small detail that will otherwise produce a policy that evaluates against empty data.

Testing policies with gator before they reach a cluster

Every ConstraintTemplate in the library has a suite.yaml file that defines its test cases, and the documented way to exercise them is the gator CLI:

gatekeeper-library$ gator verify ./...

gator is downloaded from the Gatekeeper releases page, and the point of it is that a policy change can be checked without a cluster in the way. That matters more than it sounds. Admission policies are unusual in that a bug in one can block a deployment, and the failure arrives in the least convenient moment: a release pipeline, on a Friday, with a pod that should have scheduled.

The library is explicit about the contribution workflow, and the workflow is what tells you how these policies are meant to be maintained. A new policy should contain a constraint template named src/<policy-name>/constraint.tmpl with a description annotation and the parameter structure, if any, defined in spec.crd.spec.validation.openAPIV3Schema, and the template is rendered using gomplate.

Alongside the template come one or more sample constraints, each with an allowed example named example_allowed.yaml and a disallowed example named example_disallowed.yaml under library/<policy-name>/samples/<policy-name>, plus a kustomization.yaml and a suite.yaml under library/<policy-name>. The Rego source lives as src.rego with unit tests as src_test.rego in the corresponding directory under src/<policy-name>.

The allowed and disallowed pair is the interesting part. It is the executable statement of what the policy is supposed to do, and it is what makes the library a usable reference rather than a pile of Rego. If you are writing your own policy and you are not pairing an allowed case with a disallowed case, you are writing a test that cannot fail in a useful way.

The Makefile targets follow the same logic. make generate produces library/<policy-name>/template.yaml from the Rego source using gomplate, make generate-website-docs produces the markdown for the website, make generate-artifacthub-artifacts produces the Artifact Hub packages, and make generate-all does all of them. make validate runs the validation checks, currently on the directory structure of the website/docs directory, and make unit-test runs the tests in the scripts directory. The whole set runs with ./test.sh, and a single policy can be tested directly with opa test on its src.rego and src_test.rego files with the verbose flag.

Versioning per policy, and why a copied policy is a fork

The library has introduced versioning for its policies, and the guidelines are specific enough that they read like a contract with downstream users. The version lives in the constraint.tmpl annotation, and the rules are split by the kind of change.

A major version bump is required for a breaking change, and the examples given are updating the template Kind, updating an existing parameter schema, adding the requires-sync-data annotation to sync new data, or any other breaking change. A minor bump is required for a backward compatible change, such as adding a parameter or updating the Rego logic. A patch bump is required for a simple backward compatible change, such as a simple Rego fix or updated policy metadata.

There is a carve-out, and it is a sensible one. Sample constraints, mutations and expansion templates are provided as examples, and changes to them do not require a version bump. In other words, the parts you are meant to copy into your own repository carry a version, and the parts that exist to illustrate do not.

This is the most important operational fact in the repository for an adopter. Once you install a ConstraintTemplate from this library, you have taken a copy, and the copy does not update itself. If upstream makes a breaking change to a template you copied, your cluster keeps enforcing the old behaviour until someone notices. The version annotation is what makes that diffable, and a team that copies policies should treat the version number as something it records.

The project also pins the toolchain in the Makefile, which tells you what a tested environment looks like. Kustomize is at 5.7.1, Gatekeeper and gator are both at 3.21.0, gomplate is at 3.11.6, bats is at 1.12.0, and the Kubernetes version used for the integration cluster is 1.34.0 with kind at 0.29.0. The comment next to the kind version explains that the k8s version is pinned because the kind image availability lags k8s releases.

Where gatekeeper-library is the wrong choice

The first limitation is that these are examples, and the project says so for mutation policies. The same is effectively true of the validation policies even where the wording is softer: the library gives you a working rule and a sample Constraint, and the sample Constraint carries values chosen for the sample, not for your cluster. Applying a library Constraint without editing it means enforcing whatever the example author set, which may permit everything or nothing depending on the parameters.

The second is that a policy library is a snapshot of someone else's security decisions. The library is community-owned, which means many opinions went into it, and the versioning rules exist because those opinions change. A ConstraintTemplate that encodes a reasonable default for one organisation is an arbitrary rule for another, and the only way to know which it is for you is to read the Rego.

The third is the scope of the whole approach. Gatekeeper's admission webhook sits in the path of every create and update in the cluster. Once you install templates and constraints, a badly written constraint can reject legitimate workloads, and the failure appears as a scheduling error rather than as a policy error. That is a real operational cost of admission control in general, and the library does not reduce it, it only makes it easier to get started.

The fourth is the dependency on a specific ecosystem. This library is only useful if your cluster runs OPA Gatekeeper. A team using Kyverno, or validating with a cloud provider's own policy engine, or relying on the built-in Pod Security Admission, gets nothing from it, and the Rego, the ConstraintTemplates and the gator tooling are all wasted effort.

The fifth is the absence of tagged releases. The repository has no GitHub releases, so there is no version to pin for the library as a whole. You pin individual policies by their annotation, and you pin the source by commit SHA when you use kustomize, which is workable but puts the burden of tracking that SHA on whoever maintains the constraints.

Editorial conclusion

gatekeeper-library fits a Kubernetes platform team that wants a working reference for admission policy, since the policies arrive with sample constraints, unit tests and versioned templates that show how a ConstraintTemplate is meant to be written, and copying one is far cheaper than writing the first from scratch. It is the wrong choice for a team that wants out-of-the-box enforcement, because the project states that mutation policies are examples to customise, and it is the wrong choice if your cluster runs a validating setup that is not Gatekeeper. Before adopting it, apply one policy from library/general/httpsonly to a test cluster with kubectl, run gator verify against your own constraints, and read the versioning guidelines in the contribution notes, because the last push was on 2026-10-19 and each policy carries its own major, minor or patch version that you are expected to bump on change.

Frequently asked questions

Official sources

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