kubectl describe: Command Reference for CI/CD
The richest single-command view of why a resource is unhappy.
kubectl describe prints a human-readable summary of an object plus the Events controllers emitted about it. It is the fastest way to find out why a pod will not start. This reference shows what it covers and how to capture it on CI failure.
Common flags and usage
- describe pod <name>: container states, restart counts, and Events
- describe deploy/<name>: rollout conditions and replica status
- describe node <name>: taints, pressure conditions, allocatable
- -l, --selector: describe every object matching a label
- --show-events=false: suppress the Events block
Example
# Capture diagnostics the moment a rollout fails
kubectl rollout status deploy/web --timeout=120s || {
kubectl describe deploy/web
kubectl describe pod -l app=web
exit 1
}In CI
The Events section explains most failed deploys: "Failed to pull image" is a bad tag or missing credentials, "Insufficient cpu" is an oversized request. Events are time-boxed (default ~1h), so capture describe output immediately on failure rather than after retries have aged it out.
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.
# 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 nodesKey takeaways
- The Events block is the payoff: it names the real failure cause.
- Events expire (~1h default), so capture them on failure, not later.
- Pair describe with kubectl logs --previous for crash loops.