Kubernetes Metrics Server: what it does, how to install it, and when to use Prometheus instead

The gap Metrics Server fills in a Kubernetes cluster

Kubernetes ships Horizontal Pod Autoscaler and Vertical Pod Autoscaler as controllers, but neither can read CPU or memory from the Kubelet on its own. The autoscalers consume the Metrics API, and the Metrics API is an aggregated API served by something running inside the cluster. Metrics Server is that something. It is a single deployment that collects resource metrics from Kubelets and exposes them through the Kubernetes apiserver, so both autoscalers and kubectl top can query the same endpoint.

The audience is narrow by design. If you are running a cluster and you want `kubectl top pods` to return numbers, or you want an HPA on CPU utilization to make decisions, you need this component or something that speaks the same API. The README is explicit that the project is meant only for autoscaling, and warns against using it to forward metrics to a monitoring system or as a source for one. That is not modesty about the project's quality. It is a statement about sampling and retention: the data is collected on a short interval to drive a control loop, not to be a historical record.

How the Metrics API is served: aggregation, Kubelets and the 15 second loop

The data flow is short. Metrics Server watches the Node objects in the cluster, reads the addresses from `.status.addresses` and the Kubelet port from `.status.daemonEndpoints.kubeletEndpoint.port` (default 10250), then scrapes each Kubelet for container resource metrics. It registers itself as an API service for the `metrics.k8s.io/v1beta1` group, which is why the kube-apiserver must have the aggregation layer enabled: the apiserver proxies requests for that group to Metrics Server rather than serving them from etcd. When you run `kubectl top`, or when the HPA controller asks for pod metrics, the request goes to the apiserver and is forwarded.

Which node address it picks is not arbitrary. Metrics Server uses the `kubelet-preferred-address-types` command line flag, and the README says the manifests default it to `InternalIP,ExternalIP,Hostname`. On clusters where the internal IP is not routable from the pod network, that default is the first thing to change, and the symptom is a Metrics Server that runs cleanly but returns nothing.

The collection interval is 15 seconds, per the README, which is what the project means by fast autoscaling. The resource claim is 1 mili core of CPU and 2 MB of memory per node, with support stated up to 5,000 node clusters. Treat those as the project's own figures rather than measured results.

Installing Metrics Server from components.yaml and reading the first result

The README gives two routes: a YAML manifest and the official Helm chart. The manifest route is one command against the latest release.

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

The manifest creates the deployment, the RBAC, and the APIService object that wires `metrics.k8s.io/v1beta1` into the aggregation layer. After applying it, the deployment needs a moment before the API is ready. If the APIService registers before the backing pods serve, requests fail temporarily; that is expected on a fresh install, not a misconfiguration.

The first real check is whether the API answers at all.

kubectl get apiservice v1beta1.metrics.k8s.io
kubectl top nodes

The APIService should report Available, and `kubectl top nodes` should print CPU and memory per node. If the APIService stays unavailable, the README's requirements list is the checklist: aggregation layer enabled on the kube-apiserver, webhook authentication and authorization on the nodes, Kubelet certificates signed by the cluster CA, and a container runtime that implements the container metrics RPCs or has cAdvisor support.

For Helm, the chart is maintained inside this repository and published to a chart repository backed on the `gh-pages` branch. The README notes a new chart version is released for each Metrics Server release and can also be released independently, and warns against referencing the chart on `master` directly because it may contain changes since the last release. Use the chart release tag. High availability is a `replicas` value greater than 1 through the chart, or the separate manifest.

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/high-availability-1.21+.yaml

The README states this configuration requires a cluster with at least 2 nodes, and recommends adding `--enable-aggregator-routing=true` to the kube-apiserver so requests are load balanced between the instances.

Cluster requirements that decide whether the install succeeds

Most failed installs are not Metrics Server bugs. They are clusters that do not meet the prerequisites, and the README says plainly that these requirements are not the default for all distributions. Four matter most.

The kube-apiserver must enable an aggregation layer. Without it there is no way to register the Metrics API, and the APIService never becomes available.

Nodes must have webhook authentication and authorization enabled. Metrics Server authenticates to the Kubelet as a client, and if the Kubelet is not configured to accept that, scrapes are rejected.

The Kubelet certificate must be signed by the cluster Certificate Authority. Where it is not, the documented workaround is passing `--kubelet-insecure-tls` to Metrics Server, which disables certificate validation. That is a real trade-off and it should be a deliberate one: it removes the verification step between Metrics Server and every Kubelet in the cluster. Self-managed clusters created with kubeadm commonly hit this; managed distributions usually do not.

