kubectl describe: Usage, Options & Common CI Errors
By Kaveh Alemi·Latchkey
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
Terminal
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 label
Common 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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
Frequently asked questions
kubectl describe: Usage, Options & Common CI Errors?
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 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
