highAdvancedUSE#hpa#autoscaling#metrics#scaling

HorizontalPodAutoscaler unable to fetch metrics — HPA not scaling

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

Likely source:scalingavailability

Focused incident mode — strips away everything but this runbook.

Symptoms

  • HPA currentMetrics shows <unknown> or targets stuck at 0%
  • HPA does not scale up despite high load
  • kubectl describe hpa shows unable to fetch metrics from custom metrics API

Evidence to grab

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

  • HPA status

    kubectl describe hpa <hpa> -n <namespace>

  • Metrics API availability

    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

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

Confirm before fixing

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

Check metrics-server replicas

Fix

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

Install metrics-server from the official manifest

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

Confirm the metrics API is reachable

2
kubectl describe hpa <hpa> -n <namespace>
READ

Read the scaling conditions and error messages

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

Check metrics-server health

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

Restart metrics-server if it is crashing

Prevention

  • Monitor metrics-server pods and alert if any replica is not Ready.
  • Test HPA scaling in staging before production to confirm metrics flow.
  • Usekubectl top pods regularly to verify the metrics API is healthy.
  • Document custom metrics names and validate them in Prometheus before wiring the HPA.

Related runbooks

Same stack, same failure family — worth a skim.

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

kubectl top pods returns error: metrics not available

KubernetesIntermediateUSE3 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
Pods stuck in Pending state — unschedulablehigh

kubectl get pods shows Pending for minutes

KubernetesIntermediate3 causes
Open runbook

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