kubectl top internals — the interactive metrics query

kubectl top is the interactive metrics query. It returns the CPU and memory usage per node or pod. This lesson walks the command, the internal flow, the columns, the sort options, and the production patterns.

The kubectl top command

kubectl top nodes
kubectl top pods
kubectl top pods -A
kubectl top pods -n default
kubectl top pods --containers
kubectl top pods -A --sort-by=memory

The command queries the metrics.k8s.io API.

The internal flow

sequenceDiagram
    participant U as User
    participant K as kubectl
    participant API as API server
    participant M as Metrics Server
    U->>K: kubectl top nodes
    K->>API: GET /apis/metrics.k8s.io/v1beta1/nodes
    API->>M: forward request
    M->>M: collect from kubelets
    M-->>API: metrics
    API-->>K: metrics
    K-->>U: formatted output

The flow is the metrics path.

The node output

The node output:

kubectl top nodes

NAME       CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
cp-1       500m         12%    2048Mi          26%
cp-2       450m         11%    1900Mi          25%
worker-1   800m         40%    4096Mi          52%
worker-2   600m         30%    3500Mi          45%

The columns:

• NAME: the node name.
• CPU(cores): the CPU usage in cores (e.g., 500m = 0.5).
• CPU%: the CPU usage as a percentage of the allocatable.
• MEMORY(bytes): the memory usage in bytes.
• MEMORY%: the memory usage as a percentage of the allocatable.

The pod output

The pod output:

kubectl top pods -A

NAMESPACE     NAME                              CPU(cores)   MEMORY(bytes)
default       nginx-1-abc                       100m         128Mi
default       nginx-2-def                       120m         130Mi
kube-system   kube-apiserver-cp-1               500m         2048Mi
kube-system   kube-proxy-xyz                    50m          64Mi

The columns:

• NAMESPACE: the pod’s namespace.
• NAME: the pod’s name.
• CPU(cores): the CPU usage summed across containers.
• MEMORY(bytes): the memory usage summed across containers.

The container output

The container output:

kubectl top pods --containers

POD          NAME      CPU(cores)   MEMORY(bytes)
nginx-1-abc  nginx     100m         128Mi
nginx-2-def  nginx     120m         130Mi

The columns:

• POD: the pod’s name.
• NAME: the container’s name.
• CPU(cores): the container’s CPU usage.
• MEMORY(bytes): the container’s memory usage.

The sort options

The sort options:

kubectl top nodes --sort-by=cpu
kubectl top nodes --sort-by=memory
kubectl top pods -A --sort-by=cpu
kubectl top pods -A --sort-by=memory

The sort options order the output by the specified column.

The labels

The labels:

kubectl top pods -A --selector=app=nginx
kubectl top pods -A -l app=nginx

The labels filter the output by the pod’s labels.

The no-headers output

The no-headers output:

kubectl top nodes --no-headers

The no-headers output is useful for scripts.

The JSON output

The JSON output:

kubectl top pods -o json

The JSON output is the API response.

The failure modes

The common failure modes:

Metrics Server not running

error: Metrics API not available

The Metrics Server is not running. Check the pod status.

Metrics Server TLS

error: the server is currently unable to handle the request

The Metrics Server has a TLS issue. Check the logs.

Pod not in Metrics Server

W0701 12:00:00.000000   12345 top_pod.go:136] Metrics not available for pod default/nginx-1-abc

The Metrics Server has not collected the metrics for the pod yet. Wait for the next collection interval.

Cross-course references

• The HPA course (Part LXXXII) covers the integration.
• The Prometheus course (Part LXXXVIII) covers the continuous monitoring.
• The bash scripting course covers the parsing.

Quiz

Production discipline

• Use kubectl top for interactive inspection. The quick query.
• Use —sort-by for ranking. The most loaded pods.
• Use —containers for per-container metrics. The deep inspection.
• Use —selector for label filtering. The targeted query.
• Use —no-headers for scripts. The automation.
• Document the investigation. The query, the findings.

The kubectl top is the interactive metrics query. Operating it well is using the command, the sort options, and the label filters, and documenting the findings.