Your Gatekeeper Constraint is blocking system-namespace workloads — how do you scope or exempt it?

## Scoping is where Gatekeeper rules actually go wrong A Constraint that blocks the wrong thing is usually not a bad rule — it is a rule with no boundary. The `spec.match` block is the boundary, and its default is the dangerous one: **an empty match matches every object the webhook is sent**. ### The fields of a Constraint's match block - **`kinds`** — a list of `{apiGroups, kinds}` pairs. The core group is the empty string `""`. Without this, a rule written for Pods is evaluated against everything. - **`namespaces`** — an allowlist. If present, only these namespaces are in scope. - **`excludedNamespaces`** — a denylist applied on top. - **`labelSelector`** — a selector over the labels of the **object being admitted**. - **`namespaceSelector`** — a selector over the labels of the **namespace the object is in**. Mixing these two up is the classic scoping bug: you label namespaces `policy-tier=strict` and then write `labelSelector`, which looks at pod labels and matches nothing. - **`scope`** and **`name`** — narrow to cluster-scoped or namespaced resources, or to a named object. The same match block governs the periodic audit, not just admission, so narrowing it also narrows what shows up on the Constraint's status. ### Two different exemption mechanisms **Per-Constraint exclusion.** Add the namespace to that Constraint's `excludedNamespaces`, or scope by label. The request still reaches Gatekeeper and the engine still decides; it simply finds no match. This is the right tool when one rule is wrong for one place, and its great virtue is visibility: the exception is written on the object that carries the rule, so anyone reading the Constraint sees it, and it is a reviewable diff in the repository that owns the rule. **Engine-wide exemption.** Gatekeeper's `Config` resource carries a match list whose entries pair `excludedNamespaces` with a list of `processes` — audit, webhook, sync, mutation, or all of them. A namespace excluded from the webhook process is not evaluated by any Constraint at all. This is the right tool for namespaces that must keep working while the policy engine is broken or misconfigured: `kube-system`, the CNI and CSI namespaces, and Gatekeeper's own namespace. The cost is that this exemption is invisible from the rule. Someone reading a Constraint that says "all Pods" has no way to know a set of namespaces was carved out somewhere else entirely, so an engine-wide exclusion list has to be short, deliberate, owned and reviewed. ### Why system namespaces are a special case, not just another exclusion A Constraint that rejects, say, Pods without resource limits will happily reject a system component's Pod. If that component is on the path to recovering the cluster — or is Gatekeeper itself — you have built a rule that stops you from fixing the rule. Exempting the system namespaces from the engine is what keeps that failure recoverable, which is why it belongs at the engine level rather than being re-derived in every Constraint by someone who might forget. ### Diagnosing the live incident 1. Read the rejection message: it names the Constraint that fired, which tells you which object to look at. 2. Read that Constraint's `match`. Nine times out of ten it is empty, or it lists `kinds` but no namespace scoping. 3. Decide the blast radius: is this one namespace that should never have been in scope, or is the rule itself wrong? Excluding a namespace to make an alert stop, when the rule is genuinely correct there, converts a security control into a formality. 4. Apply the narrower match, or the engine-level exemption for a system namespace, and write down which one you chose and why. ### Scaling past a list of names Hand-maintained `namespaces` and `excludedNamespaces` lists rot: a new namespace is created, nobody adds it, and either it escapes the rule or it is blocked by surprise. The durable pattern is a namespace **label** that expresses intent — a tier, an environment, an opt-in — combined with `namespaceSelector` on the Constraint. New namespaces get the label from whatever creates them, and the rule's scope follows automatically instead of being edited after every incident. ### Common wrong answers - "Set it to dryrun until they fix it" — that turns off enforcement everywhere the rule applies, not just where it misfires. - "Delete the ConstraintTemplate" — that garbage-collects every Constraint built on it, cluster-wide. - "`labelSelector` matches namespace labels" — it matches the admitted object's labels; `namespaceSelector` is the one that reads namespace labels.