Kubernetes 1.37: Metrics API Reaches Stability

The Metrics API is Stable – After Nearly Nine Years in Beta

With Kubernetes 1.37, metrics.k8s.io is released as v1, marking it as a Stable API. The Resource Metrics API has been part of the established infrastructure of a Kubernetes cluster for years: it provides current CPU and memory usage data for nodes and pods, is consumed by kubectl top, and forms the basis for resource-based autoscaling via the HorizontalPodAutoscaler.

Kubernetes 1.37 intentionally does not change its function. metrics.k8s.io/v1 has the same resources and fields as the previous v1beta1. No additional metrics or new data model are introduced. The relevant change lies in the API lifecycle: a beta interface existing since Kubernetes 1.8 becomes a stable API contract.

For cluster operators, this is initially a manageable migration. For platform teams and developers who directly consume Kubernetes APIs, the graduation is still relevant because it creates long-term stability guarantees for an interface that is often implicitly assumed to be part of the Kubernetes platform .

From Kubernetes 1.6 to 1.37

The Resource Metrics API was first introduced as Alpha with Kubernetes 1.6 and became Beta with Kubernetes 1.8. Since then, the API model has proven to be extremely stable. It has been productively used by Kubernetes components and external clients for years without requiring a fundamental revision of the schema.

With Kubernetes 1.37, this factual stability is now formalized:

metrics.k8s.io/v1beta1
metrics.k8s.io/v1

The unusually long beta phase is also interesting in the context of the Kubernetes API strategy. Beta APIs are by no means equated with experimental Alpha APIs and are regularly used productively in the Kubernetes ecosystem. However, they differ from Stable APIs in terms of long-term compatibility commitments and their deprecation lifecycle.

The graduation is therefore less a functional extension than a consolidation. An API whose data model has been established for years and builds on central Kubernetes functionality is elevated to the status that corresponds to its actual significance.

The Kubernetes project explicitly mentions the goal of avoiding APIs that remain in beta indefinitely. metrics.k8s.io was an obvious candidate with almost nine years in beta.

What metrics.k8s.io Provides

The API is deliberately narrowly defined and provides two resource types:

NodeMetrics
PodMetrics

NodeMetrics describes the current CPU and memory usage of a node. PodMetrics provides corresponding values for pods and further differentiates between the individual containers of a pod.

A query can be made directly via the Kubernetes API Server:

kubectl get --raw /apis/metrics.k8s.io/v1/nodes

For the pods of a namespace accordingly:

kubectl get --raw \
  /apis/metrics.k8s.io/v1/namespaces/default/pods

A node metric contains, in addition to the actual usage values, a timestamp and the measurement interval:

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1",
  "metadata": {
    "name": "worker-01"
  },
  "timestamp": "2026-08-28T10:00:00Z",
  "window": "30s",
  "usage": {
    "cpu": "487558164n",
    "memory": "732212Ki"
  }
}

This limitation to a few resource metrics is a key feature of the API. metrics.k8s.io is not a general telemetry interface nor a monitoring backend. The API provides standardized access to those short-term resource usage data that Kubernetes components need for certain operational decisions.

The most well-known consumers are kubectl top and the HorizontalPodAutoscaler.

Metrics API and metrics-server are Different Components

In practical Kubernetes operations, Metrics API and metrics-server are often used synonymously. Architecturally, however, they should be clearly separated.

metrics.k8s.io defines the API and its resource model. The metrics-server is a concrete implementation of this API.

This is relevant because the Metrics API is not fully implemented within the kube-apiserver as a regular core API. It uses the Kubernetes API Aggregation Layer. An implementation like metrics-server registers an additional API group via an APIService, which is then accessible through the regular Kubernetes API endpoint.

The data path can be simplified as follows:

Container
    │
    ▼
 kubelet
    │
    ▼
metrics-server
    │
    │  metrics.k8s.io
    ▼
API Aggregation Layer / kube-apiserver
    │
    ├── kubectl top
    │
    └── HorizontalPodAutoscaler

For a client, /apis/metrics.k8s.io/v1/... thus appears as part of the Kubernetes API. However, the requests are forwarded to the API server via the Aggregation Layer, which implements the corresponding API group.

This architecture has immediate consequences for the introduction of v1: An upgrade of the Kubernetes Control Plane to 1.37 does not necessarily mean that the metrics implementation used in the cluster automatically provides the Stable API.

The API implementation must support metrics.k8s.io/v1 itself and register it via a corresponding APIService.

Whether this is the case can be checked via API Discovery:

kubectl get --raw /apis/metrics.k8s.io/ | jq .

Additionally, the registered APIService can be inspected:

kubectl get apiservice v1.metrics.k8s.io

Especially in platforms where Control Plane, cluster add-ons, and their lifecycle are managed independently, this separation should be considered in upgrade planning.

What Actually Changes Between v1beta1 and v1

From the perspective of the API schema, the migration is unusually unspectacular. Kubernetes 1.37 adopts the existing resource types and fields unchanged in v1.

This means, in particular, that no adjustment to the processing of NodeMetrics or PodMetrics is required. Applications that directly consume the Metrics API primarily need to adjust the API version used.

Previously:

/apis/metrics.k8s.io/v1beta1/nodes

New:

/apis/metrics.k8s.io/v1/nodes

The fact that no schema change is associated with the graduation is relevant for operators of larger Kubernetes landscapes. An API graduation could otherwise require changes to clients, serialization, type definitions, or downstream processing steps. With metrics.k8s.io/v1, this coupling does not exist.

The migration can therefore be separated from functional changes to the metrics pipeline.

Stable Primarily Means a More Reliable API Contract

The main difference between v1beta1 and v1 is not in the data transmitted but in the stability commitments of the Kubernetes project.

Kubernetes APIs follow explicit rules for compatibility, deprecation, and removal. With a Stable API, developers and platform operators can assume much more long-term that existing integrations will remain across Kubernetes releases.

This is particularly relevant for software that not only uses Kubernetes through declarative resources but also interacts directly with the API: custom controllers, operators, platform services, cluster management systems, or other integrations.

For such components, an API version is part of the technical contract between Kubernetes and the overlying platform. A permanently used beta API therefore creates unnecessary uncertainty in the long run, even if it has remained stable for years.

The graduation eliminates this discrepancy.

v1beta1 Does Not Disappear with Kubernetes 1.37

The introduction of v1 does not mean that existing clients must migrate immediately. v1beta1 remains available during the transition phase.

A metrics implementation can thus offer both API versions in parallel:

metrics.k8s.io/v1
metrics.k8s.io/v1beta1

This allows for a decoupled upgrade process. Control Plane and metrics implementation can be updated first, followed by clients and integrations.

This transition phase is particularly necessary because within Kubernetes 1.37 itself, not all consumers handle the new API version in the same way.

kubectl top Already Prefers v1

In Kubernetes 1.37, kubectl supports both metrics.k8s.io/v1 and v1beta1.

For kubectl top, API Discovery is first used to check if the Stable API is available. If so, the client uses v1. Otherwise, it can still fall back to v1beta1.

This allows for a cluster, for example, whose Control Plane has already been updated to Kubernetes 1.37, but whose metrics implementation still only offers v1beta1. Similarly, newer metrics implementations can provide both versions in parallel.

For custom clients, this behavior is a sensible migration pattern. Instead of configuring a single endpoint exclusively, Kubernetes API Discovery can be used to determine which versions of the API group are actually available. A client can then prioritize v1 and use v1beta1 as a fallback during the transition phase.

This is especially relevant in cluster fleets where different Kubernetes and add-on versions are operated simultaneously.

The HorizontalPodAutoscaler Still Requires v1beta1 in 1.37

A much more important limitation for operations concerns the HorizontalPodAutoscaler. The HPA Controller still exclusively uses metrics.k8s.io/v1beta1 in Kubernetes 1.37.

This distinguishes it from kubectl top, which can already choose between the available API versions.

For operators, this results in a clear consequence: Anyone using resource-metrics-based autoscaling should not remove v1beta1 from the metrics API implementation after the introduction of v1.

A typical HPA might use CPU utilization as a scaling signal:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

The controller requires resource metrics of the associated pods. In Kubernetes 1.37, this query is still performed via v1beta1.

A metrics implementation that only provides:

metrics.k8s.io/v1

would thus be fundamentally on the current Stable API level but would not fully serve the HPA Controller of Kubernetes 1.37.

For the transition phase, therefore, the parallel provision of both versions is the sensible state:

metrics.k8s.io/v1
metrics.k8s.io/v1beta1

Only when the corresponding Kubernetes components themselves have migrated to v1 can a later removal of the beta version be sensibly evaluated.

The Metrics API is Not a Replacement for Prometheus

The term “Metrics API” occasionally leads to false expectations about its scope. metrics.k8s.io addresses a much narrower use case than traditional monitoring and observability systems.

The API provides current CPU and memory usage for nodes and pods. It does not provide a general time-series database, does not offer long-term historization, and is not intended as a universal interface.