What is the difference between a validating and a mutating admission webhook?

A mutating webhook can modify an object by returning a JSONPatch, and runs first in the admission chain. A validating webhook can only accept or reject an object and runs after all mutations are applied, so it sees the final form of the resource.

What does failurePolicy control?

failurePolicy decides what happens when the webhook is unreachable or returns an error. Fail rejects the request (fail closed), which is safer for security policies. Ignore allows the request through (fail open), which avoids blocking the cluster when the webhook is down.

Why does sideEffects matter for dry-run requests?

sideEffects declares whether the webhook mutates external state. For a dry-run request the API server only calls webhooks declared None or NoneOnDryRun, since a webhook with real side effects must not fire during a dry run. Set None if your webhook only inspects the object.

What is reinvocationPolicy on a mutating webhook?

reinvocationPolicy controls whether a mutating webhook is called again after other webhooks in the same round modify the object. IfNeeded re-invokes it so it can react to later changes; Never calls it at most once per admission. Webhooks must be idempotent if set to IfNeeded.

How does matchPolicy affect which requests are intercepted?

matchPolicy decides how rules match API requests sent via different API versions or groups. Equivalent matches a request if any equivalent resource version matches the rules, catching requests to aliased versions. Exact only matches the literal group, version and resource listed in the rules.

Kubernetes Admission Webhook Operations

Kubernetes admission webhook operations

Admission webhooks let you intercept requests to the Kubernetes API server after authentication and authorization but before persistence. A MutatingWebhookConfiguration can change objects; a ValidatingWebhookConfiguration can only allow or deny them. Both are configured through a shared set of fields — rules, failurePolicy, sideEffects, namespaceSelector, timeoutSeconds, and more. This reference explains each field and its allowed values.

Filter the fields below to find the right key and what its values mean.

How it works

When a request arrives, the API server evaluates each configured webhook whose rules (operations, apiGroups, apiVersions, resources) and selectors match. Mutating webhooks run first, in an order that may re-invoke them per reinvocationPolicy; each returns an admission response that may include a base64-encoded JSONPatch. After all mutations, validating webhooks run against the final object and can only return allowed true/false.

The webhook is reached over TLS at the clientConfig (a service reference or a url), and the server trusts it via the caBundle. If the call fails, failurePolicy decides between rejecting (Fail) or admitting (Ignore) the request. sideEffects governs dry-run behavior, timeoutSeconds (1–30) bounds the call, and matchPolicy (Exact or Equivalent) controls how aliased API versions are matched. admissionReviewVersions lists the AdmissionReview API versions the webhook understands.

Tips and examples

A minimal validating webhook rule:

webhooks:
- name: policy.example.com
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["apps"]
    apiVersions: ["v1"]
    resources: ["deployments"]
  failurePolicy: Fail
  sideEffects: None
  matchPolicy: Equivalent
  admissionReviewVersions: ["v1"]
  timeoutSeconds: 5

Always exclude the kube-system namespace and the webhook’s own namespace via namespaceSelector to avoid a deadlock where the webhook blocks the pods that serve it. Use failurePolicy: Ignore plus a short timeoutSeconds for non-critical webhooks so an outage cannot freeze the control plane, and make mutating webhooks idempotent when reinvocationPolicy is IfNeeded.

Kubernetes Admission Webhook Operations

Email me this result

Kubernetes admission webhook operations

How it works

Tips and examples