The fastest way to view pod metrics is kubectl top pod, which prints current CPU and memory usage for each pod. It works only if the Metrics Server (or another provider of the resource metrics API) is running in your cluster. This guide covers the commands, the errors you will hit, how to read the numbers, and where a spot-check stops being enough.
TL;DR
kubectl top pod -n <namespace>shows current CPU and memory per pod. Add--containersto split usage by container and--sort-by=memoryto put the heaviest pods first.- "error: Metrics API not available" means no Metrics Server is serving the metrics API. Install it or use a cluster distribution that ships it.
- The numbers are a recent snapshot for autoscaling and spot-checks, not history. For trends and alerts, use a real monitoring stack.
- High usage is not the same as an unhealthy pod. Check requests, limits, restarts and events before you act.
- If you look at several clusters every day, a desktop client that shows metrics beside logs and a pod terminal saves a lot of context switching.
Table of Contents
- The quick answer: kubectl top pod
- Why it fails: "Metrics API not available"
- Reading the numbers without fooling yourself
- High usage is not the same as unhealthy
- What kubectl top does not do
- Choosing how to look at pod metrics
- Our perspective: metrics belong next to the pod
- Viewing pod metrics in Kubezilla Desktop
- A practical checklist for a metrics spot-check
- FAQ
- Sources
The quick answer: kubectl top pod
The official kubectl top pod reference describes the command as a way to see the resource consumption of pods. The everyday forms look like this:
# Pods in the current namespace
kubectl top pod
# Pods in a specific namespace
kubectl top pod -n payments
# Every namespace
kubectl top pod -A
# One pod, broken down by container
kubectl top pod api-7d9f8c6b5-x2kqp --containers
# Heaviest memory consumers first
kubectl top pod -n payments --sort-by=memory
The same reference lists --sort-by (accepting cpu or memory), --containers and --sum, which prints the total usage of the pods returned. Pass a label selector with -l app=api to narrow the list to one workload.
Typical output:
NAME CPU(cores) MEMORY(bytes)
api-7d9f8c6b5-x2kqp 212m 389Mi
api-7d9f8c6b5-9tzvb 198m 402Mi
worker-5c7b9d-lm4hd 14m 96Mi
That is the whole feature. Everything else in this article is about reading it correctly and knowing what it leaves out.
Why it fails: "Metrics API not available"
If you see "error: Metrics API not available", the cluster has no component answering the resource metrics API. The kubectl top command does not talk to pods directly. According to the Kubernetes documentation on the resource metrics pipeline, it queries the Metrics API, which the Metrics Server fills by collecting data from the kubelet on each node.
Check whether the Metrics Server is running
The Kubernetes task page on assigning memory resources suggests this check:
kubectl get apiservices
If the resource metrics API is available, the output includes a reference to metrics.k8s.io. You can also look for the deployment directly:
kubectl get deployment metrics-server -n kube-system
Install it if it is missing
The Metrics Server project on GitHub says it can be installed from a YAML manifest or with the official Helm chart. The manifest route is a single command:
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
The same page lists requirements that are not the default on every distribution: the API server needs the aggregation layer enabled, nodes need Webhook authentication and authorization, and the container runtime must expose container metrics. Local clusters and some hardened setups often need extra configuration, so read those requirements before you assume the manifest alone will work. Managed Kubernetes services frequently bundle a metrics component already, which is why this error shows up most on self-built and local clusters.
"It worked a minute ago" and new pods
The reference notes that, because of the metrics pipeline delay, metrics may be unavailable for a few minutes after a pod is created. If kubectl top pod returns nothing for a brand-new pod, wait before you start debugging.
Reading the numbers without fooling yourself
Most wrong conclusions from kubectl top come from misreading units or from treating a snapshot as a trend.
What "500m CPU" means
The CPU column is reported in cores, and the m suffix means millicores. Per the Kubernetes docs, 500m is 0.5 of a CPU core. One CPU unit is one vCPU on a cloud provider or one hyper-thread on bare-metal Intel processors. The quantity is absolute: 100m is the same amount of compute on a 4-core node and a 64-core node. The finest value the scheduler supports is 1m.
So a pod showing 212m is using about a fifth of one core, averaged over the measurement window.
Memory units
Memory appears in bytes with binary suffixes: Mi is mebibytes, Gi is gibibytes. A pod at 389Mi is using roughly 408 million bytes. When you compare it with a limit written as 512Mi, keep the suffixes identical or you will misjudge headroom.
Why it differs from top inside the container
The pipeline is tuned for stable autoscaling signals rather than millisecond precision, so its values can differ from what you see running top or free inside a container. CPU is derived from cumulative kernel counters over a window, so small swings are normal. For bursty workloads, run kubectl top pod <name> --containers to find which container is driving the usage. A sidecar is often the surprise.
Usage versus requests and limits
A number on its own says little. Compare it with the pod's requests and limits:
kubectl get pod api-7d9f8c6b5-x2kqp -o jsonpath='{.spec.containers[*].resources}'
| What you see | What it may mean | What to check next |
|---|---|---|
| Memory close to the limit, pod stable | Caching or a runtime that fills available memory by design | Restart count, last state |
| Memory close to the limit, restarts climbing | Container is being killed for exceeding memory | kubectl describe pod, look for OOMKilled |
| CPU far below the request | Over-provisioned request, wasted schedulable capacity | A week of history before you shrink it |
| CPU pinned at the limit | Throttling is likely | Latency graphs, container-level split |
| No data at all | Metrics Server missing or pod too new | kubectl get apiservices, pod age |
High usage is not the same as unhealthy
Kubernetes guidance and practitioners agree on this: a container using memory near its limit is not automatically in trouble. Some applications cache aggressively. What matters is whether the pod is restarting, being killed, or failing probes.
For that, kubectl top is the wrong tool. Use:
kubectl describe pod <pod-name>
The events section shows scheduling problems, OOM kills and probe failures. The Kubernetes page on liveness, readiness and startup probes explains the three probe types: readiness decides whether a pod can receive traffic, liveness decides whether a container needs a restart, and startup gives slow-booting applications a grace period. Failed probes produce event messages such as "Unhealthy" that you can read in the pod description.
The probe configuration walkthrough shows the restart counter increasing after a failed container recovers, which is exactly the kind of signal a CPU and memory table will never give you. One practical tip: avoid giving liveness and readiness probes identical logic. A liveness check should answer "is the process alive or deadlocked?", while readiness can include dependencies such as a database. If both fail when the database is down, Kubernetes restarts pods that a restart cannot fix.
A reasonable health routine for one suspect pod:
kubectl get pod <name>: status, ready count, restarts.kubectl top pod <name> --containers: current usage per container.kubectl describe pod <name>: events, last state, probe results.kubectl logs <name> --previous: what the last crashed container said.
What kubectl top does not do
The Kubernetes documentation is explicit that the Metrics API offers a basic set of metrics to support autoscaling and similar use cases. Its main consumers are the Horizontal Pod Autoscaler and the Vertical Pod Autoscaler. That shapes what you can expect:
- No history. You see recent consumption only. You cannot ask what memory looked like at 3 a.m. last Tuesday.
- No alerting. Nothing tells you when a pod crosses a threshold.
- Only CPU and memory. No network, disk I/O or request latency.
- A delay. Values lag, especially for new pods.
For trends, capacity planning and alerts, the community's answer is a dedicated observability stack, commonly Prometheus with Grafana, or an OpenTelemetry-based pipeline. If you go that route, the OpenTelemetry semantic conventions for Kubernetes metrics describe how pod-level metrics are named and which attributes they carry, which helps keep dashboards consistent across tools.
Think of the split like this: monitoring stacks answer "what happened and should we be paged?" while kubectl top answers "what is this pod doing right now?" You need both, and they rarely replace each other.
Choosing how to look at pod metrics
There are four common ways to view pod metrics. None is best everywhere.
| Approach | Strength | Limit |
|---|---|---|
kubectl top in a terminal | Zero setup beyond Metrics Server, scriptable | Snapshot only, one cluster context at a time, plain text |
| Metrics and dashboards in a monitoring stack | History, alerts, many metric types | Setup and upkeep, a browser tab per environment |
| A cluster-hosted web dashboard | Visual, shareable inside a team | Needs deploying and exposing safely |
| A native desktop Kubernetes client | Live view next to logs, terminals and YAML, many clusters in one window | A client to install and license |
The people who feel the friction most are those who touch several clusters in a day: switching contexts, re-running top, opening logs in another pane, then a shell in a third. That is the problem a desktop client targets.
Our perspective: metrics belong next to the pod
We build Kubezilla Desktop, so we watch how engineers actually debug. A metric is rarely the end of the question. You look at a pod's memory, see it climbing, and your next move is the logs, then a shell, then the YAML to check the limit. Each of those used to mean a different tool, a different terminal tab or a browser window with its own login.
Our view is that the number should live in the same place as everything you will do about it. That is why Kubezilla Desktop puts real-time metrics, live log streaming, pod terminals and YAML editing in one native interface, and why it connects to multiple clusters, including over SSH tunnels, without asking you to wire up VPNs or bastion-host workarounds first.
We also hold a firm line on where your credentials live. Kubeconfigs are stored securely on your own machine, and there is no cloud sync and no telemetry. A tool that looks at production clusters should not need to phone home. It is built in Rust, which keeps RAM use low and startup fast, so opening it to check one pod does not feel like launching an IDE.
We are also candid about the limit. A desktop client is a window onto the live state of your clusters. It does not replace the history and alerting of a monitoring stack, and it relies on the cluster's metrics pipeline as kubectl top does. Use both: alerts to tell you something is wrong, a fast client to find out why.
— Margus
Viewing pod metrics in Kubezilla Desktop
If kubectl top is your current routine, Kubezilla Desktop is meant to cut the repetition out of it. You add your clusters once, with kubeconfigs kept locally, and move between them in one window. From there you can check resource usage for the workloads you care about, stream logs live, open a terminal in the pod and edit YAML without leaving the app. Helm and ArgoCD operations and PVC file browsing sit in the same interface, as do workload scaling controls.
Kubezilla Desktop runs on Linux, macOS and Windows and costs €5 per month. You can see the details on the Kubezilla Desktop pricing page, or read the overview of the Kubernetes desktop app first.
If you want to go deeper on adjacent tasks, these guides pair well with metrics work:
- Kubernetes pod shell: five commands and faster access for when the metrics send you into the container.
- Scaling a Kubernetes deployment for when the numbers say you need more replicas.
- Restarting a Kubernetes deployment safely for when a leaking pod needs a verified rollout.
- Managing multiple clusters if the same checks run across many environments.
A practical checklist for a metrics spot-check
When someone says a service feels slow, this sequence keeps you honest:
- Confirm the metrics API answers:
kubectl get apiservices. If it does not, fix that first. - List usage for the namespace sorted by the suspect resource:
kubectl top pod -n <ns> --sort-by=cpu. - Split by container for the outlier:
--containers. - Read requests and limits for the same pod and compare with the usage, in matching units.
- Run
kubectl describe podand look for restarts, OOM kills and "Unhealthy" events. - Check whether the pod is new. If it is a few minutes old, the numbers may not exist yet.
- If the pattern needs history to judge, go to your monitoring dashboards rather than guessing from one sample.
Two habits save the most time. First, always note the time of your sample, since the value is only meaningful for that window. Second, compare replicas of the same deployment: if one pod of five is far above its siblings, you have a pod-specific problem such as a hot key, a stuck job or a leaking connection, not a capacity problem.
FAQ
How can I check the memory usage of a pod using kubectl?
Run kubectl top pod <pod-name> -n <namespace> and read the MEMORY(bytes) column. Add --containers to see each container separately. This needs the Metrics Server, and a new pod may show nothing for a few minutes.
What does "500m CPU" mean in Kubernetes?
It means 500 millicores, or half of one CPU core. One CPU unit equals one vCPU on cloud providers or one hyper-thread on bare-metal Intel hosts. The value is absolute, so 500m is the same compute on any node size.
How do I check pod health, not just resource usage?
Use kubectl describe pod <pod-name> and read the events for restarts, OOM kills and failed probes. Readiness probes control traffic, liveness probes control restarts, and startup probes protect slow initialization. A pod can show high memory in kubectl top and still be perfectly healthy.
Is kubectl top enough for monitoring?
Not for long-term monitoring. It reports recent usage to support autoscaling and quick checks, with no history or alerting. Pair it with a monitoring stack such as Prometheus and Grafana for trends and alerts.
Why does kubectl top show different numbers than top inside the container?
The metrics pipeline aggregates kubelet data and is tuned for stable autoscaling signals, not instant precision. CPU is computed as a rate over a window, so it will not match an instantaneous reading. Expect small differences rather than exact agreement.
Sources
- kubectl top pod reference, Kubernetes
- Resource metrics pipeline, Kubernetes
- Assign memory resources to containers and pods, Kubernetes
- Metrics Server, kubernetes-sigs on GitHub
- Liveness, readiness and startup probes, Kubernetes
- Configure liveness, readiness and startup probes, Kubernetes
- Semantic conventions for Kubernetes metrics, OpenTelemetry