YAML manifest errors
| Error message | Likely cause | Fix |
|---|---|---|
cannot be handled as a Pod | Wrong or missing apiVersion | Set apiVersion: v1 for Pod |
unknown field "xxx" | Typo in field name | Check kubectl explain <resource> |
error parsing ... | Invalid YAML syntax | Check indentation, colons, quotes |
no matches for kind "X" in version "Y" | Wrong apiVersion for the kind | kubectl api-resources to find correct group |
kubectl api-resources | grep -i <kind>
kubectl explain <resource>
kubectl explain pod # shows apiVersion at top
Common correct apiVersions:
Pod, Service, ConfigMap, Secret, ServiceAccount, Namespace → v1
Deployment, ReplicaSet, DaemonSet, StatefulSet → apps/v1
Job, CronJob → batch/v1
Ingress, NetworkPolicy → networking.k8s.io/v1
RBAC Role/Binding, ClusterRole/Binding → rbac.authorization.k8s.io/v1
HPA → autoscaling/v2
StorageClass, PV, PVC → storage.k8s.io/v1 / v1
ResourceQuota, LimitRange → v1
PodDisruptionBudget → policy/v1
HTTPRoute → gateway.networking.k8s.io/v1
Deployment crashing due to command/args typo
Pattern: kubectl get deploy shows 0/1 ready; kubectl describe pod shows CrashLoopBackOff.
kubectl get po -n <ns>
kubectl logs -n <ns> <pod>
kubectl logs -n <ns> <pod> --previous
kubectl get deployment <name> -n <ns> -o yaml | grep -A5 command
kubectl edit deployment -n <ns> <name>
# fix typo e.g. "sleeep 3600" → "sleep 3600"
kubectl rollout status deployment -n <ns> <name>
Common command/args bugs:
- Typo:
sleeepinstead ofsleep - Missing shell wrapper:
sleep 3600ascommand: [sleep, "3600"]works, but shell constructs need["/bin/sh", "-c", "..."] - Wrong args order:
command: ["3600", "sleep"] argsused whencommandneeded (or vice versa): see containers.md
kubectl replace --force (pod in-place fix)
Pods are mostly immutable: can't kubectl edit most fields.
# Pattern 1: replace with force (deletes + recreates)
kubectl get pod <pod> -n <ns> -o yaml > pod-fix.yaml
vim pod-fix.yaml
kubectl replace -f pod-fix.yaml --force
# Pattern 2: delete + apply
kubectl delete pod <pod> -n <ns>
kubectl apply -f pod-fix.yaml
- For Deployments/StatefulSets:
kubectl editorkubectl set; controller recreates pods --forceneeded only for standalone Pods with immutable fields
Admission control mistakes
| Error | Layer | Fix |
|---|---|---|
exceeded quota: compute-quota | ResourceQuota admission | Lower requests/limits or delete objects; check kubectl describe quota |
must specify limits / must specify requests | ResourceQuota + no LimitRange | Add resources to container or create LimitRange defaults |
maximum cpu usage per Container is | LimitRange admission | Stay within max; check kubectl describe limitrange |
violates PodSecurity "restricted" | Pod Security admission | Harden securityContext; use non-root image |
user cannot create (no quota keyword) | RBAC | Fix Role/RoleBinding |
kubectl apply -f pod.yaml --dry-run=server # catch admission errors before apply
kubectl auth can-i create pods -n dev # RBAC only: does NOT test admission
Exam gotchas
- Can trigger a CronJob manually:
kubectl create job manual --from=cronjob/<name> ImagePullBackOff,CrashLoopBackOff,CreateContainerConfigError→ all have distinct root causes; debug differently