List Pods With kubectl

In Kubernetes, Pods provide a shared environment for one or more containerized applications, allowing the containers to communicate and share common resources.

The short answer

To list all the Pods in your Kubernetes cluster at once, you can use the [.inline-code]kubectl get pods[.inline-code] command as follows:

$ kubectl get pods

This command provides details for every Pod within your cluster including their status, allowing you to quickly evaluate its overall health and troubleshoot any potential Pod issues, such as non-running or failed Pods.

[#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]k8s list pods[.inline-code] in the AI Command Suggestions will prompt a [.inline-code]kubectl[.inline-code] command that can then quickly be inserted into your shell by doing [.inline-code]CMD+ENTER[.inline-code].

[#understand-the-output] Understanding the output of the [.inline-code]kubectl get pods[.inline-code] command [#understand-the-output]

By default, the [.inline-code]kubectl get pods[.inline-code] command provides details about all the Pods in your cluster in a tabular format:

Where:

• NAME is the unique name of the Pod.
• READY is the number of containers in the Pod that are ready. For example, [.inline-code]1/1[.inline-code] indicates that all containers in the Pod are ready and running,whereas [.inline-code]0/2[.inline-code] indicates that none are running.
• STATUS is the current execution of the status (such as Pending, Running, Succeeded, Failed or Unknown).
• RESTARTS is the number of times the Pod has restarted. It will indicate the Pod’s stability and the occurrence of any issues that might have initiated the restart.
• AGE is the time when Pod was created.

Understanding 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, this may indicate a potential issue with the functioning of the Pod.

Listing all Pods with additional information

To display additional information about the Pods, you can use the [.inline-code]-o wide[.inline-code] flag (short for [.inline-code]--output wide[.inline-code]) as follows: 

 $ kubectl get pods -o wide

Where:

• IP is the IP address of the Pod.
• NODE is the Node where the Pod is currently running.
• NOMINATED NODE is the preferred Node to run the Pod on, identified by the Kubernetes scheduler based on the Pod’s resource requirements.
• READINESS GATES are the conditions that must be satisfied for the Pod to be considered ready.

Additionally, you can read our article on how to describe a Kubernetes Pod with kubectl to retrieve more comprehensive information about Pods.

[#list-pods-by-name] Listing Pods by name [#list-pods-by-name]

To list one or more Pods by name in your Kubernetes cluster, you can use the [.inline-code]kubectl get pods[.inline-code] command as follows:

$ kubectl get pods <pod_name …>

Where:

• [.inline-code]pod_name[.inline-code] is a list of Pod names separated by a space character.

For example:

$ kubectl get pods myPod1 myPod2

Upon execution, the above command will output a table of information about the Pods named [.inline-code]myPod1[.inline-code] and [.inline-code]myPod2[.inline-code], including their name, status, restart count, and age.

Note that if you specify a Pod name that does not exist, the command will result in an error indicating that the specified Pod was not found.

[#list-pods-in-namespace] Listing Pods in a namespace [#list-pods-in-namespace]

In Kubernetes, namespaces provide a logical way to separate resources within an application. 

To list all the Pods in a specified namespace, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]-n[.inline-code] flag (short for [.inline-code]--namespace[.inline-code]):

$ kubectl get pods  -n <namespace>

For example:

$ kubectl get pods -n myNamespace

Upon execution, the above command will list all the Pods and their status in the Namespace named [.inline-code]myNamespace[.inline-code].

If you want to learn more about namespaces, you can read our article on how to create a namespace in Kubernetes with kubectl.

Listing Pods in all namespaces

By default, the [.inline-code]kubectl get pods[.inline-code] only lists Pods within the current namespace.

To list Pods across all namespaces, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]--all-namespaces[.inline-code] flag:

$ kubectl get pods --all-namespaces 

[#list-pods-by-label] Listing Pods by label [#list-pods-by-label]

Labels are key-value pairs attached to the Kubernetes objects that organize resources based on specific criteria.

To list Pods based on a specific label, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]-l[.inline-code] flag (short for [.inline-code]--label[.inline-code]):

$ kubectl get pods -l <label>=<value>

Where:

• [.inline-code]label[.inline-code] is the key of the label. 
• [.inline-code]value[.inline-code] is the value associated with the label.

For example:

$ kubectl get pods -l app=myapp

Upon execution, the above command will display all Pods with the label [.inline-code]app=myapp[.inline-code] assigned to them.

Displaying the labels of all Pods

To view the labels associated with all the Pods at once, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]--show-labels[.inline-code] flag:

$ kubectl get pods --show-labels

Upon execution, the above command will output an additional column showing any labels associated with Pods.

[#list-pods-with-yaml-or-json] Listing Pods in the YAML and JSON formats [#list-pods-with-yaml-or-json]

By default, the output format of the [.inline-code]kubectl get pods[.inline-code] command is a table. However, you can specify other formats, such as YAML or JSON using the [.inline-code]-o[.inline-code] flag:

$ kubectl get pods -o <output_format>

Where:

• [.inline-code]output_format[.inline-code] is one of [.inline-code]yaml[.inline-code] or [.inline-code]json[.inline-code].

For example:

$ kubectl get pods -o yaml

Upon execution, the above command will display comprehensive details about all the Pods in the specified YAML format.

[#filter-pods-by-field-selector] Filtering Pods using a field selector [#filter-pods-by-field-selector]

To filter the list of Pods based on a specific field, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]--field-selector[.inline-code] flag:

$ kubectl get pods --field-selector=<field_name>=<field_value>

Where:

• [.inline-code]field_name[.inline-code] is a JSONPath expression used for selecting a specific field.
• [.inline-code]field_value[.inline-code] is the value for the specified field.

For example, this command will filter and display the list of all Pods running on the Node named [.inline-code]node01[.inline-code]:

$ kubectl get pods --field-selector=spec.nodeName=node01

And this command will filter and display all Pods in a [.inline-code]Running[.inline-code] phase:

$ kubectl get pods --field-selector=status.phase=Running

You can learn more about JSONPath expressions by visiting the official Kubernetes documentation page.

[#sort-the-list-of-pods] Sorting the output of the [.inline-code]kubectl get pods[.inline-code] command [#sort-the-list-of-pods]

To sort the output of the [.inline-code]kubectl get pods[.inline-code] command based on a specific field, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]--sort-by[.inline-code] flag:

$ kubectl get pods --sort-by=<expression>

Where: 

• [.inline-code]expression[.inline-code] is a JSONPath expression.

For example, this command will display the list of all Pods sorted by their names in ascending order:

$ kubectl get pods --sort-by=.metadata.name

And this command will display the list of all Pods sorted by their restart count:

$ kubectl get pods --sort-by=.status.containerStatuses[0].restartCount

Note that the [.inline-code].status.containerStatuses[0].restartCount[.inline-code] expression selects the restart count of the first container in the Pod.

[#customize-the-pod-list] Customizing the output of the [.inline-code]kubectl get pods[.inline-code] command [#customize-the-pod-list]

To customize the output columns of the [.inline-code]kubectl get pods[.inline-code] command, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]-o custom-columns[.inline-code] flag:

$ kubectl get pods -o custom-columns=<custom_column_name>:<expression>

• [.inline-code]custom_column_name[.inline-code] is the name you want to assign to a column. 
• [.inline-code]expression[.inline-code] is a JSONPath expression.

For example:

$ kubectl get pods -o custom-columns=NAME:.metadata.name,QoS_CLASS:.status.qosClass

Upon execution, the above command will output two columns, [.inline-code]NAME[.inline-code] populated with the values of [.inline-code]metadata.name[.inline-code] and [.inline-code]QoS_CLASS[.inline-code] populated with the values of [.inline-code]status.qosClass[.inline-code].

Customizing the output using a template file

To customize the output columns of the [.inline-code]kubectl get pods[.inline-code] command using a template file (i.e. a predefined column configurations), you can use the [.inline-code]-o custom-column-file[.inline-code] flag:

$ kubectl get pods -o custom-columns-file=<template_file_path>

Where:

• [.inline-code]template_file_path[.inline-code] is an absolute or relative file path for a template file. 

For example:

$ kubectl get pods -o custom-columns-file=./myTemplate.txt

Where the [.inline-code]myTemplate.txt[.inline-code] file contains:

NAME                QoS_CLASS
metadata.name status.qosClass

Upon execution, the above command will output two columns [.inline-code]NAME[.inline-code] populated with the values of [.inline-code]metadata.name[.inline-code] and [.inline-code]QoS_CLASS[.inline-code] populated with the values of [.inline-code]status.qosClass[.inline-code].

[#extract-pod-information] Extracting Pod information [#extract-pod-information]

To output specific field values of Pods, you can use the [.inline-code]kubectl get pods[.inline-code] command with the [.inline-code]-o[.inline-code] flag (short for [.inline-code]--output[.inline-code]) combined with a JSONPath expression as follows:

$ kubectl get pods -o jsonpath=”<expression>”

Where:

• [.inline-code]expression[.inline-code] is a JSONPath expression.

For example, this command will extract the image name of each container running your cluster’s Pods.

$ kubectl get pods -o jsonpath=”{.items[*].spec.containers[*].image}”

Where:

• [.inline-code].items[*][.inline-code] indicates the iteration over each Pod.
• [.inline-code].spec[.inline-code] specifies the Pod’s specification.
• [.inline-code].containers[*][.inline-code] marks the iteration over each container within the Pod.
• [.inline-code].image[.inline-code] retrieves the image name for each container.