In a Gatekeeper ConstraintTemplate, what must the Rego produce to deny a request?

## What the contract actually is A ConstraintTemplate is a Kubernetes custom resource. Inside it, `spec.targets` holds one entry for the target `admission.k8s.gatekeeper.sh`, and that entry carries a `rego` block of policy source. When a Constraint built from that template matches an incoming request, Gatekeeper loads the Rego into its embedded OPA and evaluates **one rule by name**: `violation`. That rule is written as a *partial set* rule whose elements are objects: ``` violation[{"msg": msg}] { # body } ``` Every time the body holds, one object is added to the set. The decision is then trivially mechanical: | result | meaning | | --- | --- | | empty set | this constraint found nothing to complain about | | non-empty set | one violation per element, each with its own message | What happens *because* of a non-empty set — a hard denial, a warning, or a recorded-but-allowed result — is the Constraint's `enforcementAction`, not the rule's business. The rule's only job is to describe what is wrong. ## The two keys in each element `msg` is **required** and must be a string. It is the human sentence that comes back to whoever ran the write, and it is stored alongside the audit results. Build it with `sprintf` so it names the specific offender rather than restating the rule. `details` is **optional** and may be any object. It is the machine-readable half: the volume name, the container, the value that failed, the threshold it failed against. Dashboards and reporting jobs read `details` precisely because they should not be parsing English out of `msg`. ## Why it is a set and not a boolean A boolean can only say "this Pod is bad". A set says "these three volumes are bad, and here is which". The idiom is to iterate and let the body hold once per offender: ``` violation[{"msg": msg, "details": {"volume": vol.name}}] { vol := input.review.object.spec.volumes[_] vol.hostPath msg := sprintf("volume %v mounts a hostPath", [vol.name]) } ``` Here `vol.hostPath` is doing double duty: it is an existence check. If a volume has no `hostPath` field, that expression contributes nothing, the body does not hold for that iteration, and no element is added. Only the offending volumes produce messages. ## The failure mode you must internalise The contract is **silent on both ends**. A rule that never adds an element and a rule that is wired to the wrong field path look identical from outside: no violations, request admitted. Nothing in Gatekeeper tells you the rule you shipped is inert. Two habits follow from that, and interviewers listen for them: 1. Always exercise a new template against a manifest you *know* should fail, not only against a compliant one. A template that passes clean input proves nothing. 2. Prefer explicit iteration with `[_]` over clever one-shot expressions, because an iteration that yields nothing is easier to spot in a failing test than a nested field access that silently goes nowhere. ## Common shapes people get wrong - **Returning a boolean or a string.** `violation = true` is a complete rule, not a set of objects, and Gatekeeper gets nothing it can turn into a denial message. The rule looks written and behaves as if absent. - **Putting the message under the wrong key.** Only `msg` is the message. A `reason`, `message` or `error` key is just more of `details` from Gatekeeper's point of view, and the denial comes back without a useful sentence. - **One violation for the whole Pod.** Technically fine, operationally poor: the person who is blocked has to work out which of eight containers offended. - **Assuming the package must be called `violation`.** The package name is conventionally the template's kind lowercased, and it is arbitrary; the *rule* name is the fixed part of the contract. ## What the rule is allowed to look at The body may only read what Gatekeeper hands it — the object under decision and the matched Constraint's parameters. There is no reaching out mid-rule to fetch something else, so the whole rule reduces to: pattern-match the object, and for every place it violates the intent, emit a message that names the offender.