.jpg)
Subscribe to our newsletter
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
What is kubectl top pod?
The kubectl top pod command allows you to view the CPU and memory consumption of pods in your Kubernetes cluster. It acts as a "live" snapshot to help you identify resource-heavy workloads or verify how your Horizontal Pod Autoscaler (HPA) is making decisions.
Prerequisites:
To use this command, the Metrics Server must be installed and running in your cluster. You can check if it is running by looking for the metrics-server deployment in the kube-system namespace.
Common commands:
- View current namespace pods:
kubectl top pod - View all pods across all namespaces:
kubectl top pod -A - View pods in a specific namespace:
kubectl top pod -n <namespace-name> - View individual container metrics within pods:
kubectl top pod --containers - Sort by specific resource:
kubectl top pod --sort-by=cpuor--sort-by=memory
How to read the output:
This is part of a series of articles about Kubernetes performance
In this article:
- Prerequisites for Using kubectl top pod
- Basic kubectl top pod Syntax
- kubectl top pod Use Cases
- How to Read kubectl top pod Output
- Best Practices for Using kubectl top pod
Prerequisites for Using kubectl top pod
Before using kubectl top pod, the Kubernetes cluster must have the Metrics Server installed and running. The Metrics Server collects CPU and memory usage data from kubelets on each node and exposes it through the Kubernetes Metrics API. Without it, the command returns an error similar to Metrics API not available.
You can verify whether the Metrics Server is installed by running:
kubectl get deployment metrics-server -n kube-system
If it is not installed, deploy it using the official Kubernetes components repository:
kubectl apply -f
https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
The user running the command also needs permission to access pod metrics. In clusters with role-based access control (RBAC) enabled, the account must have access to the metrics.k8s.io API.
To confirm that metrics are available, run:
kubectl top nodes
If node metrics appear successfully, pod metrics are usually available as well.
Basic kubectl top pod Syntax
The basic syntax for the command is:
kubectl top pod [POD_NAME] [flags]
To display resource usage for all pods in the current namespace:
kubectl top pod
Example output:
NAME CPU(cores) MEMORY(bytes)
nginx-6d4cf56db6-xk8rt 2m 15Mi
api-server-7f89c7d9d 25m 120Mi
Flags and options:
To view metrics for pods in a specific namespace:
kubectl top pod -n production
To display usage for a single pod:
kubectl top pod nginx-6d4cf56db6-xk8rt
You can also sort pods by resource consumption using standard shell tools:
kubectl top pod --sort-by=memory
Additional useful flags include:
--containers — Shows metrics for individual containers inside each pod
--all-namespaces — Displays pods across all namespaces
--no-headers — Removes column headers from the output
Example with container-level metrics:
kubectl top pod nginx-6d4cf56db6-xk8rt --containers
kubectl top pod Use Cases
The following table shows how to perform common cluster operations with the kubectl top pod command.
How to Read kubectl top pod Output
The output of kubectl top pod provides a snapshot of current CPU and memory usage for pods. Understanding the meaning of each column helps identify resource-heavy workloads and troubleshoot performance issues.
Example output:
NAME CPU(cores) MEMORY(bytes)
nginx-6d4cf56db6-xk8rt 2m 15Mi
api-server-7f89c7d9d 25m 120Mi
The columns represent:
NAMECPU(cores) — Current CPU usageMEMORY(bytes) — Current memory consumption
CPU values are typically shown in millicores (m):
1000mequals 1 CPU core250m
For example:
2m500mmeans the pod is consuming half a CPU core
Memory values are displayed using binary units:
Ki= kibibytesMi= mebibytesGi= gibibytes
The values shown are current usage metrics collected by the Metrics Server. They are not historical averages and may change between command executions. Because of this, kubectl top pod is best suited for quick operational checks rather than long-term monitoring.
Outputs for containers:
When using the --containers flag, the output includes metrics for each container inside the pod:
kubectl top pod nginx-6d4cf56db6-xk8rt --containers
Example output:
POD NAME CPU(cores) MEMORY(bytes)
nginx-6d4cf56db6-xk8rt nginx 2m 15Mi
Using top pod output to diagnose pod issues:
After identifying unusual resource consumption, compare actual usage against configured requests and limits. This helps determine whether pods are correctly sized or require tuning to improve performance and resource efficiency.
Best Practices for Using kubectl top pod
Here are some useful practices to consider when using this command.
1. Confirm Metrics Server Is Installed and Healthy
Before relying on kubectl top pod, verify that the Metrics Server is installed and functioning correctly in your cluster. You can check its status with kubectl get deployment metrics-server -n kube-system and inspect the logs for errors.
If the Metrics Server is misconfigured or unhealthy, kubectl top pod may return incomplete data or fail entirely. Regularly monitor the health of the Metrics Server to ensure resource metrics reflect the current state of your workloads.
Example:
kubectl --namespace=kube-system get deployment metrics-server
Output:
NAME READY UP-TO-DATE AVAILABLE AGE
metrics-server 1/1 1 1 45d
Verify metrics collection:
kubectl top nodes
Output:
NAME CPU(cores) CPU% MEMORY(bytes) MEMORY%
worker-node-1 420m 21% 3120Mi 39%
worker-node-2 365m 18% 2875Mi 36%
2. Always Check the Right Namespace
Kubernetes clusters often host multiple namespaces, each containing different workloads or environments. When using kubectl top pod, specify the correct namespace with the -n flag if you are not working in the default one.
Failing to specify the namespace can lead to missed issues or incorrect conclusions about resource usage. For example, you might overlook a resource spike in a staging environment if you only check the default namespace.
Example:
kubectl --namespace production top pod
Output:
NAME CPU(cores) MEMORY(bytes)
frontend-76d9c7f7f5-qn9p8 65m 210Mi
backend-5c8b7d9f67-jh2wt 220m 580Mi
redis-0 15m 140Mi
3. Sort by CPU or Memory to Find Noisy Pods Faster
Sorting pods by CPU or memory usage highlights those consuming the most resources. Use --sort-by=cpu or --sort-by=memory to bring the most resource-intensive pods to the top of the output. Reviewing pods based on resource consumption helps address bottlenecks and supports capacity planning.
Example:
kubectl top pods -n production --sort-by=memory
Output:
NAME CPU(cores) MEMORY(bytes)
analytics-worker-7f4b7d5c8d 320m 1850Mi
api-server-6b8f4d5f4d 140m 720Mi
frontend-76d9c7f7f5 60m 220Mi
4. Compare Usage Against Requests and Limits
To interpret resource metrics, compare the actual usage reported by kubectl top pod to the requests and limits defined in pod specifications. If a pod frequently approaches its resource limits, it may experience throttling or eviction. Consistently low usage relative to requests suggests over-provisioning. This comparison helps teams adjust resource allocations and avoid issues such as OOMKills or CPU throttling.
Example:
View current usage:
kubectl -n production top pod api-server-6b8f4d5f4d
Output:
NAME CPU(cores) MEMORY(bytes)
api-server-6b8f4d5f4d 850m 920Mi
Check configured resources:
kubectl -n production describe pod api-server-6b8f4d5f4d
Output (excerpt):
Limits:
cpu: 1
memory: 1Gi
Requests:
cpu: 500m
memory: 512Mi
In this example, the pod is approaching both CPU and memory limits and may require tuning.
5. Use Labels for Workload-Level Checks
Kubernetes labels enable you to filter and group pods by application, environment, or custom key. By combining kubectl top pod with the -l flag, you can monitor resource usage for a specific workload, team, or microservice.
Example:
Retrieve pods with a specific label:
kubectl -n production get pods -l app=web
Output:
NAME READY STATUS
web-6d7f9d8f8b-7xt2m 1/1 Running
web-6d7f9d8f8b-kq4pn 1/1 Running
Check resource usage for those pods:
kubectl top pod -n production | grep web
Output:
web-6d7f9d8f8b-7xt2m 35m 120Mi
web-6d7f9d8f8b-kq4pn 42m 135Mi
This allows operators to quickly evaluate the resource consumption of a specific application or service without reviewing unrelated workloads.
How to Continuously Right-Size Pod Resources with PerfectScale
While kubectl top pod gives you a live snapshot of CPU and memory usage, turning those readings into the right requests and limits across hundreds of workloads is a constant, manual effort. PerfectScale's performance optimization solution enhances Kubernetes performance by autonomously right-sizing workloads, preventing downtime, and optimizing resource use for 99.99% availability - so the usage patterns you spot with kubectl top pod translate directly into safe, data-driven configuration changes.
Key capabilities of PerfectScale:
- Automatic issue remediation: Instantly identifies and fixes resiliency risks, including resource under-provisioning issues such as OOM, CPU throttling, and eviction, to maximize uptime and eliminate latency.
- Autonomous CPU and memory right-sizing: Continuously analyzes your workloads and right-sizes CPU and memory requests and limits based on actual demand, reducing throttling risk while cutting cloud cost — addressing the over- and under-provisioning that
kubectl top podhelps you detect. - Infrastructure hardening: Provides holistic visibility across your nodes to proactively surface misconfigurations, prevent node over-commitment with precise memory limit recommendations, validate node affinities and taints, and select the most suitable node types for your pods.
- Impact-driven prioritization: Resolves critical issues in real time with auto-prioritization, aligns alerting with your SLA/SLOs, sends instant notifications through channels like Slack, MS Teams, or Datadog, and escalates issues into a ticket with one click.
Ready to move from manual snapshots to autonomous optimization? Learn how PerfectScale boosts Kubernetes performance.
