kubectl top

When to Use kubectl top

kubectl top provides a quick view of CPU and memory consumption for pods and nodes. It is the Kubernetes equivalent of the Linux top command and is the fastest way to identify resource-hungry workloads or nodes approaching capacity limits.

Prerequisites

kubectl top requires the Metrics Server to be running in the cluster:

# Check if Metrics Server is installed
kubectl get deployment metrics-server -n kube-system

# Install Metrics Server if missing
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# Verify metrics are available
kubectl top nodes

If you see an error like "Metrics API not available," the Metrics Server is not installed or not functioning correctly.

Node Metrics

View resource usage across cluster nodes:

# View all node metrics
kubectl top nodes

# Example output:
# NAME       CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
# worker-1   450m         22%    3200Mi           40%
# worker-2   800m         40%    5100Mi           63%
# worker-3   250m         12%    2800Mi           35%

The percentages are relative to the node's total allocatable resources. A node consistently above 80% CPU or memory should trigger scaling actions.

Pod Metrics

View resource consumption for pods:

# All pods in current namespace
kubectl top pods

# All pods across all namespaces
kubectl top pods -A

# Sort by CPU usage to find hot spots
kubectl top pods --sort-by=cpu

# Sort by memory to find memory-hungry pods
kubectl top pods --sort-by=memory -A

# Filter by label
kubectl top pods -l app=nginx

# Example output:
# NAME                     CPU(cores)   MEMORY(bytes)
# my-app-7d6f8b4c5-x2k9m   150m         256Mi
# my-app-7d6f8b4c5-a1b2c   120m         230Mi

Container-Level Metrics

For multi-container pods, view per-container breakdown:

# Show per-container metrics
kubectl top pods --containers

# Example output:
# POD                      NAME          CPU(cores)   MEMORY(bytes)
# my-app-7d6f8b4c5-x2k9m   app           120m         200Mi
# my-app-7d6f8b4c5-x2k9m   istio-proxy    30m          56Mi

# Filter for specific pods with container breakdown
kubectl top pods --containers -l app=nginx

This helps identify whether the main container or a sidecar is consuming unexpected resources.

Identifying Resource Issues

Use top metrics to diagnose common problems:

# Find pods close to their memory limits
kubectl top pods -A --sort-by=memory

# Compare with configured limits
kubectl get pods -o custom-columns=\
NAME:.metadata.name,\
MEM_REQUEST:.spec.containers[0].resources.requests.memory,\
MEM_LIMIT:.spec.containers[0].resources.limits.memory

# Find nodes under pressure
kubectl top nodes
kubectl describe node <node-name> | grep -A 5 "Conditions"

Scripting with top

Combine top with other tools for automated analysis:

# Find pods using more than 500Mi memory
kubectl top pods --no-headers | awk '$3 > 500 {print $1, $3}'

# Alert on high CPU nodes
kubectl top nodes --no-headers | awk -F'[[:space:]]+' '$3 > 80 {print "HIGH CPU:", $1, $3}'

# Export metrics for reporting
kubectl top pods -A --no-headers --sort-by=memory > pod-metrics.txt

Comparison with Resource Requests and Limits

Understanding the relationship between actual usage (shown by top) and configured requests/limits is key to right-sizing workloads:

# Get actual usage
kubectl top pods

# Get configured requests and limits
kubectl get pods -o custom-columns=\
"NAME:.metadata.name,\
CPU_REQ:.spec.containers[0].resources.requests.cpu,\
CPU_LIM:.spec.containers[0].resources.limits.cpu,\
MEM_REQ:.spec.containers[0].resources.requests.memory,\
MEM_LIM:.spec.containers[0].resources.limits.memory"

If actual usage is consistently far below requests, you are over-provisioning and wasting cluster resources. If usage frequently approaches limits, the workload needs more resources or the limits need adjusting.

Limitations

kubectl top shows point-in-time metrics with a delay (typically 15-30 seconds). It does not show historical data, trends, or percentile distributions. For production monitoring, use Prometheus with Grafana or your cloud provider's monitoring solution. kubectl top is best for quick spot checks and interactive debugging.