Sign In

Curriculum 7: Reading & Inspecting

kubectl describe Deep Dive

12 min · 15 XP

Reading kubectl describe Output

kubectl describe produces dense output. Knowing how to read each section turns it into your most effective troubleshooting tool.

Anatomy of describe Output

When you describe a Pod, the output is organized into predictable sections. Here is how to read each one.

Metadata Section

Name:             my-app-7d4b8c6f5-abc12
Namespace:        production
Labels:           app=my-app
                  pod-template-hash=7d4b8c6f5
Annotations:      kubernetes.io/psp: restricted

This tells you the Pod's identity, which namespace it belongs to, and its labels and annotations.

Conditions

Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True

Conditions tell you the Pod's health at a glance. If any condition is False, that is where to focus:

  • PodScheduled=False: The scheduler cannot find a suitable node. Check resource requests, node taints, and affinity rules.
  • Initialized=False: Init containers have not completed. Check init container logs.
  • ContainersReady=False: One or more containers failed readiness probes.
  • Ready=False: The Pod is not ready to receive traffic.

Container Details

Containers:
  nginx:
    Image:          nginx:1.25
    Port:           80/TCP
    State:          Running
      Started:      Mon, 15 Jan 2025 10:00:00 UTC
    Ready:          True
    Restart Count:  0
    Limits:
      cpu:     500m
      memory:  256Mi
    Requests:
      cpu:     100m
      memory:  128Mi

Check the State field carefully. Common states include:

  • Running -- the container is healthy
  • Waiting (CrashLoopBackOff) -- the container keeps crashing and restarting
  • Waiting (ImagePullBackOff) -- the image cannot be pulled
  • Terminated -- the container exited

Events Section

Events are listed chronologically at the bottom:

Events:
  Type     Reason            Age   Message
  Normal   Scheduled         5m    Successfully assigned to worker-1
  Normal   Pulled            5m    Container image already present
  Normal   Created           5m    Created container nginx
  Normal   Started           5m    Started container nginx

Warning events are the most important clues during troubleshooting:

  Warning  FailedScheduling  2m    0/3 nodes are available: insufficient memory
  Warning  Unhealthy         30s   Readiness probe failed: connection refused

Describing Other Resources

Different resource types show different sections:

# Node describe shows allocatable resources and running pods
kubectl describe node worker-1

# Service describe shows endpoints and selector
kubectl describe service my-service

# Deployment describe shows replica status and rollout events
kubectl describe deployment my-app

Key Takeaways

  • Read Conditions first to identify which stage is failing
  • Container State tells you exactly what each container is doing
  • Events at the bottom are your primary troubleshooting timeline
  • Warning events almost always point to the root cause
  • Different resource types show different sections, but the pattern is consistent