kubectl top shows no metrics: metrics-server troubleshooting

TL;DR

kubectl top depends entirely on metrics-server, and when it shows nothing the problem is almost always metrics-server itself: not installed, crashing, or unable to reach kubelets. Work through it in order: is metrics-server running, can it scrape kubelets (TLS is the usual suspect), and is the metrics API actually serving. Nine times out of ten it is one of those three.

The query

kubectl top shows no metrics: metrics-server troubleshooting

Use this when

• kubectl top returns errors or empty tables
• HPA is not scaling and you suspect metrics
• A new or upgraded cluster has no resource metrics
• Dashboards that read the metrics API are blank

Not for when

• Setting up Prometheus or full monitoring stacks
• Application-level custom metrics
• Node resource pressure itself (use the metrics once they work)

Steps

Step 1: Check if metrics-server is running

Look for the metrics-server deployment in kube-system and check its pod status and logs. On managed clusters it should exist by default; on kubeadm or k3s clusters it may be missing or disabled. Expected output: a running metrics-server pod, or a clear "not installed" answer that sends you to install it.

Step 2: Read the metrics-server logs for scrape errors

The logs name the failure directly: connection refused to kubelets, TLS verification failures, or timeouts. TLS issues with kubelet certificates are the most common cause on clusters with custom CA setups. Expected output: a specific error naming which kubelet or what TLS problem is blocking scrapes.

Step 3: Verify kubelet connectivity from the metrics-server pod

The server needs to reach each kubelet's HTTPS endpoint. Network policies, firewalls, or wrong address types (hostname vs internal IP) break this. Check that the addresses metrics-server uses match addresses that actually route. Expected output: metrics-server can open HTTPS connections to kubelets on all nodes.

Step 4: Check the metrics API registration

Query the API aggregation layer to confirm the metrics.k8s.io API service is available and not reporting failures. A broken apiservice registration makes kubectl top fail even with a healthy metrics-server. Expected output: the metrics.k8s.io APIService shows Available=True.

Step 5: Confirm with kubectl top after a short wait

Metrics-server scrapes on an interval (default 60 seconds), so fresh installs need a minute or two before data appears. Run kubectl top nodes and kubectl top pods; both should return values. Expected output: CPU and memory columns populated for nodes and pods.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8CbOK1bfQxjI64s6tBy0Lg

Resolved from the public thread: https://vectle.com/posts/pst_8CbOK1bfQxjI64s6tBy0Lg

Thread query: kubectl top shows no metrics: metrics-server troubleshooting

TL;DR: kubectl top depends entirely on metrics-server, and when it shows nothing the problem is almost always metrics-server itself: not installed, crashing, or unable to reach kubelets. Work through it in order: is metrics-server running, can it scrape kubelets (TLS is the usual suspect), and is the metrics API actually serving. Nine times out of ten it is one of those three.