Introduction

The Horizontal Pod Autoscaler depends on resource metrics being available through the Kubernetes metrics API. When those metrics are missing, the HPA shows <unknown> instead of a utilization value and scaling decisions stop. In most clusters, the issue is not the HPA object itself. It is metrics-server availability, kubelet scraping problems, or workloads that never declared the resource requests the HPA needs.

Symptoms

  • kubectl get hpa shows <unknown> instead of CPU or memory usage
  • kubectl top nodes or kubectl top pods returns no data
  • HPA events say it did not receive metrics for ready Pods
  • Scaling stays flat even though workload demand is clearly rising

Common Causes

  • metrics-server is not installed or is unhealthy
  • metrics-server cannot scrape kubelet metrics because of TLS or network issues
  • The metrics API service is not available
  • Pods do not define resource requests, so utilization cannot be calculated correctly

Step-by-Step Fix

  1. 1.Check whether metrics-server is installed and healthy
  2. 2.If metrics-server is down, every HPA based on resource metrics will degrade.
bash
kubectl get deployment metrics-server -n kube-system
kubectl logs -n kube-system deployment/metrics-server
  1. 1.Verify the metrics API is available
  2. 2.HPA ultimately consumes the metrics API, so confirm that API service is healthy.
bash
kubectl get apiservice v1beta1.metrics.k8s.io
kubectl top nodes
  1. 1.Check kubelet scraping and TLS compatibility
  2. 2.Clusters with self-signed or unusual kubelet certificates often require extra metrics-server tuning.
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"}]'
  1. 1.Confirm the target workload defines resource requests
  2. 2.CPU and memory utilization percentages need baseline requests, not only limits.
yaml
resources:
  requests:
    cpu: 100m
    memory: 128Mi

Prevention

  • Keep metrics-server monitored as part of cluster control-plane dependencies
  • Define resource requests on workloads that use HPA
  • Test kubectl top as a quick health check for the metrics path
  • Review metrics-server TLS and kubelet assumptions when cluster networking or certificates change