Kubernetes API Validation Model

Kubernetes API Validation Model is the layered set of checks the API server applies to every object before it is persisted, spanning structural schema validation derived from OpenAPI definitions, type-specific semantic validation implemented in Go for built-in resources, and pluggable validation implemented through webhooks and, more recently, expression-based policy for both built-in and custom types. Validation exists to ensure that only well-formed, internally consistent objects ever reach etcd, protecting every downstream controller from having to defensively re-check invariants the API layer should have already guaranteed.

Structural Schema Validation

OpenAPI-Derived Checks

Every built-in type and every CustomResourceDefinition carries an OpenAPI v3 schema describing its fields, their types, and constraints such as required fields, minimum and maximum numeric bounds, string patterns, and enumerated allowed values; the API server validates incoming requests against this schema automatically, rejecting requests with type mismatches, missing required fields, or values outside declared bounds before any type-specific logic even runs.

Pruning of Unknown Fields

By default, fields present in a request but not described in the type's schema are pruned (silently dropped) rather than causing outright rejection, though strict server-side validation modes can instead reject such requests, catching typos and misremembered field names that would otherwise be silently discarded and cause confusing behavior later.

Semantic Validation for Built-In Types

Beyond What Schema Alone Can Express

Structural schema validation cannot express cross-field invariants — such as "a container's resource limits must be greater than or equal to its requests" — so built-in types carry additional semantic validation implemented directly in the API server's Go code, checked after structural validation passes, catching logically inconsistent objects that are individually well-typed but collectively invalid.

Immutability Enforcement

Semantic validation is also where immutability rules are enforced on updates — rejecting an attempt to change a Pod's node assignment after scheduling, for instance — comparing the incoming object against the object's current stored state to detect and reject changes to fields the type's rules designate as fixed once initially set.

Validating Admission Webhooks

Extending Validation to Arbitrary Policy

Validating admission webhooks allow cluster operators to plug in custom validation logic evaluated as part of every matching request's admission chain, implemented as an external HTTP service the API server calls synchronously, which can reject a request for any reason the webhook author chooses — enforcing organizational policy, security constraints, or naming conventions that go beyond what schema and built-in semantic validation cover.

Failure Policy Considerations

Because validating webhooks sit synchronously in the request path, their configured failure policy — whether a webhook that is unreachable or errors should cause the request to fail closed (rejected) or fail open (allowed) — has direct operational consequences, since a fail-closed webhook that becomes unavailable can block all matching API operations cluster-wide until it recovers.

Common Expression Language Validation

In-API-Server Policy Without a Webhook

CEL-based validation, expressed through ValidatingAdmissionPolicy resources or within a CustomResourceDefinition's schema directly, allows policy authors to write validation expressions evaluated inside the API server itself rather than requiring a separate webhook service, reducing both the latency and the availability risk that an external webhook call introduces while still allowing custom, cross-field validation logic.

Expressiveness and Scope

CEL validation expressions can reference the object being validated, and in some contexts the prior version of the object on updates, allowing checks such as preventing a field from being decreased or requiring consistency between two related fields, covering a substantial portion of the use cases that previously required a dedicated webhook to implement.

Ordering and Interaction Across Validation Layers

Validation Happens After Mutation

All validation, whether structural, semantic, webhook-based, or CEL-based, is evaluated against the fully mutated form of the request, after any mutating admission webhooks and defaulting have already run, ensuring that what is validated is exactly what would actually be persisted, not an intermediate or pre-mutation form of the object.