kubectl describe

When to Use kubectl describe

kubectl describe is your primary debugging tool when a resource is misbehaving. Unlike kubectl get, which gives a concise summary, describe provides the full picture: configuration, status, conditions, volumes, and critically, the events stream that tells you what Kubernetes has been doing with that resource.

Understanding the Output

The describe output is divided into several sections depending on the resource type. For a Pod, you will see:

# Describe a pod and pipe through less for easier reading
kubectl describe pod my-app-7d6f8b4c5-x2k9m | less

Key sections to pay attention to:

• Labels and Annotations: Metadata attached to the resource that drives selection and tooling behavior.
• Containers: Image, ports, environment variables, resource requests and limits, and volume mounts for each container.
• Conditions: Boolean status fields like Ready, Initialized, PodScheduled, and ContainersReady.
• Events: A chronological log of actions Kubernetes has taken, including scheduling, pulling images, starting containers, and any failures.

Debugging with describe

The Events section is where most troubleshooting begins. Events persist for a limited time (default one hour), so check them promptly when issues arise.

# Check why a pod is in CrashLoopBackOff
kubectl describe pod crashing-pod -n production

# Look for image pull errors on a specific deployment
kubectl describe deployment my-app | grep -A 5 "Events"

Common event messages and what they mean:

• FailedScheduling: The scheduler cannot place the pod. Check resource requests, node affinity, taints, and tolerations.
• ImagePullBackOff: Kubernetes cannot pull the container image. Verify the image name, tag, and registry credentials.
• FailedMount: A volume could not be mounted. Check PVC status and storage class availability.
• OOMKilled: The container exceeded its memory limit. Increase the memory limit or investigate the memory leak.

Describing Nodes

Node descriptions are essential for capacity planning and diagnosing cluster-wide issues.

# Check allocatable resources on a node
kubectl describe node worker-1

# Look at taints that might prevent scheduling
kubectl describe node worker-1 | grep -A 5 Taints

The node description shows allocated resources versus capacity, which helps identify whether the cluster is running out of CPU or memory. The Conditions section reveals whether a node has disk pressure, memory pressure, or PID pressure.

Describing Other Resources

Nearly every Kubernetes resource type supports describe. Services, Ingresses, ConfigMaps, and PersistentVolumeClaims all provide useful debugging information.

# Check endpoints behind a service
kubectl describe svc my-service

# Verify ingress rules and backend configuration
kubectl describe ingress my-ingress

# Check storage class binding mode
kubectl describe pvc my-claim

For Services, the describe output shows the Endpoints list, which tells you which pods are backing the service. An empty Endpoints list usually means the label selector on the Service does not match any running pods.

Tips for Efficient Usage

Combine describe with label selectors to narrow your focus when dealing with many pods in a deployment:

# Describe only pods from a specific release
kubectl describe pods -l app=nginx,version=v2

# Describe all pods on a specific node
kubectl describe pods --field-selector spec.nodeName=worker-3

When the output is long, use grep to jump to the relevant section. The section headers are consistent, so you can reliably extract specific parts:

# Extract just the events
kubectl describe pod my-pod | grep -A 20 "^Events:"

# Check resource limits across all containers
kubectl describe pod my-pod | grep -A 3 "Limits:"

The describe command does not support -o json or -o yaml output formatting. If you need structured output, use kubectl get -o yaml or kubectl get -o json instead. The describe output is human-readable only, which makes it ideal for interactive debugging but unsuitable for scripting.