# kubectl top: Command Reference for CI/CD

> Reference for kubectl top: show live CPU and memory for nodes and pods, sorting and per-container breakdown, and the metrics-server requirement in CI.

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

See real CPU and memory usage, not just configured requests.

kubectl top reports actual resource consumption from the metrics API, answering "is this pod near its limit?". This reference covers the flags and the metrics-server dependency that makes top fail on bare CI clusters.

## Common flags and usage

- top nodes: per-node CPU (millicores) and memory (bytes)
- top pods: per-pod usage in the current namespace
- top pods -A: across all namespaces
- --containers: break a pod down per container
- --sort-by=cpu|memory: order the output

## Example

```shell
kubectl top nodes
kubectl top pods -n prod --sort-by=memory
kubectl top pod -l app=web --containers
```

## In CI

top needs metrics-server, which is not installed on kind/minikube/bare clusters by default ("Metrics API not available"). Install it first, and on kind/minikube add --kubelet-insecure-tls. Metrics lag ~15-60s after a pod starts, so 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: Command Reference for CI/CD?

kubectl top reports actual resource consumption from the metrics API, answering "is this pod near its limit?". This reference covers the flags and the metrics-server dependency that makes top fail on bare CI clusters.

### In CI?

top needs metrics-server, which is not installed on kind/minikube/bare clusters by default ("Metrics API not available"). Install it first, and on kind/minikube add --kubelet-insecure-tls. Metrics lag ~15-60s after a pod starts, so wait one scrape interval before asserting on usage.

---

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