Metrics Server — the resource metrics API

The Metrics Server is the cluster’s resource metrics API. It provides the metrics.k8s.io API, which exposes CPU and memory usage for pods and nodes. This lesson walks the Metrics Server, the API surface, the integration with HPA and kubectl top, and the failure modes.

What the Metrics Server does

The Metrics Server collects CPU and memory usage from the kubelets and exposes them via the metrics.k8s.io API:

flowchart LR
    A[Kubelet] --> B[Metrics Server]
    B --> C[metrics.k8s.io API]
    C --> D[HPA]
    C --> E[kubectl top]
    C --> F[Custom adapters]

The Metrics Server is the resource metrics source.

The metrics.k8s.io API

The metrics.k8s.io API:

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

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "items": [
    {
      "metadata": {"name": "cp-1"},
      "timestamp": "2026-08-16T10:00:00Z",
      "window": "30s",
      "usage": {"cpu": "500m", "memory": "2048Mi"}
    }
  ]
}

The API exposes the metrics in JSON format.

The pod metrics

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

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "items": [
    {
      "metadata": {"name": "nginx-1-abc", "namespace": "default"},
      "containers": [
        {
          "name": "nginx",
          "usage": {"cpu": "100m", "memory": "128Mi"}
        }
      ]
    }
  ]
}

The pod metrics are per-container.

The Metrics Server deployment

The Metrics Server is deployed as a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      k8s-app: metrics-server
  template:
    metadata:
      labels:
        k8s-app: metrics-server
    spec:
      containers:
      - name: metrics-server
        image: registry.k8s.io/metrics-server/metrics-server:v0.7.x
        args:
        - --cert-dir=/tmp
        - --secure-port=4443
        - --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname
        - --kubelet-use-node-status-port
        - --metric-resolution=15s

The Deployment is a single replica.

The API Service

The API Service registers the Metrics Server:

apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
  name: v1beta1.metrics.k8s.io
spec:
  service:
    name: metrics-server
    namespace: kube-system
  group: metrics.k8s.io
  version: v1beta1
  groupPriorityMinimum: 100
  versionPriority: 100

The API Service registers the metrics.k8s.io API.

The kubectl top integration

The kubectl top uses the Metrics Server:

kubectl top nodes
kubectl top pods

NAME       CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
cp-1       500m         12%    2048Mi          26%
worker-1   800m         40%    4096Mi          52%

The output is the resource usage.

The HPA integration

The HPA uses the Metrics Server:

sequenceDiagram
    participant HPA as HPA controller
    participant M as Metrics Server
    participant K as Kubelet
    loop every 15s
        HPA->>M: get pod metrics
        M->>K: get kubelet metrics
        K-->>M: CPU/memory
        M-->>HPA: aggregated metrics
        HPA->>HPA: compute replicas
    end

The HPA queries the metrics.k8s.io API.

The kubelet integration

The kubelet exposes the metrics:

# Substitute your own value before running - the node's kubelet address:
NODE_IP=192.0.2.31

# The kubelet's metrics endpoint
curl -k "https://$NODE_IP:10250/metrics/resource"

The kubelet exposes the metrics in Prometheus format.

The Metrics Server scrapes the kubelet:

Metrics Server:
  - Periodically scrapes the kubelet's /metrics/resource
  - Aggregates the metrics
  - Exposes them via metrics.k8s.io API

The kubelet is the source.

The collection interval

The collection interval:

args:
- --metric-resolution=15s

The default is 15 seconds. The Metrics Server scrapes each kubelet every 15 seconds.

The Metrics Server vs Prometheus

The Metrics Server is not for Prometheus:

flowchart LR
    A[Kubelet] --> B[Metrics Server]
    A --> C[cAdvisor]
    B --> D[metrics.k8s.io API]
    C --> E[Prometheus]
    D --> F[HPA]
    D --> G[kubectl top]
    E --> H[Grafana]

The Metrics Server is for HPA and kubectl top; Prometheus uses cAdvisor.

The failure modes

The common failure modes:

Kubelet TLS

metrics-server: x509: certificate is valid for 10.0.1.10, not for 127.0.0.1

The Metrics Server cannot connect to the kubelet. The fix is to specify --kubelet-preferred-address-types.

API Service unavailable

error: metrics.k8s.io/v1beta1: the server is currently unable to handle the request

The Metrics Server is not running. Check the pod status.

Slow scraping

metrics-server: scrapes took 30s, threshold 15s

The Metrics Server is slow. Increase the --metric-resolution.

Cross-course references

• The HPA course (Part LXXXII) covers the integration.
• The Prometheus course (Part LXXXVIII) covers the cAdvisor.
• The Prometheus Operator course covers the auto-discovery.

Quiz

Production discipline

• Deploy the Metrics Server. Required for HPA on resource metrics.
• Configure the kubelet TLS. Use —kubelet-preferred-address-types.
• Use the HPA integration. The Metrics Server is the source.
• Use kubectl top. The interactive inspection.
• Monitor the metrics-server metrics. Prometheus exposes them.
• Document the deployment. The Helm values, the configuration.

The Metrics Server is the resource metrics API. Operating it well is deploying it, configuring the TLS, and integrating it with HPA and kubectl top.