Edit

List pods in an Azure Kubernetes Service (AKS) cluster

This article shows you how to list pods in an Azure Kubernetes Service (AKS) cluster using kubectl. Listing pods is one of the most common tasks for understanding cluster state, monitoring workloads, and troubleshooting application issues.

Prerequisites

  • An existing AKS cluster. If you don't have one, create one using the Azure CLI, the Azure portal, or Terraform.

  • The Azure CLI installed and authenticated using az login.

  • Permission to retrieve the cluster credentials, such as the Azure Kubernetes Service Cluster User Role.

  • Permission to list pods in the namespaces you want to query. Listing pods across all namespaces requires cluster-scoped permission.

  • The kubectl command-line tool installed. You can install it using az aks install-cli.

  • Your kubeconfig configured to point to your cluster. Run the following command to configure it:

    az aks get-credentials --resource-group <resource-group-name> --name <cluster-name>

    Replace <resource-group-name> and <cluster-name> with your own values.

Understand pod namespaces in AKS

AKS clusters organize pods into namespaces. By default, kubectl commands target the default namespace only. AKS clusters include several system namespaces you should be aware of:

Namespace Purpose
default Where your workloads land unless you specify another namespace.
kube-node-lease Lease objects that enable nodes to communicate their availability to the control plane.
kube-system Kubernetes and AKS system components, such as coredns, konnectivity-agent, and metrics-server. The components vary based on the cluster configuration and enabled add-ons.
kube-public Publicly readable resources, mostly used by cluster bootstrapping.
gatekeeper-system Azure Policy add-on pods, if enabled.

Most day-to-day debugging targets either default or the namespace your application is deployed to. To request pods across all namespaces, use the -A flag described below. The command returns pods only if you have permission to list them at cluster scope.

List pods in the default namespace

To list all pods in the current namespace (by default, default), run:

kubectl get pods

Example output:

NAME                              READY   STATUS    RESTARTS   AGE
store-front-1a23b4c5d6-7ef8g      1/1     Running   0          2d
order-service-90h1i2j3kl-mnop4    1/1     Running   0          2d
product-service-5q6r7s8t9-uv0wx   1/1     Running   0          2d

The output columns mean:

Column Description
NAME The pod's unique name within the namespace.
READY The ratio of ready containers to total containers. 1/1 means all reported containers are ready. A container can be running but not ready, such as when its readiness probe fails.
STATUS A user-facing summary generated by kubectl, such as Running, CrashLoopBackOff, or Terminating. This value isn't the same as the pod's API phase, which can be Pending, Running, Succeeded, Failed, or Unknown.
RESTARTS How many times the pod's containers have restarted. Frequent restarts indicate a potential issue.
AGE How long ago the pod was created.

List pods across all namespaces

To list pods across all namespaces, including system pods, use the -A (or --all-namespaces) flag. You must have permission to list pods at cluster scope:

kubectl get pods -A

Example output:

NAMESPACE        NAME                                  READY   STATUS    RESTARTS   AGE
default          store-front-1a23b4c5d6-7ef8g          1/1     Running   0          2d
kube-system      coredns-12a34bc567-8defg              1/1     Running   0          5d
kube-system      coredns-12a34bc567-hijkl              1/1     Running   0          5d
kube-system      kube-proxy-abc1d                      1/1     Running   0          5d
kube-system      metrics-server-1a2b345c67-defg8       1/1     Running   0          5d

The output adds a NAMESPACE column identifying which namespace each pod belongs to.

List pods in a specific namespace

To scope your query to one namespace, use the -n (or --namespace) flag:

kubectl get pods -n <namespace>

For example, to list only the AKS system pods:

kubectl get pods -n kube-system

Get detailed information about each pod

To include the pod's IP address and the node it is running on, add the -o wide flag:

kubectl get pods -o wide

Example output:

NAME                              READY   STATUS    RESTARTS   AGE   IP             NODE                                NOMINATED NODE   READINESS GATES
store-front-1a23b4c5d6-7ef8g      1/1     Running   0          2d    10.244.1.4     aks-nodepool1-12345678-vmss000000    <none>           <none>
order-service-90h1i2j3kl-mnop4    1/1     Running   0          2d    10.244.2.11    aks-nodepool1-12345678-vmss000001    <none>           <none>

The NODE column shows which AKS node is running each pod. This is useful when you need to correlate pod behavior with node-level resource pressure or events.

Filter pods by label

Pods in AKS are typically labeled during deployment. To list pods that match a specific label, use the -l (or --selector) flag:

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

For example, if your pods are labeled app=store-front:

kubectl get pods -l app=store-front

To list all pods that have a particular label key regardless of value:

kubectl get pods -l app

To combine multiple label conditions:

kubectl get pods -l app=store-front,environment=production

List pods on a specific node

To find all pods running on a specific AKS node, use a field selector:

kubectl get pods -A --field-selector spec.nodeName=<node-name>

Replace <node-name> with the name of the node, which you can find by running kubectl get nodes.

Control the output format

JSON output

To retrieve the full pod definition as JSON, use -o json. This is useful for programmatic access or when integrating with Azure CLI scripts:

kubectl get pods -o json

To extract a specific field using a JSON path expression:

kubectl get pods -o jsonpath='{.items[*].metadata.name}'

YAML output

To retrieve the full pod specification as YAML, use -o yaml. This is often used for debugging or when you want to save the pod definition for later use:

kubectl get pod <pod-name> -o yaml

Custom columns

To define exactly which fields appear in the output table, use -o custom-columns:

kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName

Example output:

NAME                              STATUS    NODE
store-front-1a23b4c5d6-7ef8g      Running   aks-nodepool1-12345678-vmss000000
order-service-90h1i2j3kl-mnop4    Running   aks-nodepool1-12345678-vmss000001

Watch pods in real time

To watch pods update in real time (useful during deployments, rollouts, or troubleshooting), add the -w (or --watch) flag:

kubectl get pods -w

Press Ctrl+C to stop watching. You can combine -w with any of the namespace or label flags described above.

Get details about a specific pod

To see detailed information about a single pod, including events, resource requests and limits, and container state:

kubectl describe pod <pod-name>

To scope to a specific namespace, add the -n flag:

kubectl describe pod <pod-name> -n <namespace>

The Events section at the bottom of the output is often the fastest way to identify why a pod is stuck in Pending or CrashLoopBackOff.

Next steps

  • Last updated on