kubectl top: Usage, Options & Common CI Errors

See real CPU and memory usage, not just requests.

kubectl top reports actual resource consumption for nodes and pods, sourced from the metrics API. It answers "is this pod near its limit?" - distinct from kubectl describe, which shows configured requests/limits.

What it does

kubectl top nodes and kubectl top pods query the metrics.k8s.io API (served by metrics-server) and print current CPU (in millicores) and memory (in bytes). --containers breaks a pod down per container; --sort-by orders by cpu or memory; -l filters by label.

Common usage

Terminal

kubectl top nodes
kubectl top pods -A --sort-by=memory
kubectl top pod my-pod --containers
kubectl top pods -l app=web

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 (common on kind/minikube/bare CI clusters) - install it before any step that calls top. On kind/minikube, metrics-server also needs --kubelet-insecure-tls to start. Metrics lag ~15-60s after a pod starts, so calling top immediately in CI returns "unknown" or nothing; wait one scrape interval before asserting on usage.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl describe: Usage, Options & Common CI Errorskubectl describe shows a resource plus its events. Read the Events section to debug ImagePullBackOff, CrashLo… kubectl "the server could not find the requested resource" in CIFix kubectl "Error from server (NotFound): the server could not find the requested resource" in CI - a remove… kubectl get: Usage, Options & Common CI Errorskubectl get lists and displays Kubernetes resources. Output formats, label selectors, watch mode, and the emp…