OPA & Gatekeeper

OPA's data document is the in-memory JSON tree of standing facts policies read as data.something, separate from the input being decided. Facts arrive as startup files, inside a bundle OPA polls for, or as pushes to its Data API.

Gatekeeper's audit controller periodically re-evaluates objects that already exist in the cluster against every enforced Constraint and records the violations in each Constraint object's own status field. It only reports: it never blocks, deletes or changes anything.

gator test evaluates Gatekeeper policy locally: you hand it ConstraintTemplates, their Constraints, and the Kubernetes objects to review, and it reports which object violated which constraint. It needs no cluster, no kubeconfig and no admission webhook.

A Gatekeeper Assign is a mutator: at admission it writes a value into a field of the incoming object, so the object is stored changed instead of rejected. A Constraint only inspects and denies.

Gatekeeper denies a request when the template's violation rule produces a non-empty set of objects, each carrying a msg string. An empty set means the constraint is satisfied. Each object may also carry an optional details object.

Gatekeeper's Config (spec.sync.syncOnly) and SyncSet objects choose which resource kinds are replicated into its in-memory cache. Those objects then appear to Rego under data.inventory, so a constraint can read cluster objects other than the one being admitted.

A ConstraintTemplate defines a reusable rule plus a schema for its parameters, and makes Gatekeeper generate a new custom resource kind. A Constraint is an instance of that kind: it switches the rule on, scoped and parameterised.

You POST to /v1/data followed by the document path, with a body of the form {"input": {...}} carrying the facts. OPA evaluates that document and replies 200 with {"result": <value>} - the value the rule produced.

Where the decision is computed. Embedded is an in-process function call with no network. A sidecar keeps the call on the pod's loopback. A shared server puts one OPA in every caller's path over the network.

Under input.attributes.request.http: method, path, headers with lowercased keys, and body as a string. The OPA Envoy plugin also adds three top-level conveniences: input.parsed_path, input.parsed_query and input.parsed_body.

Write a mask policy, by default at data.system.log.mask, returning JSON pointers into the log event such as /input/... OPA erases or replaces those fields before the entry leaves the process, and records which paths it erased.

Two things only: input.review, holding the resource under decision as input.review.object (and its previous version as oldObject on an update), and input.parameters, holding the matched Constraint's parameters. No other object, no cluster state, no history.

A failed bundle download or activation leaves the last activated bundle deciding, so OPA answers confidently on old policy. Compare the active revision in status and decision logs with the revision the service intended to serve.

Each OPA decision log entry is a JSON record of one policy evaluation: a unique decision_id, the queried policy path, the input document, the result returned, the bundle revision in force, and a timestamp.

OPA replays the Etag from its last successful bundle download as If-None-Match on the next poll. If the service answers 304 Not Modified, OPA skips the download and the activation and keeps serving the bundle it has.

PUT replaces the entire document at the given path, so anything previously under it is gone. PATCH takes a JSON Patch operation list and edits in place, changing only the paths those operations name.

A gator verify case can assert how many violations the object produced and what the violation message said, not merely that something was denied. That pins which rule fired and what a developer will be told when it does.

ModifySet. Assign writes the whole value at the location, so it would replace whatever drop list the author already had. ModifySet treats the list as a set and merges the new member in, leaving the existing entries alone.

A rule indexes data.inventory by scope, groupVersion, kind and name. An unsynced kind makes that lookup undefined, not false — so the surrounding logic decides whether the rule blocks everything or waves everything through.

deny rejects the request and returns the violation message. dryrun admits it and only records the violation on the Constraint's status. warn admits it too, but the API server returns a warning that the person applying sees immediately.

Because the document you queried is undefined: nothing produced a value, so there is no result field to return. Evaluation itself succeeded, which is why the status is still 200. An empty body is no decision - neither an allow nor a deny.

One rebuild and release per service. With Rego compiled into the binary there is nothing to push, so enforcement coverage follows ten release trains, and for a while some services enforce the new rule and some the old one.

Because input.attributes.request.http.path is the raw request target and still carries the query string, so the equality test against "/api/v1/orders" fails. Match input.parsed_path instead, which is query-free and percent-decoded.

Read what the running engine holds, not what the source of truth says: GET the approved list from that OPA and compare. A correct rule denying a newly approved value is a data-freshness failure, fixed on the data path.

Because the violations list in a Constraint's status is truncated, not complete: Gatekeeper stores at most --constraint-violations-limit entries per Constraint, 20 by default. The real count sits beside it in status.totalViolations, as of the last audit timestamp.

Use gator expand with an ExpansionTemplate: it renders the Pod a Deployment, Job or CronJob would produce, and gator test and verify then review that generated Pod. The false green is a Pod rule tested only on bare Pods.

A mutator that matches nothing fails silently, so work outward: confirm which object is actually admitted, then applyTo's group/version/kind, then the match block, then the location path and pathTests — and verify on a server-side dry-run of a real object.

Gatekeeper evaluates template Rego without http.send. A call during admission would put an outside service on every matching write's path and make results non-reproducible. Facts are pushed in instead: parameters, replicated objects, or an external data provider.

Replication lag. A Gatekeeper rule reads data.inventory, a watch-fed replica rather than a live query, so the NetworkPolicy existed in the API server but had not reached the cache when the decision was made.