Kubernetes API - Get Pods on Specific Nodes

Introduction
Before you drain a node, debug a node that is slow, or check how the scheduler spread your replicas, you need to know which pods run where. Every pod records its node in spec.nodeName, and the Kubernetes API can filter on that field on the server. In this guide, you'll learn how to get the pods on one node with kubectl and with the API directly, and how to list every pod in the cluster together with its node.
TL;DR
- Pods on one node, all namespaces:
kubectl get pods -A --field-selector spec.nodeName=worker-node-1 - Every pod with its node:
kubectl get pods -A -o wide - The same filter in the API:
GET /api/v1/pods?fieldSelector=spec.nodeName%3Dworker-node-1
Prerequisites
Before proceeding, make sure:
- You have
kubectlinstalled and configured. - Your user can list pods in all namespaces. With access to one namespace only, replace
-Awith-n <namespace>. jqis installed for the examples that process JSON.
Using the Kubernetes API
List Pods with Node Information
To list Pods along with their node information, use:
kubectl get pods -o wide
The -o wide output adds the IP, NODE, NOMINATED NODE and READINESS GATES columns. Like every kubectl get for namespaced objects, it shows only the namespace of your current context unless you add -A.
Filter Pods by Node
To get the Pods running on a specific node, use a field selector:
kubectl get pods -A --field-selector spec.nodeName=<node-name>
Replace <node-name> with the name from kubectl get nodes. The API server does the filtering, so this is fast even in a large cluster.
Do not leave out -A. Without it, the command lists only the pods of your current namespace on that node, and system pods such as the CNI agent or kube-proxy are missing from the result.
Example
To retrieve all Pods running on a node named worker-node-1, and only the ones that are running, combine two field selectors:
kubectl get pods -A -o wide --field-selector spec.nodeName=worker-node-1,status.phase=Running
Field selectors for pods support only some fields, for example spec.nodeName, status.phase, metadata.name, metadata.namespace, spec.serviceAccountName and status.podIP. For other pod fields, use -o json and jq. Pod objects do not contain the labels of their node: to select pods by a node label, get the node names first with kubectl get nodes -l <label>=<value> -o name, and query each node.
kubectl describe node worker-node-1 lists the pods on the node that have not finished under Non-terminated Pods, with the CPU and memory requests and limits of each one, and the totals under Allocated resources.
Using the Kubernetes API Directly
kubectl get --raw sends a request to the API server with your kubeconfig credentials. Encode the = in the field selector as %3D and put the URL in quotes:
kubectl get --raw "/api/v1/pods?fieldSelector=spec.nodeName%3Dworker-node-1" \
| jq -r '.items[] | "\(.metadata.namespace)/\(.metadata.name)"'
To call the API from a script without kubectl, use a ServiceAccount token and verify the server certificate. Do not use curl -k, which accepts any certificate:
APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
kubectl config view --raw --minify --flatten \
-o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt
TOKEN=$(kubectl create token pod-reader -n monitoring) # a ServiceAccount that may list pods
curl --cacert ca.crt -H "Authorization: Bearer $TOKEN" \
"$APISERVER/api/v1/pods?fieldSelector=spec.nodeName%3Dworker-node-1"
Inside a pod, the token and CA are already mounted under /var/run/secrets/kubernetes.io/serviceaccount/, and the API server is https://kubernetes.default.svc. The ServiceAccount needs a ClusterRole with list on pods to read every namespace.
The client libraries accept the same selector. With the official Python client:
from kubernetes import client, config
config.load_kube_config() # use config.load_incluster_config() inside a pod
pods = client.CoreV1Api().list_pod_for_all_namespaces(
field_selector="spec.nodeName=worker-node-1"
)
for pod in pods.items:
print(pod.metadata.namespace, pod.metadata.name, pod.status.phase)
How Do I List All Pods and Their Nodes?
For a quick look, -o wide across all namespaces is enough:
kubectl get pods -A -o wide
For a short table that is easy to read or to use in a script, choose the columns yourself and sort by node:
kubectl get pods -A --sort-by=.spec.nodeName \
-o custom-columns='NODE:.spec.nodeName,NAMESPACE:.metadata.namespace,POD:.metadata.name,STATUS:.status.phase'
NODE NAMESPACE POD STATUS
<none> shop web-7d4b9c-9dw7c Pending
worker-node-1 kube-system coredns-6f6b679f8f-8mv2x Running
worker-node-1 shop web-7d4b9c-x2kqz Running
worker-node-2 kube-system kube-proxy-q8zfn Running
worker-node-2 shop web-7d4b9c-p4lsm Running
A pod with <none> as its node is not scheduled yet. kubectl describe pod shows the reason in its events, for example not enough CPU or a taint that the pod does not tolerate.
How Many Pods Run on Each Node?
Count the running pods by node:
kubectl get pods -A --field-selector status.phase=Running \
-o jsonpath='{range .items[*]}{.spec.nodeName}{"\n"}{end}' | sort | uniq -c
14 worker-node-1
31 worker-node-2
A large difference between nodes is normal after a node joins or comes back: the scheduler places each pod once and does not move it later. Topology spread constraints spread new pods, and the descheduler evicts pods so that the scheduler places them again. To see the pod limit of each node, run kubectl get nodes -o custom-columns='NODE:.metadata.name,MAX_PODS:.status.allocatable.pods'.
Best Practices
- Add
-Ato node queries. A node runs pods from many namespaces. - Filter on the server.
--field-selectorand-lsend less data thangrepon the full list, which matters in a large cluster and in scripts that run often. - Use labels for groups of nodes. Managed node pools add a pool label to their nodes. Select a pool with
kubectl get nodes -l <label>=<value>, and show the zone of each node withkubectl get nodes -L topology.kubernetes.io/zone. - Give scripts their own ServiceAccount with read-only access, not your admin kubeconfig.
Conclusion
spec.nodeName connects every pod to its node. kubectl get pods -A --field-selector spec.nodeName=<node> gives you the pods on one node, -o wide or custom columns give you the whole map, and the same field selector works in a raw API call or a client library.
Related Resources
- The 5-Minute Kubernetes Cluster Health Check: nodes, resource use and problem pods in five commands
- How to list all containers in a pod
- Introduction to Kubernetes: Scheduling: node selectors, affinity, taints and draining
- Kubernetes Scheduler Challenge: place pods on nodes yourself and see which rules block them
- Kubernetes Flashcards
Try it hands-on
Run the commands from this article in the browser. Nothing to install.
Kubernetes Terminal Simulator
Practice Kubernetes commands in an interactive browser terminal. Learn kubectl contexts, nodes, Pods, Deployments, Services, rollouts, logs, exec, events, ConfigMaps, and cleanup workflows with a live cluster visualization.
Kubernetes Networking / CNI Simulator
Visualize Kubernetes networking and CNI packet paths with an interactive simulator. Learn Pod-to-Pod routing, same-node and cross-node traffic, ClusterIP Services, EndpointSlices, headless Services, LoadBalancer, NodePort, kube-proxy, eBPF service routing, Ingress, NetworkPolicy, and internet egress.
We earn commissions when you shop through the links below.
Bitrise
Managed runners for GitHub Actions
Bitrise Build Hub runs your GitHub Actions jobs on M4 Macs and AMD Linux machines. Change runs-on and keep your workflows, secrets and logs on GitHub.
Atomsized
AWS platform engineering and GitOps
Design and automation for reliable AWS and Kubernetes platforms, safer delivery workflows, and preview and UAT environments your engineers can understand and own.
DigitalOcean
Cloud infrastructure for developers
Simple, reliable cloud computing designed for developers
DevDojo
Developer community & tools
Join a community of developers sharing knowledge and tools
SMTPfast
Developer-first email API
Send transactional and marketing email through a clean REST API. Detailed logs, webhooks, and embeddable signup forms in one dashboard.
QuizAPI
Developer-first quiz platform
Build, generate, and embed quizzes with a powerful REST API. AI-powered question generation and live multiplayer.
Want to support DevOps Daily and reach thousands of developers?
Become a SponsorTags
Found an issue?
Related Posts
Also worth your time on this topic
How to Restart, List and Keep Containers Running in a Kubernetes Pod
Kubernetes has no command to restart one container. Learn the ways that work, how to restart pods after a ConfigMap or Secret change, how to list containers, run several commands, keep a container running, and use local images.
Kubernetes Kubelet
What is the role of the kubelet in a Kubernetes cluster? How does it interact with the control plane?
mid
Helm Charts and Kubernetes Package Management
Learn Kubernetes application deployment and management using Helm charts with templates, values, and lifecycle management.
90 minutes