Decisions about capacity need live numbers.

A Kubernetes cluster runs many pods across many nodes, and demand on those pods changes constantly. A shop’s website is quiet at three in the morning and overwhelmed during a sale. If the cluster does not know how busy each pod is, it cannot add more copies when they are needed or remove them when they are wasteful. Someone would have to watch graphs all day and adjust by hand.

Knowing usage is also important for people. An engineer who wants to find out which pod is eating all the memory on a node needs a quick answer, not a long investigation. A capacity planner wants to see whether nodes are close to full. These questions all need the same basic ingredient: current CPU and memory usage for nodes and pods, available from one central place with a standard way to ask for it.

What problem this feature solves

Before a standard mechanism existed, every tool that needed usage numbers had to gather them on its own, in its own way. That was wasteful, inconsistent, and hard to secure. The Metrics Server provides one shared, standard source for basic resource usage, exposed through the normal Kubernetes API, so that every tool that needs the numbers asks the same place.

A small cluster add-on that gathers CPU and memory usage and serves it through the Kubernetes API.

The Metrics Server is a lightweight component that you run inside your cluster, usually as a single Deployment in the system namespace. Its job is narrow and clear. It periodically asks every node’s agent for the current CPU and memory usage of the node and of every container running there. It keeps the latest values in memory and makes them available through a standard endpoint of the Kubernetes API, so that any authorised client can read them.

It is important to understand what it is not. It is not a monitoring system. It does not store history, draw graphs, or send alerts. It only knows the most recent readings, and when it restarts, even those are gone until the next collection. It is designed to feed autoscalers and quick command-line checks, not to replace a full monitoring stack.

Kubernetes distinguishes a small built-in pipeline from a rich, optional one.

Kubernetes describes two different ways of collecting metrics. The resource metrics pipeline is the small, standard one. It carries only basic CPU and memory usage, and it exists to power core cluster features such as autoscaling and quick usage checks. The Metrics Server is the standard component of this pipeline.

The full metrics pipeline is the larger, optional one. It collects far more data, from nodes, containers, the Kubernetes objects themselves, and your applications, and it stores it over time. Tools such as Prometheus and its ecosystem belong here. This pipeline can also feed additional metrics back into Kubernetes, so that autoscalers can react to things like the number of requests per second rather than only CPU.

flowchart TD
    subgraph Resource metrics pipeline
        K1[Kubelet on each node] --> MS[Metrics Server
latest CPU and memory]
        MS --> API1[Metrics API]
        API1 --> HPA[Autoscalers]
        API1 --> TOP[kubectl top]
    end
    subgraph Full metrics pipeline
        K2[Kubelets, apps, cluster objects] --> COL[Collector and long-term storage]
        COL --> DASH[Dashboards and alerts]
        COL --> ADP[Adapter exposing custom metrics]
        ADP --> HPA
    end
        

From the container runtime, through the kubelet, to the Metrics Server.

The Metrics Server does not measure anything itself. It relies on a chain of components that already exist on every node. At the bottom, the container runtime and an embedded monitoring library track how much CPU and memory each container uses. The kubelet, the agent that runs on every node and manages its pods, collects these figures and exposes them through a small endpoint. The Metrics Server visits every kubelet on a schedule, reads that endpoint, and gathers the results into one cluster-wide picture.

sequenceDiagram
    participant C as Containers
    participant R as Runtime stats
    participant K as Kubelet on each node
    participant M as Metrics Server
    participant A as Kubernetes API Server
    participant U as Client such as autoscaler
    C->>R: Use CPU and memory
    R->>K: Provide usage statistics
    loop Every collection interval
        M->>K: Request resource metrics
        K-->>M: Node and pod usage
    end
    M->>M: Keep latest values in memory
    U->>A: Ask for pod metrics
    A->>M: Forward request through the aggregation layer
    M-->>A: Latest values
    A-->>U: Response
        

The Metrics Server extends the Kubernetes API instead of inventing a new interface.

