kubectl describe: Get Resource Details and Events

1. Beyond the Summary: Introducing kubectl describe

While kubectl get gives you a one-line summary, kubectl describe provides a detailed, human-readable report. It aggregates information about a resource's configuration, its current state, and—most importantly—a chronological list of events related to it.

Think of it this way:

• kubectl get: Tells you a Pod's STATUS is ImagePullBackOff.
• kubectl describe: Tells you why, by showing an event that says Failed to pull image... repository does not exist or may require authorization.

This distinction is crucial for effective troubleshooting. To get a foundational understanding of the command, please start by reading the following article from Spacelift.

The basic syntax is simple and follows the pattern you've already learned:

# Describe a specific pod
kubectl describe pod <pod-name>

# You can also use the shorthand for resource types
kubectl describe po <pod-name>

# Describe a deployment in a specific namespace
kubectl describe deployment <deployment-name> -n <namespace-name>

2. A Deep Dive into kubectl describe pod

The most common and powerful use of kubectl describe is on a Pod. Let's break down its output, as understanding its structure is key to using it effectively.

The output is typically divided into several key sections:

• Metadata: The top section shows basic information like Name, Namespace, Labels, Annotations, and the Node the Pod is scheduled on.
• Status: The current phase of the Pod (Running, Pending, Failed, etc.) and its IP address.
• Containers: A detailed breakdown for each container within the Pod, including the Image used, its current State (e.g., Running), any Restarts, and resource requests/limits.
• Conditions: A series of True/False statuses that represent the lifecycle state of the Pod. Key conditions include:
  • PodScheduled: Was the scheduler able to assign this Pod to a Node?
  • Initialized: Have all Init Containers completed successfully?
  • ContainersReady: Are all main containers in the Pod reporting that they are ready?
  • Ready: Is the Pod as a whole ready to serve traffic?
• Volumes: Information about any volumes mounted into the Pod's containers.
• Events: This is often the most valuable section for debugging. It's a time-ordered list of events that have affected the Pod, logged by various Kubernetes components. You'll see messages from the scheduler about placement decisions and messages from the kubelet on the node about pulling images and starting containers.

This short video provides a clear walkthrough of the describe pod command and its output.

For a comprehensive reference on every field in the describe pod output, you can refer to the "Understanding the kubectl describe output" section of the Spacelift article (LINK) you read earlier. It's a great resource to bookmark.

3. Practical Troubleshooting Scenarios

Your work as a Platform Engineer often involves figuring out why an application isn't running correctly. kubectl describe is your first step in diagnosing these common issues.

The following video from "Java Home Cloud" is excellent because it demonstrates how to use kubectl describe to debug the three most common Pod failure scenarios.

These examples highlight a critical workflow:

1. Use kubectl get pods to see a Pod is in an error state.
2. Use kubectl describe pod <pod-name> to find out why.
3. Focus on the Events section for explicit error messages from Kubernetes components.

4. Describing Other Resources

While kubectl describe pod is the most common use case, you can use describe on almost any Kubernetes resource. The output is always tailored to be most useful for that specific resource type.

Here are a few other examples relevant to your role:

• kubectl describe deployment <name>: Shows the deployment's selector, replica status (desired, current, available), rolling update strategy, and events related to scaling the underlying ReplicaSets. This is useful for debugging a stuck rollout.
• kubectl describe service <name>: Shows the service's selector, type, IP, and ports. Critically, it also shows the Endpoints, which are the actual Pod IPs the service is currently directing traffic to. If your application is unreachable, checking that the Endpoints list is populated and correct is a vital first step.
• kubectl describe node <name>: Provides detailed information about a worker node's health, including its Conditions (like MemoryPressure or DiskPressure), its resource capacity and allocations, and a list of all Pods running on it. This is essential for diagnosing cluster-wide resource shortages or node-specific failures.

Conclusion

You have now added kubectl describe to your toolkit, moving from simply observing status to actively diagnosing problems. This command bridges the gap between seeing a problem with kubectl get and digging into application-specific issues with kubectl logs.

Key Takeaways:

• kubectl describe provides a detailed, human-readable overview of a Kubernetes resource, aggregating configuration, status, and events.
• It is the primary command for understanding why a resource is in a particular state (e.g., Pending, CrashLoopBackOff).
• The Events section is the most critical part for troubleshooting, as it contains chronological messages from Kubernetes components like the scheduler and kubelet.
• While most powerful for Pods, describe provides valuable, context-specific information for other resources like Deployments, Services, and Nodes.

In the case of a CrashLoopBackOff, describe tells you that the container is restarting, but it doesn't tell you why the application inside is failing. For that, we need to look inside the container at its standard output. Our next lesson will do just that, focusing on kubectl logs.