Kubernetes Admission Request Processing

Kubernetes Admission Request Processing is the detailed mechanics of how a single API request flows through the admission control system, from the moment authorization succeeds to the moment the resulting object (or rejection) is returned to the caller. Understanding this processing sequence — the exact structure of the AdmissionReview object, the order of mutating versus validating steps, and how multiple plugins and webhooks compose — is necessary for anyone writing an admission webhook or diagnosing why a request was unexpectedly modified or rejected.

The AdmissionReview Object

Request and Response Structure

Every admission webhook receives an AdmissionReview object containing an AdmissionRequest — the operation type, the resource, the submitted object, the authenticated user, and any old object being replaced — and must respond with an AdmissionReview containing an AdmissionResponse indicating whether the request is allowed, and for mutating webhooks, a JSON Patch describing the desired modifications.

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "request": {
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
    "operation": "CREATE",
    "userInfo": { "username": "system:serviceaccount:payments:ci-deployer" },
    "object": { "apiVersion": "v1", "kind": "Pod" }
  }
}

Constructing a Response

A validating webhook returns a simple allowed: true or allowed: false with an optional status message; a mutating webhook additionally returns a base64-encoded JSON Patch specifying the exact changes to apply.

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
    "allowed": false,
    "status": { "message": "container must not run as root" }
  }
}

Ordering Within a Single Request

Mutating Phase First

All matching mutating admission plugins and webhooks run before any validating step, and because multiple mutating webhooks can apply in sequence, each one operates on the object as modified by every mutating webhook that ran before it — the final object entering the validating phase reflects the cumulative effect of the entire mutating chain.

Validating Phase Runs Once, Against the Final Object

Validating webhooks all receive the same, fully-mutated object; no further mutation is possible at this stage, and every matching validating webhook must return allowed: true for the request to proceed — a single rejection from any one validating webhook fails the entire request.

Re-Invocation for Mutating Webhooks

Because one mutating webhook's changes could invalidate assumptions another mutating webhook relied on, Kubernetes supports a reinvocationPolicy allowing certain mutating webhooks to be invoked again if a later webhook in the chain modified the object, ensuring earlier webhooks see the final state before the mutating phase concludes.

webhooks:
- name: default-resources.example.com
  reinvocationPolicy: IfNeeded

Object Version and Conversion Considerations

Matching apiVersions Correctly

A webhook's rule configuration specifies which apiVersions of a resource it intercepts; if a client submits a resource version the webhook does not list, the webhook is not invoked at all, which is a common source of policy gaps when a resource is later submitted through a newer or older API version than originally anticipated.

dryRun Requests

Requests submitted with --dry-run=server set dryRun: true in the AdmissionRequest; webhooks that perform side effects (writing to an external audit system, for instance) must check this field and skip those side effects during a dry run, since the request will never actually be persisted regardless of the webhook's response.

Timeout and Latency Within Processing

Cumulative Webhook Latency

Because every matching webhook in both phases is invoked sequentially (webhooks within the same phase can run concurrently, but the mutating phase must fully complete before the validating phase begins), the total added latency for a single request is the sum of the mutating phase's slowest concurrent path plus the validating phase's slowest concurrent path, which becomes significant as more webhooks are registered against overlapping resource types.

Handling Timeouts Gracefully

A webhook exceeding its configured timeoutSeconds is treated according to its failurePolicy; designing webhook services with response times well under their configured timeout, and monitoring for latency approaching that threshold, prevents transient slowness in a policy service from unpredictably blocking or allowing production traffic depending on failure policy.