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.
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.
Terminal
# 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
Frequently asked questions
kubectl top: Usage, Options & Common CI Errors?
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 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.
