5.13 Kubernetes API Validation Model

Kubernetes API Validation Model is the layered system by which the API server checks that an incoming object meets structural, semantic, and policy requirements before it is persisted, spanning schema-based structural validation, built-in type-specific validation logic, and pluggable admission-time validation, together ensuring that only well-formed and policy-compliant objects ever reach etcd.

Structural Schema Validation

OpenAPI-Derived Schemas

Every resource type, whether built-in or defined through a Custom Resource Definition, is associated with an OpenAPI v3 schema describing the expected type, format, and constraints of each field, which the API server uses to reject requests containing fields of the wrong type or values outside declared constraints such as minimum and maximum numeric bounds.

Structural Versus Non-Structural Schemas

For Custom Resource Definitions specifically, a schema is considered structural if every field's type is explicitly specified and unknown fields are handled according to a defined pruning policy, a requirement that became mandatory in modern Kubernetes versions to guarantee consistent, predictable validation and pruning behavior across all custom resources.

Pruning of Unknown Fields

By default, fields present in a submitted manifest but not defined in the resource's schema are pruned, silently removed, before the object is persisted, preventing accumulation of stray, unvalidated data, though this behavior can be relaxed for specific fields using schema extensions that permit arbitrary additional properties.

Built-In Semantic Validation

Type-Specific Validation Logic

Beyond generic schema checks, many built-in resource types carry additional validation logic implemented directly in the API server's code, enforcing rules that are difficult to express purely declaratively, such as ensuring a Service's port numbers fall within a valid range or that a Pod's container names are unique within the Pod.

Immutability Enforcement

Certain fields are validated as immutable after creation, such as a Deployment's selector or a PersistentVolumeClaim's storage class in most configurations, with update requests that attempt to change these fields rejected outright by validation logic specific to that resource type.

Admission-Time Validation

The Admission Chain

After passing authentication and authorization, and before an object is persisted, it flows through an ordered chain of admission plugins, some of which perform additional validation beyond what schema and built-in type validation cover, such as enforcing resource quota limits or Pod Security Standards.

Validating Admission Webhooks

Cluster operators can register validating admission webhooks, external HTTP services that the API server calls synchronously during the admission chain, allowing custom, organization-specific validation logic, such as requiring specific labels or rejecting images from unapproved registries, without modifying the API server itself.

Common Expression Language Validation Rules

Newer versions of Kubernetes support declarative validation rules expressed using the Common Expression Language directly within a CustomResourceDefinition's schema or through ValidatingAdmissionPolicy resources, allowing many validation scenarios that previously required a webhook to instead be expressed and enforced natively within the API server.

Validation Failure Behavior

Rejection with Diagnostic Detail

When validation fails at any stage, the API server responds with an HTTP error status, commonly 422 Unprocessable Entity for structural or semantic validation failures, accompanied by a Status object detailing which field or fields failed validation and why, giving the submitting client actionable information for correcting the request.

Fail-Open Versus Fail-Closed Webhooks

Validating webhooks are configured with a failurePolicy determining behavior if the webhook itself is unreachable or errors: Fail rejects the request outright, treating the inability to validate as a validation failure, while Ignore allows the request through, a tradeoff between strict enforcement and admission chain resilience.

Client-Side Validation Complementing Server-Side Checks

Dry Run Requests

Clients can submit requests with a dryRun parameter, causing the API server to run the full validation and admission pipeline without actually persisting any change, allowing tools to preemptively surface validation errors to a user before committing to an actual mutation.

kubectl Local Validation

Command-line tooling such as kubectl apply can perform a degree of client-side schema validation against locally cached or fetched OpenAPI schemas before ever sending a request, catching some categories of structural errors earlier in the workflow, though server-side validation remains the ultimate authority since client-side schemas can become stale.

Why Layered Validation Matters

Defense at Multiple Levels

Structural schema validation catches malformed requests cheaply and generically, built-in semantic validation enforces rules specific to well-known resource types, and admission-time validation allows organization-specific policy to be layered on top, together forming a validation model that balances broad applicability with the flexibility needed for cluster-specific governance.