Introduction to OPA Gatekeeper and Rego

OPA makes decisions, Rego describes the rules, and Gatekeeper connects both to Kubernetes. You send two sample workloads through the API server and follow when the admission webhook evaluates them and when the audit controller checks resources already stored. An architecture map connects the request path, Gatekeeper components, ConstraintTemplate, and constraint into one understandable model.

Rego describes desired results rather than an imperative sequence of steps. You read a Kubernetes object through input, use if and contains to create a clear violation rule, and test an allowed, violating, and malformed case. opa fmt, opa check --strict, and opa test --fail-on-empty provide immediate, verifiable feedback.

Kubernetes manifests contain nested objects and lists that a single condition rarely covers completely. You extend your rule with iteration, sets, negation, and a helper rule. Test resources with present, missing, and irrelevant fields expose the difference between false, undefined, and an evaluation error. A result table records the expected and actual decision side by side.

A ConstraintTemplate turns tested Rego logic into a reusable Kubernetes policy type. You transfer your rule into the explicit Rego v1 engine, define a structural OpenAPI parameter schema, and apply the template to the cluster. Ingestion status and the generated CRD show whether code and schema were accepted. One deliberately invalid parameter proves that the API server checks its type.

A constraint applies the same template with concrete parameters and a defined scope. You create two constraints for different teams and limit kinds, scope, namespaces, exclusions, and selectors. Allowed, violating, and deliberately unmatched workloads reveal whether the rule targets the right resources. The comparison exposes the separation between reusable logic and cluster-specific configuration.

Admission evaluates new changes, while audit finds violations in resources already stored. You apply the same policy to one new and one existing workload and compare the admission response, constraint status, logs, and metrics. This reveals when a request can be blocked, which information audit does not have, and why constraint status is not a complete violation history.

Some rules must compare a new object with resources already in the cluster, such as detecting duplicate Ingress hosts. You synchronise only the required data into Gatekeeper's inventory and extend the policy with that comparison. A delayed data state exposes the effects of eventual consistency. You then document data scope, permissions, and the risk of deciding from a stale view.

An exception that is too broad can make a correct policy ineffective. You bound a break-glass case through matching and exclusion and record its owner, approval, expiry date, and removal test in the repository. The same rule then moves through dryrun, warn, and deny. Requests inside and outside the exception plus a rollback show whether scope and rollout behave as intended.

Different tools expose different policy errors. opa test checks the Rego logic, Regal reports style and quality issues, and gator evaluates the template, constraint, resources, and inventory together. You build a version-pinned suite with allowed, violating, malformed, and unmatched cases. One deliberately incorrect expectation must fail before the suite counts as effective.

A policy change must be reviewable in a pull request without a spoken explanation. You organise the requirement, template, constraints, fixtures, tests, exception, and rollback in the repository and let the CI pipeline evaluate the change. You then create a deliberate live deviation. The GitOps diff, review, and pipeline result show how desired state is restored and a faulty policy is reversed.

Gatekeeper validates with Rego or CEL constraints but mutates through separate CRDs. You map the stable v1 resources AssignMetadata, Assign, and ModifySet to suitable tasks while explicitly treating AssignImage as a v1alpha1 API. Across sample objects, you define operations, applyTo, scope, and paths so that existing values are respected and repeated evaluation converges.

You now use the stable mutators to implement three bounded changes: a new annotation, a non-destructive default, and a list extension. Workloads with existing values reveal what Gatekeeper preserves. A second mutator then creates a deliberate conflict. Repeated evaluation, status, and logs help you distinguish schema, convergence, and conflicting policy intent and correct the relevant cause.

Two separate comparisons prevent false equivalence. For validation, you implement the same object-local requirement as Rego and CEL ConstraintTemplates and as a native ValidatingAdmissionPolicy. For mutation, you compare Gatekeeper's stable mutator resources with the CEL-based MutatingAdmissionPolicy. A decision matrix contrasts policy language, enforcement point, audit, data access, testing, and operational effort.

External Data includes information beyond the admission request; ExpansionTemplate can bring generated workload resources such as Pods into validation. For each capability, you inspect one successful and one failing path and assess the provider, TLS, timeout, cache, failure policy, and coverage. The outcome is a reasoned adoption decision, not a complete provider or production implementation.

Gatekeeper operates fail-open by default; only a failurePolicy deliberately set to Fail can block matching API requests when the webhook is unreachable. In an isolated failure, you inspect endpoints, certificates, logs, and metrics. You then disable the affected webhook configuration through the Kubernetes API, fix the cause, and enable it again. Smoke requests and a runbook demonstrate a safe restart.