Architecture: The Webhook Interceptor

How Gatekeeper Plugs Into Kubernetes

Gatekeeper doesn't run on your laptop or in your CI pipeline — it runs as a set of Pods inside the cluster itself. When you install Gatekeeper (via Helm or its manifest), it registers a ValidatingWebhookConfiguration object with the Kubernetes API Server. This is a built-in Kubernetes extension point that says: "Before finalizing any resource operation, call this URL first."

Here is the exact sequence of events when a developer runs kubectl apply -f bad-service.yaml:

1. Request arrives: The kubectl client sends the YAML to the Kubernetes API Server over HTTPS.
2. Authentication & Authorization: The API Server checks who you are (authn) and whether you're allowed to create this resource type (authz via RBAC). Gatekeeper has not been involved yet.
3. Admission phase begins: The API Server sees the registered webhook and pauses the request. It serializes the resource definition into a JSON payload called an AdmissionReview object and sends it to the Gatekeeper Pod via an internal HTTPS call.
4. Policy evaluation: Gatekeeper receives the AdmissionReview, extracts the resource definition, and runs it against all active policies (written in Rego). This happens in milliseconds.
5. Decision returned:
6. Allow: Gatekeeper responds with allowed: true. The API Server continues, writes the resource to etcd, and returns success to the developer.
7. Deny: Gatekeeper responds with allowed: false and a custom message (e.g., "Denied: LoadBalancers are prohibited in the dev namespace"). The API Server returns a 403 Forbidden error to the developer. Nothing is written to etcd.

What Happens If Gatekeeper Is Down?

This is a critical operational question. The ValidatingWebhookConfiguration has a failurePolicy field. If set to Fail (the default for Gatekeeper), and the webhook is unreachable, the API Server will deny all requests — a safe but potentially disruptive default. If set to Ignore, requests bypass the webhook when it's unavailable. Gatekeeper runs multiple replicas and uses a leader-election pattern to ensure high availability, but understanding this failure mode is essential for production operations.