Describe Kubernetes Pods With kubectl

In Kubernetes, Pods create a shared environment for one or more containerized application. This shared environment allows containers to communicate and share common resources easily.

The short answer

To display the detailed information of a single Pod, you can use the [.inline-code] kubectl describe pod[.inline-code]  command followed by the name of the Pod:

$ kubectl describe pod <pod_name>

For example: 

$ kubectl describe pod my-pod

Upon execution, the above command will output verbose details about the Pod, such as its status, IP address, associated namespace, ports, events, the status of the containers running within it, and more. These comprehensive details are helpful when debugging or troubleshooting any potential issues with your running Pod.

You can learn more about troubleshooting Pods in Kubernetes by reading our article on how to get the logs of Pods using the kubectl command.

[#easily-recall-with-ai]Easily retrieve this command using Warp’s AI Command Suggestions[#easily-recall-with-ai]

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Suggestions feature:

Entering [.inline-code] k8 describe pod[.inline-code]  in the AI Command Suggestions will prompt a [.inline-code] kubectl[.inline-code]  command, which can be inserted quickly into your shell by doing [.inline-code] CMD+ENTER[.inline-code].

[#describe-pods-in-a-namespace]Describing Pods in a namespace[#describe-pods-in-a-namespace]

To describe a pod in a specified namespace, you can use the [.inline-code] kubectl describe pod[.inline-code]  command with the [.inline-code] -n[.inline-code]  flag (short for  [.inline-code] --namespace[.inline-code] ):

$ kubectl describe pod <pod_name> -n <namespace>

For example:

$ kubectl describe pod my-pod -n my-namespace

Note that, if you attempt to describe a Pod that does not exist in the specified namespace, the command will result in an error, indicating that the Pod does not exist.

[#describe-all-pods]Describing all Pods at once [#describe-all-pods]

To describe all the pods in your cluster at once, you can use the following command:

$ kubectl describe pods

Upon execution, the above command will provide details for every pod within your cluster. This will help you see the status of all pods at once, making it easier to check their overall health instead of going through them individually.

[#understanding-the-pod-description] Understanding the output of the [.inline-code] kubectl describe pod[.inline-code] command [#understanding-the-pod-description]

While the [.inline-code] kubectl describe pod[.inline-code]  command displays extensive information about Pods, its output can be quite overwhelming to navigate.

Here’s a breakdown of the essential information provided by this command.

[#the-pod-information] Main Pod information [#the-pod-information]

The first section contains general information about the Pod itself.

Where:

• Name is the unique name of the Pod.
• Namespace is the namespace the Pod is associated with.
• Priority specifies the preference for pod execution by the Kubernetes scheduler.
• Service Account is the pod identity used for accessing cluster resources.
• Node represents a virtual or physical machine where the Pod is executed.
• Start Time is the timestamp of the Pod creation.
• Labels are user-defined key-value pairs used to identify the Pod.
• Annotations are additional metadata for the Pod.
• Status is the current execution status of the Pod.
• IP is the IP address of the Pod.

[#the-pod-status] Understanding the Pod status [#the-pod-status]

The Pod [.inline-code] Status[.inline-code]  property gives an immediate overview of the Pod’s current health.

It takes 5 possible values:

• [.inline-code] Pending[.inline-code] : the Pod is created, but its containers are not yet ready to run.
• [.inline-code] Running[.inline-code] : the Pod is actively running on the node, with at least one container in a running state. 
• [.inline-code] Succeeded[.inline-code] : all containers in the Pod have terminated successfully (with an exit status of [.inline-code] 0[.inline-code] ).
• [.inline-code] Failed[.inline-code] : one or more containers within your Pod have terminated with a non-zero exit status, signifying an error.
• [.inline-code] Unknown[.inline-code] : the state of the Pod cannot be determined, and is typically temporary due to node failures or network issues.

Note that, if a Pod gets stuck in a status different from Running for a long period of time, this might indicate that there is a potential issue with the functioning of the Pod.

Also note that, if the Pod gets stuck in the Pending state, it cannot be scheduled on a node due to insufficient resources. You can use the official guide for debugging pods and debugging running pods to identify the bottleneck issues of your Pod.

[#the-containers-section] The Containers section [#the-containers-section]

The Containers section provides detailed information about the containers running within the Pod, such as their current status and configuration.

Containers running within Pods can be in three different states:

• [.inline-code] Waiting[.inline-code] : the container is not yet running due to some initial setup or readiness checks.
• [.inline-code] Running[.inline-code] : the container is actively running.
• [.inline-code] Terminated[.inline-code] : the container has finished executing and has exited, either successfully or due to a failure that caused its termination.

[#the-conditions-section] The Conditions section [#the-conditions-section]

The Conditions section provides information about a list of conditions a Pod has passed (or not), each of which describes a specific aspect of the Pod's state.

Some of the most common conditions are:

• [.inline-code]Initialized[.inline-code] which indicates whether all init containers have completed successfully.
• [.inline-code] Ready[.inline-code] which indicates whether the Pod is fully operational and is able to serve requests.
• [.inline-code] ContainersReady[.inline-code] which indicates whether all containers in the Pod are ready and able to accept traffic.
• [.inline-code] PodScheduled[.inline-code] which indicates whether the Pod has been scheduled to run on a node.

You can learn more about conditions on the official documentation page.

[#the-events-section]The Events section[#the-events-section]

The Events section provides a chronological log of events and activities related to your Pod. Common types of events include pod scheduling, container start, image pulling, and so on.

Each log usually contains 5 properties:

• Type: the type of event like [.inline-code] Normal[.inline-code] , [.inline-code]Warning[.inline-code] , or [.inline-code] Error[.inline-code] .
• Reason: a brief code describing the event (e.g. Pulling, Created).
• Age: the time when the event occurred.
• From: the component responsible for logging the event.
• Message: the detailed description of the event.

These events will help identify failures in your running Pod. For example, if a container within a Pod cannot start, the [.inline-code]Reason[.inline-code]  will be set to [.inline-code] ContainerCannotRun[.inline-code]  and accompanied by the additional context in the [.inline-code] Message[.inline-code]  property.

[#describe-pods-with-a-config-file]Describing a Pod using a configuration file[#describe-pods-with-a-config-file]

To describe a Pod using a YAML or JSON file containing the pod’s configuration, you can use the [.inline-code] kubectl describe pod[.inline-code] command with the [.inline-code] -f[.inline-code] flag:

$ kubectl describe -f <path>

Where:

• [.inline-code] path[.inline-code]  is the relative or absolute path of the Pod's configuration file.

For example:

$ kubectl describe -f ./myPodConfiguration.yaml

This command will display all the details of your Pod, such as its status, the status of containers running within it, IP address, associated namespace, ports, events, and more (similar to the [.inline-code] kubectl describe pod[.inline-code]  command).

[#describe-pods-with-yaml-and-json] Describing a Pod using YAML and JSON[#describe-pods-with-yaml-and-json]

By default, the [.inline-code] kubectl describe pod[.inline-code] command doesn’t provide an option to output the information in YAML or JSON format.

To do so, you can use the [.inline-code] kubectl get pods[.inline-code] command instead with the [.inline-code] -o[.inline-code]  flag, followed by the name of the desired format:

$ kubectl get pods <pod_name> -o <format>

Where:

• [.inline-code] format[.inline-code] is either [.inline-code] yaml[.inline-code] or [.inline-code] json[.inline-code] .

For example: 

$ kubectl get pod my-pod -o yaml

The above command displays the pod information in YAML format, including details about the Pod, its containers, status, and more.