kubectl describe: Usage, Options & Common CI Errors
The richest single-command view of why a resource is unhappy.
kubectl describe prints a human-readable summary of an object and, crucially, the Events attached to it. It is the fastest way to find out why a pod will not start or a deploy will not progress.
What it does
kubectl describe RESOURCE NAME aggregates the object spec, status, and the recent Events the controllers emitted about it. For a pod it shows the container states, restart counts, conditions, and the scheduler/kubelet events - the exact reason behind ImagePullBackOff, CrashLoopBackOff, or Pending.
Common usage
kubectl describe pod my-pod
kubectl describe deploy/web # deployment + rollout conditions
kubectl describe node ip-10-0-1-5 # taints, pressure, allocatable
kubectl describe pod -l app=web # all pods matching a labelCommon errors in CI
The events you read in describe explain most failed deploys: "Failed to pull image ... ImagePullBackOff" is a bad tag or missing registry credentials; "0/3 nodes are available: 3 Insufficient cpu" is a resources.requests value larger than any node; "Back-off restarting failed container" is a crashing process - pair describe with kubectl logs --previous to see why. Events are time-boxed (default ~1h), so in slow pipelines they may have aged out; capture them immediately on failure rather than after retries.