Kubernetes Manifest Validation Guide: Check Deployments, Services, Probes, Resources, and Security Settings
KubernetesYAMLkubectlKubernetes manifestsDevOpsdeployment validation

Kubernetes Manifest Validation Guide: Check Deployments, Services, Probes, Resources, and Security Settings

ttoggle.top Editorial Team
2026-11-21
6 min read

A practical Kubernetes manifest validation workflow using dry runs, schemas, policy checks, and a reusable pre-apply checklist.

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:

  1. YAML parsing: confirms indentation, quoting, document separators, and basic structure.
  2. Schema validation: checks whether fields and values match the Kubernetes resource definition for a target version.
  3. API-server validation: asks a real cluster to validate the object without persisting it.
  4. Policy validation: checks organizational rules such as required labels, non-root containers, approved registries, or resource limits.
  5. 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

MethodSyntaxSchemaCluster statePolicy
YAML parser or linterYesUsually noNoNo
kubectl apply --dry-run=clientYesLimited client-side checksNoNo
kubectl apply --dry-run=serverYesYes, through the API serverPartlyAdmission policies may apply
kubeconform or kubevalYesYes, against schemasNoNo
OPA, Gatekeeper, Kyverno, or similarDepends on toolOftenDepends on configurationYes
kubectl diffYesThrough the serverCompares desired and live stateMay 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.yaml

Schema 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.yaml

This 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.yaml

This 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.yaml

Review 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-app

Use 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 --recursive

Use 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 --minify

Do 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

SymptomLikely causeUseful check
Service has no endpointsSelector does not match Pod labelsCompare selectors and use kubectl get endpointslices
Resource kind or version is unknownAPI is not served or is deprecatedRun kubectl api-resources and server-side dry run
Probe repeatedly failsWrong path, port, protocol, or startup timingInspect Pod events and test the endpoint inside the Pod
Pods remain PendingRequests cannot be scheduled or constraints conflictInspect events, requests, node capacity, affinity, and taints
Manifest passes locally but fails in CIDifferent cluster version, schemas, CRDs, or policiesValidate against the same environment assumptions
Object is rejected despite valid YAMLAdmission policy or server-side ruleRead the complete API error and run the policy check locally
Change affects the wrong workloadContext, namespace, or name was misidentifiedCheck 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 diff has 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.

Related Topics

#Kubernetes#YAML#kubectl#Kubernetes manifests#DevOps#deployment validation
t

toggle.top Editorial Team

Developer Tools and DevOps Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.