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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes