mediumIntermediateUSE#metrics#metrics-server#monitoring#kubectl-top

metrics-server missing or down — kubectl top fails with no metrics known

kubectl top pods returns error: metrics not available

Likely source:performancescaling

Focused incident mode — strips away everything but this runbook.

Symptoms

  • kubectl top pods returns error: metrics not available
  • kubectl top nodes fails with the server could not find the requested resource
  • HPA stuck unable to fetch metrics

metrics-server is the foundation for kubectl top, VPA, and CPU/memory-based HPA. Its absence silently degrades autoscaling for the entire cluster.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • kubectl top error

    kubectl top pods -n <namespace>

  • Metrics API check

    kubectl get --raw /apis/metrics.k8s.io/v1beta1

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • No metrics-server pods in kube-system
  • kubectl get --raw /apis/metrics.k8s.io/v1beta1 returns error

Confirm before fixing

kubectl get pods -n kube-system -l k8s-app=metrics-server
READ

Check for metrics-server

Fix

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

Install metrics-server

Expected: serviceaccount/metrics-server created

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
kubectl get --raw /apis/metrics.k8s.io/v1beta1
READ

Check metrics API registration

2
kubectl get pods -n kube-system -l k8s-app=metrics-server
READ

Verify pod is running

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

Install if missing

4
kubectl rollout restart deployment/metrics-server -n kube-system
CHANGE

Restart if crashing

5
kubectl top pods -n <namespace>
READ

Verify metrics are flowing again

Prevention

  • Install metrics-server as part of cluster bootstrap (Terraform/Helm).
  • Alert on metrics-server pod restarts or metrics API 503.
  • For managed clusters, verify the cloud provider does not install it by default.
  • Use Prometheus for long-term metrics; metrics-server is for real-time only.

Related runbooks

Same stack, same failure family — worth a skim.

HorizontalPodAutoscaler unable to fetch metrics — HPA not scalinghigh

HPA currentMetrics shows <unknown> or targets stuck at 0%

KubernetesAdvancedUSE3 causes
Open runbook
High CPU throttling — containers starved by CPU limitsmedium

High response latency with low CPU saturation on the node

KubernetesAdvancedUSE2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.