6.17 Kubernetes Manifest Validation

Kubernetes Manifest Validation is the practice and tooling ecosystem surrounding checking a manifest's correctness before it is ever applied to a live cluster, spanning local schema linting, dry-run submissions against an actual API server, and policy-as-code enforcement, together forming a layered pre-flight validation workflow that catches errors earlier and cheaper than waiting for a rejected apply against production.

Local Schema Linting

Validating Structure Without a Cluster

Standalone linting tools can check a manifest's structure against a downloaded or bundled copy of the relevant OpenAPI schemas entirely offline, catching type mismatches, missing required fields, and unrecognized fields without needing any network connection to an actual Kubernetes API server.

Benefits and Limitations of Offline Linting

Offline schema linting is fast and can run in a pre-commit hook or early CI stage, but it necessarily works against a specific, potentially stale snapshot of schema definitions, and cannot catch errors that depend on live cluster state, such as a referenced ConfigMap that does not actually exist.

Client-Side Dry Run

Local Validation Through kubectl

kubectl apply --dry-run=client performs local validation and defaulting simulation without contacting the API server at all beyond potentially fetching schema information, offering a fast sanity check that a manifest is at least structurally well-formed according to the client's understanding of the resource's schema.

What Client-Side Dry Run Cannot Catch

Because this mode never actually reaches the API server's admission chain, it cannot detect errors that only manifest during server-side processing, such as a validating webhook rejecting the object or a resource quota being exceeded, limiting it to catching purely structural and client-known-schema issues.

Server-Side Dry Run

Full Pipeline Validation Without Persistence

kubectl apply --dry-run=server submits the manifest through the complete request pipeline, including admission webhooks, quota checks, and full schema validation, but instructs the API server to skip the final persistence step, giving the most accurate possible pre-flight validation short of actually committing the change.

Trade-Offs of Server-Side Dry Run

Because it requires an actual connection to a real, appropriately configured cluster, server-side dry run cannot be run in a fully offline context and reflects the validation rules of whichever specific cluster it targets, meaning results can differ between clusters with different installed webhooks or admission configuration.

CI Pipeline Integration

Gating Merges on Manifest Validation

Repositories storing manifests commonly wire validation directly into CI, running schema linting and, where feasible, a dry run against a representative cluster, on every pull request, preventing manifests with structural errors from ever being merged into the branch that a deployment pipeline later applies.

Validating Templated Output

For manifests generated by templating tools such as Helm or Kustomize, validation typically runs against the fully rendered output rather than the template source itself, since only the rendered manifest reflects what will actually be submitted to the cluster, and template-level syntax alone does not guarantee the rendered result is valid.

Policy-as-Code Validation Beyond Schema

Enforcing Organizational Rules Pre-Merge

Tools such as Open Policy Agent's Conftest or Kyverno's CLI mode allow custom policy rules, beyond what a resource's schema alone enforces, to be checked against manifests before they ever reach a cluster, such as requiring specific labels, disallowing privileged containers, or enforcing resource limit presence.

Consistency With In-Cluster Admission Policy

Well-run environments aim to keep pre-merge policy validation consistent with whatever admission-time policy enforcement, such as validating webhooks or ValidatingAdmissionPolicy resources, actually runs against the live cluster, so that a manifest passing CI checks is genuinely likely to also be accepted when it is eventually applied.

Layering Validation for Defense in Depth

Cheapest Checks First

A well-designed validation workflow orders its checks from cheapest and fastest, local schema linting, to progressively more expensive and authoritative, server-side dry run and live admission, so that the majority of errors are caught quickly in early stages, reserving the cost of a full server-side check for manifests that have already passed the cheaper preliminary checks.