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.

Key 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.

Related guides