kubectl-top

Get the resource consumption of all nodes

$ kubectl top [[no|nodes]]

$ kubectl top [[no|nodes]] [node_name]

$ kubectl top [[po|pods]]

$ kubectl top [[po|pods]] [pod_name]

$ kubectl top [[po|pods]] [[-n|--namespace]] [namespace_name]

$ kubectl top [[po|pods]] --containers

$ kubectl top [[po|pods]] [[-l|--selector]] [key=value]

kubectl top { nodes | pods } [NAME | -l label_selector] [options]

kubectl top nodes [NAME] [options]
kubectl top pods [NAME | -l label_selector] [-n namespace | --all-namespaces] [options]

--all-namespaces / -A
    If present, list the requested object(s) across all namespaces.

--containers
    If present, show all containers in a pod (only applicable for top pods).

--no-headers
    If present, do not print the column headers.

--selector / -l
    Selector (label query) to filter nodes or pods. For example: -l "app=myapp".

--sort-by
    Sort column for custom sorting. Can be "cpu" or "memory". For example: --sort-by=memory.

--namespace / -n
    If present, the namespace scope for the request. Only applicable for top pods when not using --all-namespaces.

NAME
    Specific name of the node or pod to view usage for.

The kubectl top command provides a quick and convenient way to observe real-time resource consumption (CPU and memory) of Kubernetes nodes and pods. It acts as an interface to the

Kubernetes Metrics Server, which collects resource metrics from Kubelets and exposes them via the Metrics API. This command is invaluable for monitoring cluster health, identifying resource bottlenecks, and debugging performance issues within your cluster.

When used with nodes, it displays the total CPU and memory usage of each cluster node. When used with pods, it shows the resource usage for individual pods, and with the --containers option, it can even break down usage per container within a pod.

It's important to note that kubectl top does not show resource requests or limits defined for pods or containers; it only reports actual usage. Its simplicity and immediate feedback make it a go-to tool for initial performance investigations.

The primary limitation of kubectl top is its dependency on the Kubernetes Metrics Server. If the Metrics Server is not deployed or is not functioning correctly in your cluster, kubectl top will fail with an error stating that metrics are not available.

The data provided by kubectl top represents current or near-current usage, which might be slightly aggregated or delayed, typically within a minute. It does not provide historical data or trend analysis. Furthermore, it only shows actual usage and does not display configured resource requests, limits, or quotas for pods and containers, which are crucial for understanding resource allocation and potential throttling.

kubectl top will not work if the Kubernetes Metrics Server is not running in your cluster. You can usually deploy it using official manifests or a Helm chart. Verify its presence with kubectl get --raw "/apis/metrics.k8s.io/v1beta1".

CPU usage is typically reported in millicores (m), where 1000m equals one CPU core. Memory usage is reported in mebibytes (Mi) or gibibytes (Gi). These units are crucial for interpreting the reported values correctly.

The kubectl top command was introduced as a convenient way to integrate resource monitoring directly into the Kubernetes command-line interface. Its functionality is entirely reliant on the Kubernetes Metrics Server, which emerged as a standard, lightweight solution for collecting core resource metrics (CPU and memory usage) in Kubernetes clusters.

Prior to the widespread adoption of the Metrics Server, users often relied on more complex monitoring solutions or custom scripts to gather similar data. kubectl top filled a crucial gap by providing an on-demand, simple view of resource consumption, making initial diagnostics and daily operational tasks significantly easier for cluster administrators and developers. Its design reflects the Kubernetes philosophy of providing simple, focused tools for common tasks.

kubectl describe(1), kubectl get(1), kubectl logs(1), docker stats(1)