kubectl top pods: CPU and Memory Usage
kubectl top pods reports current CPU and memory usage per pod, sourced from the Kubernetes metrics API.
When a job is slow or getting OOMKilled, top shows what the pods are actually consuming right now, provided metrics-server is installed.
What it does
kubectl top pods queries the metrics API (served by metrics-server) and prints current CPU (in millicores) and memory (in Mi) for each pod. --containers breaks it down per container, and --sort-by orders by cpu or memory to surface the heaviest.
Common usage
kubectl top pods
kubectl top pods -l app=api --containers
kubectl top pods --sort-by=memory
kubectl top pods -A --sort-by=cpu | headOptions
| Flag | What it does |
|---|---|
| --containers | Show usage per container, not just per pod |
| --sort-by=cpu|memory | Sort output by resource |
| -l, --selector | Filter pods by label |
| -A, --all-namespaces | Across all namespaces |
| --no-headers | Drop the header row for scripting |
In CI
top reads a metrics pipeline, so it needs metrics-server running and warmed up; right after a fresh deploy, usage may be missing for a minute. For capacity gates, prefer reading requests/limits from the spec with jsonpath, since top is a point-in-time snapshot, not a quota.
Common errors in CI
"error: Metrics API not available" or "the server could not find the requested resource (get pods.metrics.k8s.io)" means metrics-server is not installed or its APIService is unavailable; install it (and on kind/self-signed setups pass --kubelet-insecure-tls to metrics-server). "metrics not available yet" right after scheduling means the collector has not gathered a sample; wait and retry.