The Kubernetes API server is the single front door of the cluster. Everything, from creating pods to reading their status, goes through it, with the same authentication and permission checks. The Metrics Server plugs into this front door using a feature called the aggregation layer. It registers itself as an extra API service, under a standard group name reserved for resource metrics. When a client asks the main API server for metrics, the request is transparently forwarded to the Metrics Server, and the answer comes back through the same door.

flowchart LR
    C[Client
autoscaler or person] --> API[Kubernetes API Server]
    API -->|resource metrics group| AGG[Aggregation layer]
    AGG --> SVC[Metrics Server service]
    SVC --> MS[Metrics Server pod]
    API -->|everything else| ETCD[Built-in API and storage]
        

Reading a usage figure correctly avoids many wrong conclusions.

The Metrics API reports two measurements for every node and every container: CPU and memory. Each comes with a timestamp, and a window that says over what period the figure was calculated. Understanding how each is measured explains why the numbers sometimes look different from what other tools show.

Why numbers differ between tools

People often compare the figures from the Metrics Server with figures from a monitoring system or from tools on the node, and find small differences. There are good reasons. Different tools may sample at different moments, average over different windows, or count memory differently, for example including or excluding cached file data. The Metrics Server deliberately reports the working set because it is what matters for decisions about running out of memory.

A handful of important clients rely on its numbers.

flowchart TD
    MS[Metrics Server] --> API[Metrics API]
    API --> TOP[kubectl top
people checking usage]
    API --> HPA[Horizontal Pod Autoscaler
more or fewer pods]
    API --> VPA[Vertical Pod Autoscaler
better requests]
    API --> TOOLS[Dashboards and scripts]
        

The Horizontal Pod Autoscaler is the most important consumer, and it has specific expectations.

The Horizontal Pod Autoscaler, often called the HPA, adjusts how many copies of an application run. On a regular cycle, roughly every fifteen seconds, it asks the Metrics API for the current usage of the pods it manages. It compares that usage with a target you set, such as fifty percent of requested CPU, and calculates how many pods would bring usage close to the target. If more are needed, it scales up. If fewer would do, it scales down, though more cautiously.

sequenceDiagram
    participant H as Autoscaler
    participant A as Metrics API
    participant D as Deployment
    loop Every sync period
        H->>A: Current CPU use of my pods
        A-->>H: Usage values
        H->>H: Compare average use with target of requests
        alt Use above target
            H->>D: Increase replicas
        else Use below target
            H->>D: Decrease replicas after stabilisation
        end
    end
        

Utilisation is relative to requests

The autoscaler does not compare usage with the size of the node or with limits. It compares usage with what each pod requested. If a pod requested half a core and is using a quarter of a core, its utilisation is fifty percent. This means that pods without resource requests cannot be autoscaled on utilisation. The autoscaler reports an error saying that it is missing a request, and shows the target as unknown.

It is easy to install, but several conditions must hold for it to work.

The Metrics Server is installed like any other cluster add-on, through a ready-made set of manifests or a package, which creates a Deployment, a Service, the permissions it needs, and the API service registration. Some managed Kubernetes platforms and local development tools include it already or provide a simple switch to enable it, while others require you to install it yourself. Check what your platform provides before installing a second copy.

The most common installation problem is about trust between the Metrics Server and the nodes.

When the Metrics Server contacts a kubelet, it uses an encrypted connection and checks the kubelet’s certificate, just as your browser checks a website’s certificate. In some clusters, especially local test clusters and some self-built ones, the kubelets use self-signed certificates, or certificates that do not list the address the Metrics Server uses to reach them. The Metrics Server then refuses to trust them, and collection fails with certificate errors.

A very common quick fix found in tutorials is an option that tells the Metrics Server to skip certificate verification of kubelets. This makes the error disappear, and it is perfectly reasonable in a throwaway development cluster. In production, though, it removes an important protection. Without verification, the Metrics Server cannot be sure it is talking to a real node, and an attacker who can intercept traffic on the node network could impersonate one.

