Last reviewed: November 14, 2026 (UTC); official Kubernetes admission references checked November 14, 2026.
Direct answer
Review an admission change as a request-routing and API-server behavior change. Start with the exact resources, operations, versions, namespaces, and objects the candidate matches. Then determine whether a mutating webhook changes the object, whether a validating webhook or policy evaluates the resulting object, what happens on timeout or webhook error, and whether a dry-run request is safe. Approve the patch only when the final admitted object and the rejection path are both tied to the same rendered revision.
Kubernetes invokes mutating admission webhooks before validating admission webhooks. A mutating webhook can apply defaults or other patches, after which validation runs against the modified object. The dynamic admission control reference documents webhook matching, side effects, timeouts, reinvocation, and failure policy. The admission webhook good-practices guide explains how to keep mutations narrow, avoid self-triggering and dependency loops, and validate the final state. For declarative checks, ValidatingAdmissionPolicy provides in-process Common Expression Language (CEL) validation and a separate binding step.
A successful server-side dry run proves that the request reached admission without being persisted. It does not prove that a later real request will hit the same webhook, that a mutator is idempotent, or that the admitted Pod or workload will start. Keep admission decisions, final-object inspection, and runtime checks as separate evidence.
Who this is for
Use this workflow when a coding agent edits a MutatingWebhookConfiguration, ValidatingWebhookConfiguration, ValidatingAdmissionPolicy, a policy binding, or an application manifest that depends on admission defaults. It is for platform engineers and maintainers reviewing changes that can alter object creation, update, or deletion across namespaces. It also applies when an agent changes a webhook Service, certificate, namespace selector, or match conditions.
Give the agent the target Kubernetes minor version, the resources the policy is meant to govern, the allowed namespaces, the availability requirement, and the owner of any exception. Ask it to render every overlay and list the effective matching rules. The fixtures below are proposed review checks; they report no authenticated cluster test or deployment result.
Key takeaways
- Read the complete matching rule before judging a webhook: API group, version, resource, subresource, operation, scope, and namespace or object selectors all matter.
- Review mutation and validation as one chain. A validator may see an object after another webhook has changed it.
- Keep mutations minimal and idempotent, and verify the final object rather than trusting a patch log.
- Set
sideEffectsaccurately and test dry-run behavior. A webhook with undeclared side effects can make dry-run requests unsafe or rejected. - A timeout or webhook error follows
failurePolicy;FailandIgnorecreate different availability and enforcement contracts. reinvocationPolicy: IfNeededcan call a mutating webhook again, so the patch must converge when another mutator changes a field later in the chain.- A ValidatingAdmissionPolicy uses CEL and still needs a binding; an unbound policy is not enforcement evidence.
Sources checked
Three primary Kubernetes references were retrieved successfully on November 14, 2026 UTC:
- Dynamic Admission Control documents mutating and validating webhook order, request matching, selectors, side effects, timeouts, reinvocation, and failure policy.
- Admission Webhook Good Practices documents narrow patches, self-mutation and dependency-loop risks, final-state validation, and operational design recommendations.
- ValidatingAdmissionPolicy documents CEL-based in-process validation, policy bindings, parameters, and failure behavior; the page identifies the feature as stable since Kubernetes v1.30.
These maintained references support an evergreen review task. Match fields and feature behavior to the target control-plane minor version. The article’s test matrix is an operating recommendation; it does not claim that any cluster was changed or that a webhook was deployed.
Contract details to verify
Freeze the request-matching contract
Render the candidate configurations and write a table for every webhook or policy. Include the configuration name, webhook name, rules, matchPolicy, namespaceSelector, objectSelector, and any matchConditions. For each rule, record API groups, API versions, resources, subresources, operations, and scope. A rule for pods does not automatically cover pods/status; a rule for one API version may miss another version unless matching is deliberately equivalent.
Check whether a selector matches the namespace or the object being admitted. A namespace selector does not constrain cluster-scoped resources in the same way it constrains namespaced resources. An object selector can match an old object or a new object during an update, so a label change can change whether the webhook runs. Match conditions add another filter after the basic rule and selectors. Preserve the rendered rule set with the candidate revision so a later label or namespace change cannot silently broaden coverage.
List the resources the webhook configuration itself matches. A webhook that intercepts its own configuration, its Service, or a policy object can create a self-mutation loop or a recovery dependency. Exclude control-plane and emergency paths deliberately, and document the exact reason for each exclusion. Use a test identity and namespace that are not accidental exceptions.
Separate mutation from validation
Mutating webhooks run first and may apply JSON patches or defaults. Validation then evaluates the object after those mutations. Build a before-and-after fixture for a harmless Pod or ConfigMap. Capture the submitted object, every expected mutation, and the final object returned by the API server. Do not treat a webhook’s log entry as proof that its patch was applied, or as proof that a later webhook did not overwrite the field.
Patch only the fields the policy owns. Avoid replacing complete arrays when adding one container or environment variable; another actor can have added an entry that the broad patch would erase. Make the mutation idempotent: submitting the already-mutated object should produce no further semantic change. If the configuration uses reinvocationPolicy: IfNeeded, run the fixture with a second mutator that changes a related field and confirm that repeated invocation converges.
If the desired rule is only validation, prefer a ValidatingAdmissionPolicy when CEL can express it and the cluster supports the required feature. A policy object alone is inert until a binding selects its enforcement action and scope. Inspect the binding’s matchResources, parameter reference, and validationActions. Keep complex external lookups in a webhook with an explicit availability and dependency plan; do not hide a network dependency inside an expression that appears in-process.
Review failure, timeout, and dry-run behavior
The webhook API reference defines failurePolicy values Fail and Ignore. With Fail, an unrecognized error, timeout, or match-condition error can reject the request. With Ignore, the API server proceeds when the webhook cannot provide a result. Choose this from the policy’s risk and the cluster’s availability requirement, then test the chosen path. A fail-open setting may preserve object creation while disabling the intended control; a fail-closed setting may make the API unavailable when the webhook Service or certificate is broken.
Keep the timeout short enough that a slow dependency does not consume API-server capacity. The dynamic admission reference documents a default timeoutSeconds of 10 seconds for webhook configuration and a bounded maximum. Measure the complete request path, including DNS, TLS, webhook processing, and API-server retries, in the approved environment. Do not claim that a request succeeded merely because the webhook process logged it.
Declare sideEffects: None when the webhook has no side effects, or NoneOnDryRun when it can act on a real request but suppresses those effects for dry-run. A dry-run request that matches a webhook declaring unknown or unsupported side effects can be rejected. Send one server-side dry-run request through the exact same namespace, identity, and labels as the real candidate, then compare the returned object and webhook evidence. A dry run does not exercise image pulls, controllers, or application startup.
Prove the final object and policy decision
Use an approved disposable namespace and synthetic names. Establish a healthy baseline before each case. Record the source revision, renderer inputs, webhook configuration resource versions, policy and binding UIDs, request UID, and the admitted object’s UID or dry-run response. Redact request bodies that contain credentials or private data.
A read-only inspection should include all matching webhook configurations and policy bindings, not just the object edited by the agent. For a real request, capture the API response and object state. For a rejected request, retain the status reason and field path without copying sensitive payloads. If a mutator adds a security context or label, inspect the persisted object and compare it with the expected final state.
Use a matrix like this:
| Controlled case | Acceptance evidence |
|---|---|
| Intended Pod or ConfigMap matches one webhook | Rule, selector, request UID, webhook response, and final object identify the same candidate |
| Namespace or object label is outside the selector | Request succeeds without the mutation; evidence shows the exclusion was intentional |
| A validating rule rejects one targeted field | Rejection names the policy or webhook and field; no object or downstream side effect is created |
| Mutator receives an already-mutated object | Second submission converges and does not duplicate fields or containers |
| A later mutator changes a related field | IfNeeded reinvocation produces the intended stable final object |
| Webhook Service is unavailable or times out | Observed result matches the documented Fail or Ignore policy; owner and recovery action are recorded |
| Server-side dry run is used | Side effects are absent, the final object is inspectable, and the same request would be admitted under the chosen policy |
| ValidatingAdmissionPolicy is present | Policy, binding, parameter, match scope, and validation action are all present and effective |
For a negative case, change one field only, such as adding a forbidden host path or removing a required label. Check that the API server rejects the request before a controller creates a Pod. A failed client connection, missing permission, or malformed fixture is not evidence of policy enforcement. Restore the baseline between cases and keep the request UID attached to every observation.
After admission passes, run the approved runtime smoke test separately. A valid object can still fail scheduling, image startup, volume permissions, or application readiness. If a mutator injects a sidecar, review its image identity, probes, resources, and service-account permissions through the relevant workload checks. Admission success establishes an API boundary, not application health.
Failure modes
The rule is broader than the stated intent. A wildcard API group, resource, or operation can cover objects the owner did not name. Expand the rendered rule and test one neighboring resource that should remain untouched.
A selector change silently changes coverage. Compare namespace and object labels in each environment. Keep a positive and negative fixture for every selector that matters.
A mutator overwrites another actor’s fields. Patch only the owned field, preserve arrays, and test repeated admission after another mutator runs.
A timeout is treated as a successful control. Record the API-server result and apply the configured failure policy. A webhook log without a matching response is incomplete evidence.
Dry run causes an external write. Correct sideEffects, suppress external actions for dry-run, and keep a dry-run test in the release checklist.
An unbound ValidatingAdmissionPolicy is called active. Inspect the binding and its validation action. A policy definition without a binding does not reject requests.
The webhook depends on the object it must admit. Avoid dependency loops and self-mutations. Keep an emergency path that can repair or remove the configuration when the webhook is unhealthy.
FAQ
Does a mutating webhook run after validation?
No. Mutating admission runs before validating admission. A later mutator can still be reinvoked when configured, so validators should be checked against the final object produced by the chain.
Should every webhook use failurePolicy: Fail?
No. The owner must balance enforcement and API availability. A security or isolation rule may require fail-closed behavior, while an advisory default may tolerate fail-open behavior. Document the choice and test the outage path.
Is a server-side dry run a full deployment test?
No. It checks admission without persistence. It does not start a container, schedule a Pod, exercise a controller, or prove external side-effect safety unless the webhook declares and implements dry-run behavior correctly.
Is a ValidatingAdmissionPolicy a webhook replacement in every case?
No. CEL policies are useful for declarative in-process checks, but a complex external lookup or mutation needs a different mechanism. Confirm feature support, bind the policy, and keep external dependencies explicit.
Reader next step
Choose one agent-written admission change. Render every webhook or policy configuration, write the request-matching table, and capture one admitted object plus one targeted rejection in an authorized disposable namespace. Repeat the admitted fixture to test idempotence, exercise the declared dry-run path, and record the outage result for the selected failure policy. Attach the request UID, final object, policy or webhook resource versions, and sanitized diagnostics to the pull request. If the patch also changes workload permissions or runtime restrictions, pair it with Review Kubernetes RBAC in Coding-Agent Patches and Review Kubernetes Pod Security in Coding-Agent Patches .