Validate Kubernetes YAML before it reaches a cluster by combining syntax checks, Kubernetes schema validation, server-side dry runs, policy checks, and a small set of deployment-specific inspections. This workflow helps catch invalid API versions, selector mismatches, probe errors, resource mistakes, and unsafe settings before they become rollout problems.
Overview
Kubernetes manifest validation is more than confirming that a file is valid YAML. A manifest can parse correctly and still fail because it uses an unsupported API version, omits a required field, references a missing namespace, violates an admission policy, or describes components that do not work together.
A reliable validation workflow uses several layers:
- YAML parsing: confirms indentation, quoting, document separators, and basic structure.
- Schema validation: checks whether fields and values match the Kubernetes resource definition for a target version.
- API-server validation: asks a real cluster to validate the object without persisting it.
- Policy validation: checks organizational rules such as required labels, non-root containers, approved registries, or resource limits.
- Behavioral review: checks relationships and runtime assumptions that static schemas cannot fully understand.
No single command catches every class of problem. The practical goal is to run the least expensive checks first, then use a cluster-aware dry run and policy checks before applying a change.
A validation method comparison
| Method | Syntax | Schema | Cluster state | Policy |
|---|---|---|---|---|
| YAML parser or linter | Yes | Usually no | No | No |
kubectl apply --dry-run=client | Yes | Limited client-side checks | No | No |
kubectl apply --dry-run=server | Yes | Yes, through the API server | Partly | Admission policies may apply |
| kubeconform or kubeval | Yes | Yes, against schemas | No | No |
| OPA, Gatekeeper, Kyverno, or similar | Depends on tool | Often | Depends on configuration | Yes |
kubectl diff | Yes | Through the server | Compares desired and live state | May encounter admission rules |
Checklist by scenario
1. Validate a local file without cluster access
Start with a parser or YAML linter in your editor or CI job. This catches malformed indentation, accidental tabs, invalid quoting, and broken multi-document files. Then use a schema validator when possible:
kubeconform -strict -summary deployment.yamlSchema validators are most useful when their Kubernetes schema set matches the cluster version and the resource kinds in your file. Check the validator's configuration for custom resources, because a standard Kubernetes schema may not describe an operator-owned kind. Older validators or schema bundles may also lag behind newly introduced or changed APIs; treat an unknown field or kind as a compatibility question to investigate, not something to suppress automatically.
2. Validate with kubectl before connecting to a cluster
A client-side dry run builds the object locally and is useful for fast feedback:
kubectl apply --dry-run=client -f deployment.yamlThis is convenient in a pre-commit hook, but it is not a substitute for server-side validation. It cannot know the exact API resources, admission configuration, or current cluster capabilities. Use it as an early check rather than a final approval.
3. Validate against the target API server
When you have access to the intended cluster, use a server-side dry run:
kubectl apply --dry-run=server -f deployment.yamlThis sends the object through API-server validation without storing it. It can expose unsupported resource versions, unknown fields, malformed values, and some admission-policy violations. Run it against each materially different environment when clusters have different Kubernetes versions, CRDs, admission rules, or namespaces.
For an existing object, compare the proposed result with live state:
kubectl diff -f deployment.yamlReview the diff for changes to container images, selectors, ports, probes, resource settings, and security context. A diff is a review aid, not proof that the application will become healthy.
4. Validate a deployment and its Service together
A Deployment can pass schema validation while its Service selects no Pods. Compare the Service selector with the labels in spec.template.metadata.labels:
kubectl get pods --show-labels
kubectl get endpointslices -l app=my-appUse the same intended label keys and values, and confirm that the Service port targets a port actually exposed by the selected Pods. Named ports must match exactly; numeric ports must be valid for the container and application design.
5. Validate probes and resources
Check that readiness, liveness, and startup probes point to a real path, port, and protocol. A probe can be syntactically valid yet fail because the application starts slowly, listens on a different interface, or exposes a different endpoint. Confirm that startup behavior is compatible with the probe timing.
For resources, inspect both requests and limits where your team requires them. Check units such as Mi, Gi, and CPU quantities carefully. Resource settings affect scheduling and runtime throttling; they should be reviewed against observed application needs rather than copied blindly.
6. Run security and policy checks
Run the policy tool used by your platform team before applying the manifest. Typical checks include prohibited host access, privileged containers, missing runAsNonRoot, writable root filesystems, unapproved image registries, absent resource requests, and missing ownership labels. The exact rules are environment-specific, so keep policy failures visible in CI and document approved exceptions instead of weakening checks globally.
What to double-check
API versions and deprecated fields
Confirm that every apiVersion is served by the target cluster and that the resource's fields belong to that version. Do not assume that a manifest accepted by one cluster will work after an upgrade or on a different environment. Review release notes and the cluster's discovery information when changing versions:
kubectl api-resources
kubectl explain deployment.spec --recursiveUse kubectl explain against the target cluster where possible, because it reflects the resources and schemas exposed there.
Namespaces and names
Confirm that names are unique within their namespace and that namespaced objects are going to the intended namespace. A manifest's metadata.namespace, the -n option, and the current kubectl context can point to different places. Check the active context before any non-dry-run operation:
kubectl config current-context
kubectl config view --minifyDo not rely on a manifest to create a namespace unless the namespace object is included and applied in an appropriate order. Verify that referenced Secrets, ConfigMaps, ServiceAccounts, and image-pull credentials exist in the same namespace or are otherwise available as expected.
Security context and secret handling
Inspect both Pod-level and container-level security contexts. Look for unnecessary privilege, host networking or filesystem access, added Linux capabilities, and writable paths. Avoid placing credentials directly in a manifest stored in source control. A reference to a Secret is not proof that the Secret contains the expected keys or values, so verify that dependency separately without printing sensitive data.
Custom resources
For CRDs, validate the CRD and the custom resource against the same target cluster. A local generic schema tool may not know operator-specific fields, defaults, or conversion behavior. Server-side validation is especially important when a controller, webhook, or admission rule changes how the custom resource is accepted.
Common mistakes
| Symptom | Likely cause | Useful check |
|---|---|---|
| Service has no endpoints | Selector does not match Pod labels | Compare selectors and use kubectl get endpointslices |
| Resource kind or version is unknown | API is not served or is deprecated | Run kubectl api-resources and server-side dry run |
| Probe repeatedly fails | Wrong path, port, protocol, or startup timing | Inspect Pod events and test the endpoint inside the Pod |
| Pods remain Pending | Requests cannot be scheduled or constraints conflict | Inspect events, requests, node capacity, affinity, and taints |
| Manifest passes locally but fails in CI | Different cluster version, schemas, CRDs, or policies | Validate against the same environment assumptions |
| Object is rejected despite valid YAML | Admission policy or server-side rule | Read the complete API error and run the policy check locally |
| Change affects the wrong workload | Context, namespace, or name was misidentified | Check context, namespace, and kubectl diff |
When to revisit
Use this checklist whenever you create or modify a manifest, open an infrastructure pull request, upgrade Kubernetes, add or update a CRD, change admission policies, or deploy to a different environment. Re-run validation after changing images, selectors, ports, probes, resource quantities, namespaces, or security settings; these edits can alter runtime behavior even when the YAML structure stays the same.
As a reusable pre-apply checklist, confirm:
- The YAML parses and all documents are included.
- API versions, kinds, and fields are supported by the target cluster.
- Client-side and server-side dry runs pass.
- A schema validator uses compatible schemas, including custom resources where applicable.
- Policy checks pass or have a documented, reviewed exception.
- Deployment labels and Service selectors match.
- Ports, probes, requests, limits, and startup behavior are consistent.
- The namespace, context, referenced dependencies, and image credentials are correct.
- Security contexts follow the platform's requirements.
kubectl diffhas been reviewed before applying.
Keep the commands in CI so the checks run consistently, and refresh the workflow when Kubernetes releases, validator behavior, cluster policies, or team deployment practices change. For adjacent infrastructure checks, compare this process with the Docker Compose validation guide and the Terraform plan review checklist.