Kubernetes v1.37 Promotes Metrics API to Stable (v1)

Metrics API Reaches Stability

Kubernetes v1.37 officially promotes the metrics.k8s.io API to its stable v1 version. This API is crucial for monitoring CPU and memory usage across Kubernetes nodes and Pods, serving as the backend for commands such as `kubectl top` and for resource-metrics-based autoscaling mechanisms.

Stability Guarantees and No Functional Changes

The graduation to stable signifies that the API now carries the stability guarantees associated with Kubernetes' stable APIs. Importantly, the v1 API retains the same resource types and fields as its v1beta1 predecessor. This means the change is an API-version graduation, not an alteration to the metrics collected or returned by the API.

API History and Purpose

The resource Metrics API was initially introduced as an alpha version in Kubernetes v1.6 and later became beta in v1.8. It has been used in production environments for several years by clients like the HorizontalPodAutoscaler (HPA) and `kubectl top`. The API is designed to be intentionally small, focusing on providing essential resource metrics for autoscaling and basic inspection, rather than replacing full monitoring pipelines or custom metrics APIs.

API Endpoints and Client Support

The stable API exposes two resource types: `NodeMetrics` for node CPU and memory usage, and `PodMetrics` for Pod CPU and memory usage, including a per-container breakdown. Clients can retrieve node metrics from `/apis/metrics.k8s.io/v1/nodes` and Pod metrics from `/apis/metrics.k8s.io/v1/namespaces/{namespace}/pods`. `kubectl top` supports both API versions, preferring v1 when available and falling back to v1beta1. The HPA controller currently supports only v1beta1, with plans for discovery-based selection between v1 and v1beta1 in the future.

Implementation Requirements

No feature gates need to be enabled for the Metrics API. It is served through the API aggregation layer by an implementation such as metrics-server. For the v1 metrics API to be available in a cluster, the chosen implementation must serve the `v1.metrics.k8s.io` API, and an associated APIService must be registered. Implementations are expected to serve both v1 and v1beta1 during the transition period.