gator test: Test Gatekeeper Constraints Offline
gator test runs Gatekeeper ConstraintTemplates and Constraints against Kubernetes resources locally, printing any violations and exiting non-zero when they occur.
If your cluster enforces policy with OPA Gatekeeper, gator test lets you run those exact ConstraintTemplates and Constraints in CI. A manifest that Gatekeeper would reject at admission fails the PR instead.
What it does
gator test reads a stream of Kubernetes objects (ConstraintTemplates, Constraints, and the resources to check) from stdin or files, compiles the templates, and evaluates the constraints. It reports each violation with the constraint name and message and exits non-zero if any resource is denied.
Common usage
# feed templates, constraints, and resources together
cat template.yaml constraint.yaml deployment.yaml | gator test
# from a directory (via find/cat) with JSON output
cat policy/*.yaml manifests/*.yaml | gator test --output json
# explicit filenames
gator test -f template.yaml -f constraint.yaml -f deployment.yamlOptions
| Flag | What it does |
|---|---|
| -f, --filename <path> | Input file or directory; repeatable |
| stdin | Read a YAML stream of objects when no -f is given |
| -o, --output <fmt> | Output format: default (yaml-ish), json |
| --include-trace | Include Rego evaluation trace for debugging |
| --image <ref> | Pull a bundle of policies from an OCI image |
In CI
Vendor the same ConstraintTemplates and Constraints your cluster applies, concatenate them with the manifests under review, and pipe into gator test. Because it runs the identical Rego Gatekeeper uses, local and admission verdicts match, closing the gap where a PR passes CI but fails at deploy.
Common errors in CI
A denied resource prints a violation line such as "Deployment <name>: <constraint message>" (for example "you must provide labels: {app.kubernetes.io/name}") and the process exits non-zero. "error creating client" or "no ConstraintTemplate found" means you forgot to include the template in the input stream. A Rego compile error surfaces as "failed to create template" with the underlying rego_parse_error.