YAML manifest errors

Error messageLikely causeFix
cannot be handled as a PodWrong or missing apiVersionSet apiVersion: v1 for Pod
unknown field "xxx"Typo in field nameCheck kubectl explain <resource>
error parsing ...Invalid YAML syntaxCheck indentation, colons, quotes
no matches for kind "X" in version "Y"Wrong apiVersion for the kindkubectl 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: sleeep instead of sleep
  • Missing shell wrapper: sleep 3600 as command: [sleep, "3600"] works, but shell constructs need ["/bin/sh", "-c", "..."]
  • Wrong args order: command: ["3600", "sleep"]
  • args used when command needed (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 edit or kubectl set; controller recreates pods
  • --force needed only for standalone Pods with immutable fields

Admission control mistakes

ErrorLayerFix
exceeded quota: compute-quotaResourceQuota admissionLower requests/limits or delete objects; check kubectl describe quota
must specify limits / must specify requestsResourceQuota + no LimitRangeAdd resources to container or create LimitRange defaults
maximum cpu usage per Container isLimitRange admissionStay within max; check kubectl describe limitrange
violates PodSecurity "restricted"Pod Security admissionHarden securityContext; use non-root image
user cannot create (no quota keyword)RBACFix 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