Network reachability runs in both directions. The control plane must reach the Metrics Server pod IP on port 10250, or the node IP and a custom port when `hostNetwork` is enabled. Metrics Server must reach the node address and Kubelet port on every node. A network policy that blocks either direction produces an install that looks healthy and returns no metrics.

Where Metrics Server is the wrong tool

The README lists the exclusions directly, and they are worth taking at face value. Do not use it for non-Kubernetes clusters. Do not use it as an accurate source of resource usage metrics. Do not use it for horizontal autoscaling on resources other than CPU and memory.

The accuracy point deserves emphasis because it is the one people argue about. Metrics Server samples on an interval and serves a recent value. A container that spikes between samples is not represented, and there is no retention to query later. If you need to answer what a workload used last Tuesday, or to bill for it, this component cannot answer that question and was not built to. The README directs those use cases to collecting from the Kubelet `/metrics/resource` endpoint directly, or to a full monitoring solution.

There is a second limitation that is structural rather than documented as a warning: Metrics Server depends on the aggregation layer, so it is only as available as the apiserver path in front of it. The high availability manifest exists precisely because a single replica is a single point of failure for every HPA in the cluster. Running one replica in production and discovering it during an autoscaling incident is a common and avoidable mistake.

Metrics Server compared with Kube-State-Metrics and Prometheus

The most common confusion is between Metrics Server and Kube-State-Metrics, and the difference is what each one reads. Metrics Server talks to Kubelets and reports resource consumption: how much CPU and memory a pod or node is using right now, served through the Metrics API. Kube-State-Metrics reads the Kubernetes API objects themselves and reports state: how many replicas a Deployment wants, whether a Pod is ready, what a node's conditions are. They answer different questions and are not substitutes. An HPA needs the first. A dashboard about desired versus available replicas needs the second.

Prometheus is the alternative the README itself names for unsupported use cases. The difference in approach is collection and storage. Metrics Server is a pull-from-Kubelet, serve-through-the-apiserver component with a short interval and no long-term store. Prometheus scrapes endpoints on its own schedule, stores samples in a time series database, and supports querying and alerting over history. That is why it can be both a monitoring system and, with an adapter, a source for autoscaling on metrics Metrics Server does not carry. The cost is a larger operational surface: storage, retention, and query capacity become your problem.

Versions, maintenance and the Apache-2.0 licence

Compatibility is versioned tightly and the README provides a matrix. Metrics Server 0.9.x serves `metrics.k8s.io/v1beta1` and supports Kubernetes 1.34 and later. 0.8.x covers 1.31+, 0.7.x covers 1.27+, and 0.6.x covers 1.25+. Older lines reach back further but with asterisks: Kubernetes versions lower than v1.16 require passing `--authorization-always-allow-paths=/livez,/readyz`. The API group has stayed at `v1beta1` across all of these, so the version that moves is the server, not the API surface.

Upgrades are a manifest or chart version change, and the practical cost is the compatibility window rather than migration work. Because the API group is unchanged, an HPA does not need editing when you move from 0.8.x to 0.9.x. What does need attention is the Kubernetes version you are running against: the matrix is the constraint, and running a Metrics Server line below your cluster version is the failure mode to check first when metrics stop appearing after a cluster upgrade.

The repository is not archived, and the last push was on 2026-09-21. Recent releases include v0.9.0 on 2026-07-13 and two Helm chart releases, 3.13.1 on 2026-06-11 and 3.14.0 on 2026-08-19, which matches the README's description of the chart being released alongside the server and sometimes independently. The project is licensed under Apache-2.0, which permits commercial use and modification with the usual notice and attribution conditions; the repository carries the standard LICENSE file, and anyone redistributing a modified build should read it rather than rely on a summary.

Editorial conclusion

Adopt Metrics Server if you run a supported Kubernetes version, need CPU and memory signals for Horizontal or Vertical Pod Autoscaler, and can meet the aggregation layer and Kubelet certificate requirements. Do not adopt it if you need an accurate resource usage record, non-Kubernetes clusters, or autoscaling on metrics other than CPU and memory; the README points those cases at a full monitoring solution such as Prometheus. Before rolling it out, verify that your kube-apiserver has the aggregation layer enabled, that your Kubelet certificates chain to the cluster CA (or that you accept --kubelet-insecure-tls), and that the control plane can reach the Metrics Server pod on port 10250.

Frequently asked questions

Official sources

1. kubernetes-sigs/metrics-server on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases