Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Admission Webhooks

Kubernetes Admission Webhooks are HTTP callbacks that let cluster operators mutate or validate API-server requests through runtime-configured policy services.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, admission control, webhooks, policy, AI infrastructure

Definition

Kubernetes Admission Webhooks are dynamic admission-control extensions for the Kubernetes API server. The Kubernetes dynamic admission-control documentation defines admission webhooks as HTTP callbacks that receive admission requests. It names two kinds: mutating admission webhooks, which can modify submitted objects, and validating admission webhooks, which can reject requests after mutation and API-server validation are complete.

Admission control sits after authentication and authorization and before object persistence. The Kubernetes admission-controller reference says admission controllers apply to requests that create, delete, or modify objects, and can also block some custom verbs such as API-server proxy connections. It also says admission controllers cannot block ordinary read operations such as get, watch, or list.

How It Works

Admission webhooks depend on the MutatingAdmissionWebhook and ValidatingAdmissionWebhook admission controllers and on the admissionregistration.k8s.io/v1 API. Operators configure them with MutatingWebhookConfiguration or ValidatingWebhookConfiguration objects. The dynamic admission guide says those configuration objects let operators choose which resources are sent to which webhooks.

The matching rules specify operations, API groups, API versions, resources, and scope. A webhook can also use namespace selectors, object selectors, match policy, and match conditions. matchPolicy: Equivalent is the documented default and lets the API server convert equivalent resource versions before sending the request to the webhook.

The API server sends an AdmissionReview request to the webhook service or URL described in clientConfig. Webhooks respond with an AdmissionReview response, copying the request UID and setting allowed true or false. The API reference says admissionReviewVersions is an ordered list of versions the webhook expects, and failurePolicy controls whether webhook call errors are ignored or cause admission to fail. The default failure policy is Fail. timeoutSeconds ranges from 1 to 30 seconds and defaults to 10 seconds.

Mutating webhooks run before validating admission. They must be idempotent, because they can be invoked again after earlier mutations. A validating webhook is the safer place to enforce policy that must see the final object state.

Agent Context

AI infrastructure often creates Kubernetes objects quickly: batch evaluation Jobs, model-serving Deployments, sandbox Pods, tool gateways, route objects, and temporary workers. Admission webhooks can enforce boundaries at that point of creation. They can block missing labels, unsafe images, overbroad ServiceAccounts, forbidden hostPath mounts, unapproved GPU classes, or public routes to internal model endpoints. Mutating webhooks can add defaults, labels, sidecars, node selectors, runtime classes, or other controlled fields.

The control is powerful because it sits between intent and persistence. A human, controller, CI system, or agent may submit a manifest, but the API server pauses before storing it and asks the configured policy service whether the object should change or proceed.

Governance Use

A governance-grade webhook record should preserve the webhook configuration name, type, rules, selectors, match conditions, client configuration, CA bundle source, admissionReviewVersions, sideEffects setting, timeoutSeconds, failurePolicy, reinvocationPolicy for mutating webhooks, owner, code version, deployment namespace, service account, audit annotations, metrics, and test fixtures. For AI workloads, the record should also identify which resources represent model serving, agent tools, retrieval systems, evaluation jobs, or administrative automation.

The review question is whether the webhook expresses a clear policy boundary. What does it block? What does it mutate? Does it fail closed or open? Can operators explain which requests are exempt? Are warning messages, rejection reasons, audit annotations, and metrics retained long enough for incident review?

Limits

Admission webhooks are not a substitute for RBAC, runtime isolation, image signing, network policy, audit logging, or human approval. They only see admission requests that match their rules. They do not observe every action inside a running container, every model prompt, every API call from an agent, or every read of existing cluster state.

They also become part of the control plane's reliability and trust boundary. The Kubernetes guide warns that admission webhooks are essentially part of the cluster control plane and should be written and deployed with caution. Slow, unavailable, overbroad, or side-effecting webhooks can create outages, bypasses, or hard-to-debug policy behavior.

Source Discipline

Claims about admission phases, dynamic webhook configuration, AdmissionReview fields, matching, side effects, timeouts, reinvocation, and failure policy should cite Kubernetes documentation. Claims about Gatekeeper, Kyverno, service mesh injection, cloud-provider policy products, or AI-specific policy engines should cite those implementation sources separately.

The local evidence should include configuration manifests, webhook server version, deployment path, TLS configuration, policy tests, rejected-request samples, audit events, Prometheus metrics, and incident rollback instructions.

Spiralist Reading

Spiralism reads the admission webhook as a gate where machine intention becomes infrastructure fact.

The manifest is only a proposal until the control plane accepts it. Good governance makes that acceptance conditional, logged, narrow, and intelligible.

Sources

Return to Wiki