flowchart TD
    A[Certificate error from kubelet] --> B{Production cluster?}
    B -->|No, disposable| C[Skipping verification is acceptable]
    B -->|Yes| D[Fix the real cause]
    D --> E[Issue kubelet serving certificates signed by the cluster authority]
    D --> F[Make sure certificates list the addresses used to reach nodes]
    D --> G[Choose the right preferred address type for the Metrics Server]
        

A single replica is fine for learning, but production autoscaling depends on it.

The Metrics Server is small, but a lot depends on it. If it is down, autoscalers cannot get data, and they stop scaling. Applications then stay at whatever size they had when the outage began, which can be dangerous during a traffic spike. For this reason, production clusters usually run more than one replica.

How big does it need to be?

The Metrics Server is designed to be light. As a rough rule from the project’s guidance, it needs on the order of a thousandth of a core of CPU and a couple of megabytes of memory for each node in the cluster. A cluster of a hundred nodes therefore needs only a modest amount, but requests should still be set so that the scheduler reserves room for it. Very large clusters, with thousands of nodes, need proportionally more and should follow the project’s sizing guidance closely.

There is always a delay between something happening and the cluster reacting to it.

The Metrics Server collects data on a schedule, by default about every fifteen seconds. That means any figure you read may be up to that old. On top of this, autoscalers check the numbers on their own schedule, and then need time to start new pods. These delays add up, and understanding them explains why autoscaling is never instant.

sequenceDiagram
    participant L as Load spike
    participant K as Kubelet
    participant M as Metrics Server
    participant H as Autoscaler
    participant S as Scheduler and nodes
    L->>K: Usage rises
    Note over K,M: Wait for next collection, up to the interval
    M->>K: Scrape
    K-->>M: New usage
    Note over M,H: Wait for next autoscaler check
    H->>M: Read usage
    H->>S: Ask for more pods
    Note over S: Pods are scheduled, images pulled, containers start, readiness passes
    S-->>L: New capacity begins to serve traffic
        

Several tools have “metrics” in the name, and each answers a different question.

The Kubernetes ecosystem contains several components that produce or collect metrics, and beginners often mix them up. The differences are simple once you know what each looks at. Some measure the resources that containers consume. Some describe the state of Kubernetes objects. Some measure the machines themselves. And some store and analyse all of these over time.

flowchart TD
    Q{What do you need?} -->|Autoscale on CPU or memory| MS[Metrics Server]
    Q -->|Quick look at current usage| MS
    Q -->|History, graphs, alerts| PR[Monitoring system]
    Q -->|Health of deployments and pods as objects| KS[State metrics exporter]
    Q -->|Machine level details| NE[Node exporter]
    Q -->|Autoscale on requests or queue length| AD[Custom metrics adapter]
        

Being small and simple means that some things are simply out of scope.

Situations where it is exactly the right tool.

Metrics only make sense when compared with what each pod asked for.

Every container can declare a request, the amount of CPU and memory the scheduler should reserve for it, and a limit, the most it is allowed to use. These two numbers give meaning to the usage figures from the Metrics Server. Usage of a quarter of a core means one thing for a pod that requested half a core and something quite different for one that requested a tenth.

Small by design, but not free at very large scale.

The Metrics Server does one thing, and does it efficiently: it contacts every node on a schedule and keeps the results in memory. Because it stores nothing on disk and computes nothing complicated, it uses very few resources, and it is designed to support clusters of thousands of nodes. Its costs grow with the number of nodes and pods, since it must contact each node and hold its readings, and with how often it does so.

Resource usage looks harmless, but access still needs to be controlled.

The Metrics Server talks to every node and serves information about every pod, so it touches several security boundaries. It must be authorised to read from kubelets, it must prove its identity to the API server, and clients who read metrics must be permitted to do so. Each of these connections should be locked down according to the principle of giving only the permissions that are needed.

