How to fix unable to fetch metrics from API in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 5, 2025· 272 views

The Horizontal Pod Autoscaler cannot retrieve CPU/memory metrics from the metrics-server. This blocks all autoscaling decisions and typically indicates the metrics-server is not installed or not running.

Quick fix

Fixes unable to fetch metrics from API

kubectl get deployment metrics-server -n kube-system
kubectl get pods -n kube-system -l k8s-app=metrics-server
  1. Verify Metrics Server is deployed and running
  2. Install or reinstall Metrics Server
  3. Test Metrics API endpoint directly
  4. Verify kubectl top commands work
kubernetes — error
kubectl get deployment metrics-server -n kube-system
kubectl get pods -n kube-system -l k8s-app=metrics-server
unable to fetch metrics from API

What this error means

The Horizontal Pod Autoscaler (HPA) relies on the Kubernetes Metrics Server to provide real-time CPU and memory usage data. When HPA reports 'unable to fetch metrics from API', it means the metrics-server component is either not installed, not running, or unable to communicate with the HPA controller. This completely blocks autoscaling decisions. The Metrics Server is a cluster add-on that collects resource metrics from kubelets and exposes them through the Kubernetes API aggregation layer (metrics.k8s.io). The HPA controller queries this API to get current CPU/memory usage, then compares it against target utilization to calculate the desired replica count. This error is common in self-hosted Kubernetes clusters where metrics-server must be manually installed, or when network policies block communication between the HPA controller and metrics-server.

Typical symptoms

  • HPA describe shows "unable to get metrics for resource" or "failed to get cpu utilization"
  • kubectl top pods returns error "Metrics not available" or "error: Metrics API not available"
  • kubectl top nodes returns error indicating metrics-server is not responding
  • HPA TARGETS column shows "<unknown>" for all metrics
  • Deployments never scale up or down regardless of load
  • Events show "FailedGetResourceMetric" with message about API unavailability

Common causes

  1. Metrics Server is not installed in the cluster (common in self-hosted clusters)
  2. Metrics Server pod is not running or in CrashLoopBackOff state
  3. Metrics API (metrics.k8s.io) is not registered with the API aggregation layer
  4. Network connectivity issues between HPA controller and metrics-server
  5. TLS certificate verification failures when metrics-server communicates with kubelets
  6. Missing RBAC permissions for metrics-server to access kubelet endpoints
  7. Firewall or network policies blocking port 443/4443 traffic to metrics-server

How to fix "unable to fetch metrics from API"

1Verify Metrics Server is deployed and running

Check if metrics-server exists and is healthy:

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

If metrics-server is not found or in CrashLoopBackOff:

bash
kubectl logs -n kube-system -l k8s-app=metrics-server | head -50

Common log errors include TLS failures or API server connectivity issues.

2Install or reinstall Metrics Server

If metrics-server is missing, install it from the official release:

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

Wait for the deployment to be ready:

bash
kubectl wait deployment metrics-server -n kube-system --for=condition=Available --timeout=120s

For clusters with self-signed certificates or insecure kubelets, add the --kubelet-insecure-tls flag:

bash
kubectl patch deployment metrics-server -n kube-system --type='json' -p='[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'
3Test Metrics API endpoint directly

Verify the metrics API is registered and responding:

bash
kubectl get --raw /apis/metrics.k8s.io/v1beta1/nodes
kubectl get --raw /apis/metrics.k8s.io/v1beta1/pods

If these return errors, check the APIService registration:

bash
kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

Look for conditions showing "Available: True". If False, the metrics-server service is not reachable.

4Verify kubectl top commands work

Test that metrics collection is functioning:

bash
kubectl top nodes
kubectl top pods -n <namespace>

If nodes work but pods don't, check kubelet configuration. If both fail, metrics-server is not properly connected.

Wait 60-90 seconds after installing metrics-server before testing, as initial metrics collection takes time.

5Check RBAC permissions and network policies

Verify metrics-server has proper RBAC:

bash
kubectl get clusterrolebinding | grep metrics
kubectl describe clusterrolebinding system:metrics-server

Check if network policies are blocking traffic:

bash
kubectl get networkpolicies -A

If you have restrictive network policies, ensure metrics-server can reach kubelets on port 10250 and the HPA controller can reach metrics-server.

6Verify HPA can now fetch metrics

After fixing metrics-server, verify HPA is working:

bash
kubectl describe hpa <hpa-name> -n <namespace>

Look for events without 'FailedGetResourceMetric' errors. The TARGETS column should show actual percentages instead of '<unknown>':

bash
kubectl get hpa -n <namespace>

Allow 30-60 seconds for metrics to propagate before checking HPA status.

Advanced notes

The Metrics Server architecture involves: HPA Controller → Metrics Aggregator API (metrics.k8s.io) → Metrics Server → kubelet summary endpoint. A failure at any level breaks the chain.

On managed Kubernetes (EKS, GKE, AKS), metrics-server is typically pre-installed. On EKS, verify the add-on is enabled. On GKE, it's enabled by default. On AKS, check the monitoring add-on.

TLS issues are common: metrics-server needs to validate kubelet certificates. Use --kubelet-insecure-tls for testing, but properly configure kubelet TLS for production.

HPA v2 (autoscaling/v2) supports container-level resource metrics, allowing more granular scaling decisions. This requires Kubernetes 1.30+ and metrics-server v0.6+.

Known issue: metrics-server v0.8.0 had compatibility problems with some cluster configurations. If experiencing issues, try v0.7.2 or the latest stable release.

For high-availability, deploy metrics-server with multiple replicas and pod anti-affinity to spread across nodes.

Frequently asked questions

What does "unable to fetch metrics from API" mean?
The Horizontal Pod Autoscaler (HPA) relies on the Kubernetes Metrics Server to provide real-time CPU and memory usage data. When HPA reports 'unable to fetch metrics from API', it means the metrics-server component is either not installed, not running, or unable to communicate with the HPA controller. This completely blocks autoscaling decisions.
How do I fix "unable to fetch metrics from API"?
The Horizontal Pod Autoscaler cannot retrieve CPU/memory metrics from the metrics-server. This blocks all autoscaling decisions and typically indicates the metrics-server is not installed or not running.
What causes "unable to fetch metrics from API"?
Metrics Server is not installed in the cluster (common in self-hosted clusters) Metrics Server pod is not running or in CrashLoopBackOff state Metrics API (metrics.k8s.io) is not registered with the API aggregation layer
Is the "unable to fetch metrics from API" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading