Kubernetes Metrics Server Usage

Kubernetes Metrics Server Usage covers the deployment, configuration, and consumption of the Metrics Server, the cluster add-on responsible for collecting current CPU and memory usage from every node's kubelet and exposing it through the metrics.k8s.io API, forming the foundational resource-metrics data source that both kubectl top and resource-based Horizontal Pod Autoscaler scaling depend on.

What Metrics Server Provides and Does Not Provide

Current Resource Usage, Not Historical Data

Metrics Server collects and retains only recent, in-memory snapshots of CPU and memory usage — it is explicitly not a monitoring or time-series storage system, and does not retain historical data beyond what is needed to serve the current usage query; long-term trend analysis or alerting on historical resource patterns requires a separate monitoring system such as Prometheus.

kubectl top nodes
kubectl top pods --all-namespaces

The Foundation for Resource-Based HPA

The Resource metric type in a HorizontalPodAutoscaler queries Metrics Server (via the metrics.k8s.io aggregated API) directly; without Metrics Server deployed and functioning correctly, CPU and memory-based HPA scaling has no data source and will report a ScalingActive: False condition.

Deployment

Installing Metrics Server

Metrics Server is typically deployed as a standard Deployment with an associated APIService registration that plugs it into the Kubernetes aggregation layer, making its data queryable through the standard Kubernetes API rather than a separate endpoint.

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

Kubelet Communication Requirements

Metrics Server communicates with each node's kubelet to collect usage data via the kubelet's Summary API, requiring network connectivity from the Metrics Server pod to every kubelet and, in most production configurations, valid TLS certificate verification for that communication.

--kubelet-preferred-address-types=InternalIP
--kubelet-insecure-tls  # only for testing; production should verify certificates

Common Deployment Issues

Certificate Verification Failures

A frequent Metrics Server deployment problem is kubelet serving certificates that Metrics Server cannot verify, particularly in clusters using self-signed or non-standard certificate configurations, surfacing as kubectl top returning no data or explicit connection errors in the Metrics Server's own logs.

kubectl logs -n kube-system -l k8s-app=metrics-server

Network Policy Blocking Kubelet Access

In clusters with restrictive network policies, Metrics Server's pod may be blocked from reaching kubelets on their metrics port unless an explicit allow rule is configured, another common cause of Metrics Server appearing deployed but failing to report any data.

Verifying Metrics Server Health

Confirming the APIService Is Available

Checking that the v1beta1.metrics.k8s.io APIService reports as available confirms Metrics Server is correctly registered with the aggregation layer, a necessary but not sufficient condition for it actually returning valid data.

kubectl get apiservices v1beta1.metrics.k8s.io

Testing Direct API Queries

Querying the raw metrics API directly isolates whether a problem lies in Metrics Server itself or in a downstream consumer (an HPA, for instance) misinterpreting otherwise valid data.

kubectl get --raw "/apis/metrics.k8s.io/v1beta1/nodes"
kubectl get --raw "/apis/metrics.k8s.io/v1beta1/namespaces/payments/pods"

Operational Considerations

Resource Sizing for Metrics Server Itself

In very large clusters, Metrics Server's own resource requirements scale with the number of nodes and pods it must poll, and under-provisioning its own CPU or memory can cause it to fall behind or time out collecting data from all kubelets within its scrape interval, indirectly degrading HPA responsiveness.

High Availability

Running Metrics Server with multiple replicas, using leader election to ensure only one is actively serving at a time, avoids resource-based HPA scaling losing its data source entirely during a single pod's restart or node failure — a materially important consideration for any cluster relying on HPA for genuinely elastic workloads.

Scrape Interval and Staleness

Metrics Server's own collection interval (commonly around 15 seconds, configurable) adds to the overall latency of the HPA control loop, since the HPA can only ever act on data as fresh as Metrics Server's most recent successful collection from each node.