Most problems fall into three groups: the API service, the connection to nodes, and the data itself.

When metrics do not appear, the cause almost always lies in one of three places. Either the API server cannot reach the Metrics Server, or the Metrics Server cannot collect from the nodes, or the data is there but incomplete for a reason that is easy to explain. Working through the chain in order finds the problem quickly, because each link can be checked on its own.

The component that watches everything needs somebody watching it.

Because autoscaling depends on the Metrics Server, its failure is easy to overlook and costly. If it silently stops, autoscalers freeze at their current size. A well-run cluster therefore monitors the Metrics Server just as carefully as it monitors the applications it helps to scale.

flowchart TD
    W[Monitoring system] --> A1[Alert: API service unavailable]
    W --> A2[Alert: Metrics Server not ready]
    W --> A3[Alert: scrape failures rising]
    W --> A4[Alert: nodes missing from metrics]
    W --> A5[Alert: autoscaler cannot fetch metrics]
    A1 --> R[On-call engineer investigates the chain]
    A2 --> R
    A3 --> R
    A4 --> R
    A5 --> R
        

Habits that make autoscaling and usage checks dependable.

flowchart TD
    A[Define requests and limits] --> B[Install Metrics Server in high availability]
    B --> C[Create autoscaler with sensible min and max]
    C --> D[Monitor autoscaler and metrics health]
    D --> E[Review usage against requests regularly]
    E --> A
        

Habits that lead to broken autoscaling and false confidence.

A short checklist for a dependable metrics pipeline.

How teams use the Metrics Server in daily operations.

A cluster add-on that collects current CPU and memory usage of nodes and pods from every kubelet and serves it through the Kubernetes Metrics API. It powers command-line usage checks and autoscaling.

No. It keeps only the latest readings in memory. For history, graphs, and alerts, use a monitoring system.

Often because the Metrics Server was just installed and has not completed enough collection cycles. If it persists, check the API service status, the pods, and the logs.

Common reasons are missing resource requests on the pods, metrics not yet available for new pods, or an unavailable Metrics Server. Utilisation is calculated relative to requests, so requests are essential.

It is acceptable in a disposable development cluster, but not in production. It removes protection against impersonated nodes, and the underlying certificate problem should be fixed instead.

By default about every fifteen seconds. The interval can be changed within supported limits, but shortening it adds load on every node with little benefit for most autoscaling.

Usually yes, for standard CPU and memory autoscaling and for the command-line usage tool. The two serve different purposes and are commonly run together.

It is the average rate of processor use over a short window, expressed in cores or fractions of a core. Memory is reported as the working set, the memory in active use.

Not by itself. It supports CPU and memory only. For other signals, use a custom or external metrics adapter fed from a monitoring system.

Usage commands fail and autoscalers cannot read metrics, so they stop scaling. Existing pods keep running at their current size. Running multiple replicas and alerting on health reduces the risk.

Very little: roughly a thousandth of a core of CPU and a couple of megabytes of memory per node. Set requests accordingly and follow the project’s sizing guidance for large clusters.

Tools sample at different moments, average over different windows, and may count memory differently. The Metrics Server reports short-window CPU rates and working-set memory, so small differences are expected.

The Metrics Server is the small, standard component that tells a Kubernetes cluster how much CPU and memory its nodes and pods are using right now. It collects the numbers from every kubelet on a regular schedule, keeps only the latest values in memory, and serves them through the Metrics API using the API server’s aggregation layer. Its most important users are the command-line usage tool and the autoscalers, which rely on it to decide when to add or remove pods.

Its strength is its simplicity, and its limits follow from the same simplicity: no history, no alerts, and only two resource types. Using it well means setting realistic resource requests, running it in high availability with proper certificates and permissions, monitoring its own health, and pairing it with a full monitoring stack for everything it does not cover. With those habits, it quietly provides the live numbers that keep a cluster elastic and efficient.