Kubernetes Manifest Validation

Kubernetes Manifest Validation is the practice of checking a manifest's correctness before it ever reaches a live cluster, spanning a spectrum from purely offline syntax and schema checking to full server-side dry-run evaluation against a real cluster's actual admission configuration, each catching a different class of error at a different point in the authoring and deployment pipeline. Because manifest errors range from simple YAML typos to deep policy violations only a specific cluster's webhooks would reject, no single validation stage catches everything, which is why mature pipelines layer several of these checks together.

Offline Structural Validation

Schema Checking Without a Live Cluster

Tools that validate manifests against a downloaded or bundled copy of the Kubernetes OpenAPI schema can catch structural errors — missing required fields, incorrect types, unknown fields — entirely offline, without any network connection to a real cluster, making this the fastest and cheapest validation stage to run, commonly wired into a pre-commit hook or the earliest stage of a CI pipeline.

Limitations of Offline Validation

Because offline schema validation has no visibility into a specific cluster's installed CustomResourceDefinitions, RBAC policy, or admission webhooks, it cannot catch errors that depend on cluster-specific state, such as a manifest referencing a custom resource type that does not exist in the target cluster, or a resource request that would violate a ResourceQuota that only that cluster enforces.

Client-Side Dry Run

kubectl apply --dry-run=client

Client-side dry run processes a manifest through the same local logic kubectl would use for a real apply, including client-side merge computation, but never sends a request to the API server at all; it catches client-side construction errors and gives a preview of the resulting object, but cannot detect anything that depends on server-side admission or validation logic.

When Client-Side Dry Run Falls Short

Because it never contacts the API server, client-side dry run cannot reveal whether a manifest would actually be accepted by a specific cluster's schema validation, admission webhooks, or RBAC rules for the requesting identity, meaning a manifest that passes client-side dry run can still be rejected outright when actually applied.

Server-Side Dry Run

Full Pipeline Evaluation Without Persistence

kubectl apply --dry-run=server submits the request through the API server's complete admission pipeline — authentication, authorization, mutating and validating webhooks, schema validation — exactly as a real request would be processed, with the sole difference that the result is never persisted to etcd, giving the most accurate possible preview of what a real apply would produce or reject.

Catching Cluster-Specific Policy Violations

Because server-side dry run genuinely evaluates admission webhooks and validating policies configured on the target cluster, it is the only validation stage capable of catching organization-specific policy violations — a required label missing, a disallowed image registry, a security context violating a Pod Security Standard — before those checks would otherwise reject a real deployment attempt.

Validation in CI/CD Pipelines

Layering Checks by Cost and Coverage

A well-designed pipeline typically runs cheap, fast offline validation on every commit, reserving more expensive server-side dry-run checks (which require a live cluster connection and consume some API server resources) for later stages such as a pre-merge check or a staging deployment step, balancing feedback speed against thoroughness.

Policy-as-Code Tools

Beyond schema and admission validation, dedicated policy engines evaluated as a CI pipeline step can enforce organization-specific rules directly against manifest content — requiring specific labels, disallowing privileged containers, enforcing naming conventions — providing a validation layer that expresses custom governance rules independently of whatever a specific cluster's live admission configuration happens to enforce.

Common Manifest Validation Failures in Practice

Structural and Type Errors

The most frequently encountered validation failures at the offline stage are simple structural mistakes — incorrect indentation changing an object's nesting, a misspelled field name that gets silently pruned rather than flagged, or a value of the wrong type such as a quoted number where an integer is expected.

Cross-Field and Policy Errors Caught Later

Errors requiring cross-field reasoning or cluster-specific policy — a selector that does not match its own Pod template's labels, a resource limit set below its corresponding request, or a security context violating an enforced Pod Security Standard — typically surface only at the semantic validation or admission stage, illustrating why offline checks alone are never sufficient for full confidence in a manifest's correctness.