Kubernetes v1.37: Metrics API graduates to stable

Kubernetes v1.37 promotes the metrics.k8s.io API to stable (v1).

This API provides CPU and memory usage for nodes and Pods, and is the API behind commands such as kubectl top and resource-metrics-based autoscaling. For cluster operators and application developers, this graduation means that the API now has the stability guarantees associated with a Kubernetes stable API.

The v1 API has the same resource types and fields as v1beta1; this is an API-version graduation, not a change to the metrics that are collected or returned. A long-lived API reaches stable The resource Metrics API was introduced as alpha in Kubernetes v1.6 and became beta in v1.8.

It has remained unchanged and has been used in production for years by clients including the HorizontalPodAutoscaler (HPA) and kubectl top. Kubernetes v1.37 formally graduates that proven API to metrics.k8s.io/v1. The API exposes two resource types: NodeMetrics, for CPU and memory usage for a node.

PodMetrics, for CPU and memory usage for a Pod, with a per-container breakdown in its containers field. The API remains intentionally small. It provides the resource metrics needed for autoscaling and basic inspection; it is not a replacement for a full monitoring pipeline or the custom metrics (custom.metrics.k8s.io) API.

What changed with the v1.37 release? The v1 API surface is identical to v1beta1, except for the API version. There are no renamed fields, new fields, or changes to the meaning of the returned CPU and memory values.

For example, a client can retrieve node metrics from the stable endpoint: kubectl get --raw /apis/metrics.k8s.io/v1/nodes Likewise, it can retrieve metrics for the pods in a namespace: kubectl get --raw /apis/metrics.k8s.io/v1/namespaces/default/pods kubectl top supports both API versions. It prefers v1 when available and automatically falls back to v1beta1 on clusters that do not yet serve v1.

The HPA controller currently supports only v1beta1. Support for discovery-based selection between v1 and v1beta1 is planned, but is not available in Kubernetes v1.37. What you need to do You don't need to enable any feature gate.

The Metrics API is served through the API aggregation layer, by an implementation such as metrics-server. You can choose any implementation of metrics.k8s.io; for the v1 metrics API to be available in your cluster, your chosen implementation must serve the v1.metrics.k8s.io API, and you need to register an associated APIService. During the transition, implementations should serve both v1 and v1beta1.

Keeping both versions available maintains compatibility with older clients. The v1beta1 API remains available in Kubernetes v1.37. You can see which versions your cluster serves with: kubectl get --raw /apis/metrics.k8s.io/ | jq .

Once your metrics implementation supports v1, you can also check that its APIService is available: kubectl get apiservice v1.metrics.k8s.io Learn more Read the Resource metrics pipeline documentation. Read KEP-5207, the proposal for (graduating) this API. Learn about the Metrics API and its reference implementation, metrics-server.

Get involved The Metrics API is maintained by SIG Instrumentation. To ask questions, share feedback, or contribute, join the #sig-instrumentation channel on Kubernetes Slack or attend a SIG Instrumentation meeting.