metrics not available yet: kubectl top cannot read the metrics API

kubectl top depends on a metrics server that is not part of Kubernetes and is not installed by default. Without it, there is no source of live CPU and memory figures.

Applies to: All Kubernetes versions

What it means

kubectl top reads from the resource metrics API, which is served by a metrics server component that most distributions do not install automatically. When it is missing, unhealthy, or unable to reach the kubelets, kubectl top fails and so does any HorizontalPodAutoscaler using CPU or memory. A briefer version of the same message appears legitimately right after a pod starts or after the metrics server restarts, since it collects on an interval and has nothing to report for the first cycle — so a single failure immediately after a change is not necessarily a problem.

Most common causes

• The metrics server is not installed in the cluster.
• The metrics server pod is not running or is crash-looping.
• The metrics server cannot reach kubelets, usually a TLS verification problem against kubelet serving certificates.
• The metrics APIService is registered but unavailable.
• The pods are too new and no sample has been collected yet.
• A firewall blocking the metrics server from reaching port 10250 on the nodes.

How to diagnose it

1. Check whether the API is registered and available: kubectl get apiservices | grep metrics.
2. Check the metrics server pod: kubectl get pods -n kube-system | grep metrics and read its logs.
3. Look for TLS errors in those logs — verification against kubelet certificates is the most common failure.
4. Test the API directly: kubectl get --raw /apis/metrics.k8s.io/v1beta1/nodes.
5. Wait a minute and retry if pods have only just started.

How to fix it

1. Install the metrics server if it is absent.
2. Fix kubelet certificate trust — either enable serving certificate rotation and approve the requests, or configure the metrics server appropriately for the cluster's certificate setup.
3. Open the network path from the metrics server to the kubelets.
4. Restore the APIService if it is unavailable.
5. Do not rely on kubectl top for historical analysis regardless — it reports only current values, and a monitoring system is the right tool for trends.

Notes

The same metrics server backs both kubectl top and CPU-based autoscaling. When it is broken, HPAs stop scaling and report unknown metrics, which is a quieter and more consequential symptom than a failing command.

Related

• unable to fetch metrics — The autoscaler cannot read its metric
• couldn't get current server API group list — Discovery against the API server failed

Sources

• Kubernetes documentation — Resource Metrics Pipeline
• Kubernetes documentation — Horizontal Pod Autoscaling
• Kubernetes documentation — Kubernetes Metrics Reference