Kubernetes Manifest Validation
Purpose
A consistent pre-deploy checklist for the Kubernetes manifest mistakes that pass kubectl apply but never become Ready, silent failures. This is K8s-specific domain knowledge about how manifests fail quietly, not generic YAML linting.
The silent-failure principle
kubectl apply validates schema, not intent. A manifest can apply cleanly and then: never pass readiness, get OOMKilled, run as root against policy, or route traffic to a dead Pod. Static pre-flight catches these before they reach the cluster.
Validation checklist (assign PASS / WARN / FAIL)
| Check |
FAIL condition |
Why it fails silently |
| Type / quoting |
containerPort: "8080" (string), "true" bool, int env value |
schema accepts strings; port never binds / value mis-typed |
| Resource requests & limits |
missing on a container |
BestEffort QoS → first evicted; can starve the node |
| Readiness probe |
missing |
traffic routed before the app can serve → 502s |
| Liveness probe |
missing (WARN) or too aggressive (FAIL) |
wedged Pod never restarts; or healthy Pod killed in a loop |
| Startup probe |
missing on slow-starting app |
liveness kills it before it finishes booting |
| securityContext |
runAsNonRoot unset, caps not dropped, writable rootfs |
runs as root; policy admission may reject later |
| Image tag |
:latest or untagged |
non-reproducible; rollout pulls a different image silently |
| Replicas / PDB |
single replica, no PodDisruptionBudget |
node drain / rollout causes full downtime |
| Hardcoded secrets |
literal token/password in env or ConfigMap |
secret committed to git; ConfigMaps aren't secret |
| Namespace |
relies on implicit default |
deploys to the wrong place; RBAC/quota surprises |
Type-quoting quick rules
containerPort, port, targetPort (numeric), replicas → integers, unquoted.- Boolean fields (
runAsNonRoot, readOnlyRootFilesystem) → bare true/false, never "true".
- Env
value: is always a string: wrap numbers/bools in quotes: value: "5432".
- YAML gotcha: unquoted
on, off, yes, no, and 1.20 get coerced, quote version strings.
Gate verdict
Report per-check PASS/WARN/FAIL, then an overall line: GATE: PASS only with zero FAILs, else GATE: FAIL.
Additional Resources
Reference Files
For per-kind mistakes and how each fails silently, consult:
references/manifest-checklist.md: Deployment, Service, Ingress, ConfigMap, Secret, and HPA common mistakes, each with the symptom, the silent failure, and the fix.
For probe and resource semantics in depth, consult:
references/probes-and-resources.md: liveness vs readiness vs startup probe semantics and tuning, requests/limits and the Guaranteed/Burstable/BestEffort QoS classes, and the securityContext hardening fields.
1---2name: k8s-manifest-validation3description: This skill should be used when the user mentions "kubernetes manifest", "k8s yaml", "deployment not ready", "pod crashloop", "resource limits", "liveness readiness probe", "securityContext", or "helm values", or is validating manifests before deploy. It provides the silent failure modes of K8s manifests plus a PASS/WARN/FAIL validation checklist.4---56# Kubernetes Manifest Validation78## Purpose9A consistent pre-deploy checklist for the Kubernetes manifest mistakes that pass `kubectl apply` but never become Ready, silent failures. This is K8s-specific domain knowledge about how manifests fail quietly, not generic YAML linting.1011## The silent-failure principle12`kubectl apply` validates schema, not intent. A manifest can apply cleanly and then: never pass readiness, get OOMKilled, run as root against policy, or route traffic to a dead Pod. Static pre-flight catches these before they reach the cluster.1314## Validation checklist (assign PASS / WARN / FAIL)1516| Check | FAIL condition | Why it fails silently |17|-------|----------------|-----------------------|18| Type / quoting | `containerPort: "8080"` (string), `"true"` bool, int env value | schema accepts strings; port never binds / value mis-typed |19| Resource requests & limits | missing on a container | BestEffort QoS → first evicted; can starve the node |20| Readiness probe | missing | traffic routed before the app can serve → 502s |21| Liveness probe | missing (WARN) or too aggressive (FAIL) | wedged Pod never restarts; or healthy Pod killed in a loop |22| Startup probe | missing on slow-starting app | liveness kills it before it finishes booting |23| securityContext | `runAsNonRoot` unset, caps not dropped, writable rootfs | runs as root; policy admission may reject later |24| Image tag | `:latest` or untagged | non-reproducible; rollout pulls a different image silently |25| Replicas / PDB | single replica, no PodDisruptionBudget | node drain / rollout causes full downtime |26| Hardcoded secrets | literal token/password in env or ConfigMap | secret committed to git; ConfigMaps aren't secret |27| Namespace | relies on implicit `default` | deploys to the wrong place; RBAC/quota surprises |2829## Type-quoting quick rules30- `containerPort`, `port`, `targetPort` (numeric), `replicas` → **integers**, unquoted.31- Boolean fields (`runAsNonRoot`, `readOnlyRootFilesystem`) → **bare** `true`/`false`, never `"true"`.32- Env `value:` is **always a string**: wrap numbers/bools in quotes: `value: "5432"`.33- YAML gotcha: unquoted `on`, `off`, `yes`, `no`, and `1.20` get coerced, quote version strings.3435## Gate verdict36Report per-check PASS/WARN/FAIL, then an overall line: `GATE: PASS` only with zero FAILs, else `GATE: FAIL`.3738## Additional Resources39### Reference Files40For per-kind mistakes and how each fails silently, consult:41- **`references/manifest-checklist.md`**: Deployment, Service, Ingress, ConfigMap, Secret, and HPA common mistakes, each with the symptom, the silent failure, and the fix.4243For probe and resource semantics in depth, consult:44- **`references/probes-and-resources.md`**: liveness vs readiness vs startup probe semantics and tuning, requests/limits and the Guaranteed/Burstable/BestEffort QoS classes, and the securityContext hardening fields.
sigistry