# kubectl top: Usage, Options & Common CI Errors

> kubectl top shows live CPU and memory usage for pods and nodes. Sorting, container breakdown, and the metrics-server-not-installed error in CI clusters.

Source: https://latchkey.dev/learn/command-reference/kubectl-top  
Updated: 2026-06-25

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.

## 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt