Introduction

When kubectl top node says metrics are not available yet, the problem is almost never kubectl itself. The command depends on the cluster’s resource-metrics pipeline, and in modern Kubernetes that means metrics-server, not Heapster, which has long been deprecated.

What kubectl top Actually Uses

kubectl top does not read node statistics directly from the operating system. It queries the Kubernetes Metrics API, which is typically served by metrics-server. metrics-server scrapes resource usage from each kubelet and exposes that data through the aggregated API so tools like kubectl top and autoscalers can read it.

That design explains the error. If metrics-server is missing, failing, blocked from kubelets, or still starting up, kubectl top has no data to display.

Install or Reinstall metrics-server

If the cluster does not already have it, install the current release manifest.

kubectl apply -f   https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Then wait a short time and check whether the deployment is healthy.

kubectl get deployment metrics-server -n kube-system
kubectl get pods -n kube-system -l k8s-app=metrics-server
kubectl top node

A fresh install often needs a minute before metrics start appearing.

Verify the Aggregated API

A working metrics-server also has to register the Metrics API with the apiserver. That is why the APIService object is a useful diagnostic step.

kubectl get apiservice v1beta1.metrics.k8s.io
kubectl describe apiservice v1beta1.metrics.k8s.io
kubectl get --raw /apis/metrics.k8s.io/v1beta1/nodes | head

If the APIService is not available, kubectl top will fail even when the pod is running. Common reasons include TLS issues, aggregation-layer problems, or the service not being reachable from the apiserver.

Check the metrics-server Logs

The next place to look is the container log. Kubelet connection errors are extremely common.

kubectl logs -n kube-system deployment/metrics-server

Typical problems include:

• kubelet certificate validation failures
• nodes reporting addresses that metrics-server cannot reach
• missing aggregation-layer support in the control plane
• network policies blocking access from metrics-server to kubelets

In lab clusters and some local environments, you may need additional arguments such as a preferred kubelet address type. For example:

args:
  - --kubelet-preferred-address-types=InternalIP,Hostname,InternalDNS,ExternalDNS,ExternalIP

If kubelet certificates are self-signed or otherwise incompatible, some environments also use --kubelet-insecure-tls. That can unblock a dev cluster, but it should be treated as a compatibility workaround, not the first production choice.

Heapster vs metrics-server

Older blog posts still mention Heapster. That is stale guidance. Heapster was removed from the standard metrics pipeline years ago. If the question is "should I use Heapster or metrics-server for kubectl top?" the answer is metrics-server.

It is also important to understand what metrics-server is for. It is intended for resource metrics used by autoscaling and quick operational checks. It is not a full monitoring stack like Prometheus.

A Practical Triage Sequence

When this error appears, the fastest path is usually:

1. confirm metrics-server exists in kube-system
2. check pod readiness and logs
3. inspect the v1beta1.metrics.k8s.io APIService
4. verify kubelet reachability and certificate behavior
5. retry kubectl top node after the pipeline stabilizes

That sequence isolates most failures quickly without guessing.

Common Pitfalls

• Assuming Heapster is still the correct fix leads to outdated installation advice.
• Treating metrics-server as a general monitoring solution causes design confusion. It is primarily for Kubernetes resource metrics.
• Ignoring the APIService object can hide aggregation-layer failures.
• Using --kubelet-insecure-tls everywhere without understanding the certificate issue weakens the setup unnecessarily.
• Expecting metrics immediately after install can produce false alarms because the server may still be warming up.

Summary

• 'kubectl top node depends on metrics-server, not Heapster.'
• The error usually means the Metrics API is missing, unhealthy, or still gathering data.
• Check the deployment, pod logs, and v1beta1.metrics.k8s.io APIService first.
• Kubelet address and certificate issues are common root causes.
• Use metrics-server for resource metrics and autoscaling support, not as a full observability stack.