Kubernetes v1.37 promotes the Metrics API to the stable metrics.k8s.io/v1 API. The change gives clients a stable version to target for node and pod resource metrics, while v1beta1 remains available during the transition.
For platform teams, the graduation is primarily an API-version and discovery change rather than a resource-schema migration. The Kubernetes Enhancement Proposal describes the v1 graduation as non-breaking: the v1 surface is intended to match v1beta1 apart from the version name. That does not remove the need to check the implementation behind the API, however. Availability still depends on APIService registration, aggregation-layer configuration, and the metrics provider serving the requested version.
What changed in Kubernetes v1.37
The stable API version is metrics.k8s.io/v1, and Kubernetes v1.37 identifies the graduation as a stable milestone. The API exposes the same core resource types developers already use through v1beta1:
NodeMetricsandNodeMetricsListPodMetricsandPodMetricsList
Pod metrics include container names and usage values. Node and pod metrics also include timestamps, measurement windows, and usage-related data. The official metrics.k8s.io/v1 reference and the v1beta1 reference document the corresponding resource surfaces.
The Metrics API supplies CPU and memory resource metrics for nodes and pods in an implementation-agnostic form. Those metrics support workloads and tools such as the Horizontal Pod Autoscaler and kubectl top; they are not a replacement for a broader observability or application-monitoring system.
v1beta1 remains part of the transition
Kubernetes will continue serving metrics.k8s.io/v1beta1 alongside v1 during the migration period. The KEP says v1beta1 is deprecated after v1 becomes stable and will later be removed according to the Kubernetes deprecation policy. It provides a minimum support framework of at least three releases or nine months for a deprecated beta API, but it does not establish a release-specific removal date.
This coexistence allows teams to migrate clients without requiring an immediate, cluster-wide cutover. It also means that a client requesting one version can behave differently from a client requesting the other. Both v1.metrics.k8s.io and v1beta1.metrics.k8s.io APIService objects can be registered at the same time. A request is served only when the exact requested version has an available APIService; if that version is unavailable, the request can return HTTP 404 even when the other version works.
What administrators need to verify
The stable API declaration does not by itself create a metrics provider in a cluster. A Metrics API implementation must be running and must register and back the relevant APIService. Metrics Server is the common example, but the supplied Kubernetes documentation does not establish that every third-party implementation supports v1.
Metrics Server deployments also depend on the Kubernetes aggregation layer. Its documentation identifies kubelet Webhook authentication and authorization, appropriate kubelet certificate configuration, and environment-specific networking or address selection as prerequisites. The API graduation should therefore be treated separately from the operational health of the metrics implementation and its connections to kubelets.
Before changing a production client, administrators should verify the status of the v1.metrics.k8s.io APIService, inspect API discovery, and query a v1 metrics endpoint. The documented paths include:
/apis/metrics.k8s.io//apis/metrics.k8s.io/v1/
The KEP also points to aggregation-layer availability metrics such as aggregator_unavailable_apiservice for v1.metrics.k8s.io. These checks help distinguish an unavailable APIService from a failure in metrics collection between the provider and kubelets.
Implications for developers and platform tooling
Custom clients should use API discovery to determine which Metrics API version the target cluster serves. New or updated clients can prefer metrics.k8s.io/v1 and retain a controlled fallback to v1beta1 when compatibility with older or incompletely migrated clusters is required.
Because the documented resource surface is unchanged, clients that already deserialize the v1beta1 resources may not need a field or semantic migration. They do, however, need to avoid assuming that a v1 endpoint is available everywhere. A client hard-coded to v1 can receive a 404 if the v1 APIService is not registered or is unavailable, even if v1beta1 is healthy.
The Kubernetes project intends in-tree consumers such as the Horizontal Pod Autoscaler and kubectl top to migrate through discovery, preferring v1 and falling back to v1beta1 when v1 is unavailable. Teams operating custom autoscaling, capacity, or administration tooling should apply the same compatibility principle rather than relying on a single hard-coded endpoint.
What you should do
- Check discovery and APIService availability. Confirm that the target cluster exposes
metrics.k8s.io/v1and that its APIService reports as available. - Test a real v1 metrics request. Verify that the cluster returns node or pod metrics through the v1 endpoint, not merely that an APIService object exists.
- Update custom consumers. Prefer v1 through discovery, and retain v1beta1 fallback only where support for clusters without v1 is necessary.
- Test dependent workflows. Check
kubectl top, Horizontal Pod Autoscaler behavior, and other Metrics API consumers against the target implementation. - Review implementation prerequisites. Confirm aggregation-layer configuration, kubelet authentication and authorization, certificate trust, and any environment-specific Metrics Server settings.
- Plan for the beta API’s eventual removal. Do not assign a removal release date based only on this graduation; use the Kubernetes deprecation policy and later project announcements.
The Metrics Server documentation lists options such as --kubelet-preferred-address-types, --requestheader-client-ca-file, and node-selection settings for environment-specific configuration. The --kubelet-insecure-tls option is documented for testing and should not be treated as a general production recommendation.
Availability and remaining caveats
The stable API is available as part of the Kubernetes v1.37 milestone, but stable API status does not guarantee that a particular cluster’s metrics implementation is available, fresh, scalable, or compatible with v1. The supplied project material also does not identify a specific released Metrics Server version that serves v1, so teams should verify support against the implementation they actually deploy rather than assuming that an upgrade is universally required.
Similarly, the graduation itself is not described as a security fix or as a change to the security model. Implementations using the aggregation layer benefit from the API server’s authentication and authorization mechanisms, while Metrics Server has its own kubelet authentication, authorization, and certificate requirements. API-version graduation alone does not validate those settings.
