What does Gatekeeper's audit controller do, and where does it write what it finds?

## Two loops over the same rules Gatekeeper enforces policy in two places, and they are separate processes with separate failure modes. The **admission webhook** is synchronous and per-request: the API server calls it while a create or update is in flight, and the answer decides whether that write lands. It sees exactly one thing — the object being written. The **audit controller** is asynchronous and periodic. It ships as its own deployment (a single replica by default, separate from the webhook pods) and its job is the opposite one: take the objects that are *already* in the cluster and check them against the rules as they stand today. Nothing is being written when audit runs; nothing is waiting on its answer. ## What a sweep actually does On each cycle — the period comes from `--audit-interval`, 60 seconds by default, and setting it to `0` disables audit entirely — the controller walks the Constraints currently installed, works out which kinds they match, reads those objects, and evaluates each one against the matching Constraint's rule. The result is a set of violations per Constraint. A Constraint whose `enforcementAction` is `dryrun` is audited exactly like an enforcing one. Dryrun only tells the *webhook* not to deny; it does not tell audit not to look. That combination — a rule that blocks nothing while its status fills up with findings — is the normal first phase of introducing a new rule. ## Where the findings land There is no central report object. Each Constraint carries its own results in its own `status`: - `violations` — a list of entries, each with the offending object's `kind`, `name` and `namespace`, the `enforcementAction` in force, and the `message` the rule produced. This list is **capped**; it is a sample, not an inventory. - `totalViolations` — the count the sweep found, reported separately from that capped list. - `auditTimestamp` — when the results were last refreshed. Everything in the status is as of that moment, not as of now. - `byPod` — per-pod bookkeeping, since more than one Gatekeeper pod may report status. If two Constraints match the same object, each records its own violation on its own status. To see everything audit found you read every Constraint. ## What audit does not do It does not enforce. It does not evict a running Pod, it does not delete a PersistentVolumeClaim, and it does not mutate anything into compliance. It also does not notify: a `status` field is not an alert, and nothing watches it unless you build that. A Constraint can sit in dryrun for a quarter with hundreds of findings recorded and no human ever look. It is also not continuous. Between sweeps the picture is stale by up to one interval, and if the audit pod is down or a sweep errored partway, the status simply keeps the last numbers it managed to write — old results look identical to fresh ones apart from the timestamp. ## What it costs A sweep is not free. Reading every object of every constrained kind, every interval, is real load on the API server and real memory in the audit pod on a large cluster. Gatekeeper gives you dials for this: lengthen `--audit-interval`, restrict the sweep to kinds some Constraint actually matches with `--audit-match-kind-only`, page the reads with `--audit-chunk-size`, or evaluate a replicated cache instead of the live API with `--audit-from-cache`. On small clusters the defaults are invisible; on a cluster with hundreds of thousands of objects, audit is often the most expensive thing Gatekeeper does. ## The example to carry You write a rule that PersistentVolumeClaims must name a StorageClass from an approved, encrypted-at-rest set. At admission, that rule affects exactly one population: claims created from now on. Meanwhile four hundred claims already exist, and several teams' data sits on them. Audit is the half of Gatekeeper that can tell you anything about those four hundred: after one interval, the Constraint's status carries a total and a sample of names. Nothing has moved, nothing has broken, and you now have a number to plan against — which is precisely the value, and precisely the limit, of a detective control.