kubectl describe explained: what to look for on Pods and Deployments

kubectl get pods tells you something is wrong. kubectl describe tells you why. If STATUS, READY, or RESTARTS already confuse you, start with kubectl get pods explained — then come back here for the next command.

This guide is a beginner walkthrough of describe on Pods and Deployments: what each section means, which lines matter first, and what to run after you finish reading. Official reference: kubectl describe.

The one-sentence version

• get — a table: is it Running, Pending, CrashLoopBackOff?
• describe — the story: Events, Conditions, lastState, image, probes, mounts.
• Read Events from the bottom. Then logs. Then change one thing.

get vs describe

kubectl describe pod api-7d9f8c6b5-xk2n1 -n staging
kubectl describe deploy api -n staging
kubectl describe svc api -n staging
kubectl describe cm api-config -n staging

Prefer a name from get. For many replicas, pick one unhealthy Pod: kubectl get pods -l app=api -n staging, then describe that name. Labels and selectors explained covers -l.

Describe a Pod — read in this order

Do not start at the top and grind through every field. Jump in this order: Status / Node (is it scheduled?), Containers → State and Last State, Conditions, then Events at the bottom.

Status, node, and IP

If Status is Pending and Node is empty, the scheduler has not placed the Pod. Events will usually say FailedScheduling (CPU, memory, taints, or PVC). If Node is set but Status is CrashLoopBackOff, the Pod is on a node and the container keeps dying — skip to lastState and logs.

Containers: State, Last State, Restart Count

This block is the reason describe exists. State is now. Last State is the crash you just missed.

Containers:
  api:
    Image:          ghcr.io/example/api:1.4.2
    State:          Waiting
      Reason:       CrashLoopBackOff
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
      Finished:     Mon, 01 Sep 2026 10:12:03 +0000
    Restart Count:  6

• Exit Code 1 (or other app codes) — process crashed; read logs --previous.
• Exit Code 137 — often OOMKilled (128 + 9). Confirm in Reason and the OOMKilled guide.
• Exit Code 143 — SIGTERM (128 + 15); often a probe or a rollout, not a random crash.
• ImagePullBackOff here — wrong image, tag, or registry auth; see ImagePullBackOff.

Also check the Image line. A typo in the tag is a describe finding, not a “Kubernetes is broken” finding.

Conditions

Ready False while Running is common: the process is up, the readiness probe fails, the Service has no Endpoints. That is a Service problem as much as a Pod problem — see What is a Kubernetes Service.

Events (read the bottom first)

Events are the cluster’s recent comments. They age out. If describe Events is empty, run kubectl get events -n staging --sort-by=.lastTimestamp and look at the tail.

Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Normal   Scheduled         4m    default-scheduler  Successfully assigned staging/api-… to node-2
  Normal   Pulled            3m    kubelet            Successfully pulled image
  Normal   Created           3m    kubelet            Created container api
  Normal   Started           3m    kubelet            Started container api
  Warning  Unhealthy         90s   kubelet            Readiness probe failed: HTTP 500
  Warning  BackOff           40s   kubelet            Back-off restarting failed container api

• FailedScheduling — not enough CPU/memory, taint, or unbound PVC.
• FailedCreatePodSandBox / network — CNI; not an app log problem.
• Unhealthy — probe failed (liveness restarts; readiness drops traffic).
• BackOff / CrashLoopBackOff — kubelet waiting; the cause is Last State + logs.
• FailedMount — ConfigMap, Secret, or volume name mismatch. See ConfigMap vs Secret.

Describe a Deployment

Describe the Deployment when many Pods look wrong, or when a rollout is stuck. You want replica counts and Deployment conditions — not every Pod field. Refresh What is a Deployment if replicas vs Pods is still fuzzy.

kubectl describe deploy api -n staging
# Replicas:               3 desired | 3 updated | 2 total | 1 available | 1 unavailable
# Conditions:
#   Type           Status  Reason
#   Progressing    True    NewReplicaSetAvailable
#   Available      False   MinimumReplicasUnavailable
# OldReplicaSets / NewReplicaSet  — which revision is live

• desired > available — some Pods are not Ready (probes, crashes, Pending).
• updated != desired during a rollout — wait, or describe the new Pods.
• OldReplicaSets still listed — a previous revision has Pods; labels may have changed.

Then describe one bad Pod from that Deployment. Deployment describe does not replace Pod Events.

After describe — what to run next

kubectl get pods -n staging
kubectl describe pod POD_NAME -n staging
kubectl logs POD_NAME -n staging --tail=200
kubectl logs POD_NAME -n staging --previous
kubectl get events -n staging --sort-by=.lastTimestamp

Common beginner mistakes

• Reading only the top of describe and skipping Events.
• Describing the Deployment and never describing a Pod — Events live on the Pod.
• Forgetting -n and describing a name that exists in default, not staging.
• Looking at current logs after a crash — you need --previous for the dead container.
• Treating Warning Events as noise. Age matters: a Warning from 20 minutes ago may be the cause.
• Editing YAML before you can point at one Event line. Describe first, change second.

Same checks in natural language (optional)

kprompt can run the describe/logs loop as a read. Mutations still show a plan and ask for approval on a TTY.

kprompt "describe pod for deployment api in staging"
kprompt "describe deployment api in staging"
kprompt "show events for api in staging"
kprompt "explain why api pods are crashing in staging"

What to learn next

You can now move from the get table to a describe story. The next beginner posts in this track are not published yet: Kubernetes requests and limits, then liveness vs readiness probes. Until those ship, go deeper on the failures describe already pointed at: CrashLoopBackOff, ImagePullBackOff, and OOMKilled. If you skipped the table, start with kubectl get pods explained.