Kubernetes 1.37:

Die Metrics API ist Stable – nach fast neun Jahren Beta

Mit Kubernetes 1.37 wird metrics.k8s.io als v1 und damit als Stable API veröffentlicht. Die Resource Metrics API gehört seit Jahren zur etablierten Infrastruktur eines Kubernetes-Clusters : Sie stellt aktuelle CPU- und Memory-Nutzungsdaten für Nodes und Pods bereit, wird von kubectl top konsumiert und bildet die Grundlage für ressourcenbasiertes Autoscaling über den HorizontalPodAutoscaler.

An ihrer Funktion ändert Kubernetes 1.37 bewusst nichts. metrics.k8s.io/v1 besitzt dieselben Ressourcen und Felder wie die bisherige v1beta1. Es kommen weder zusätzliche Metriken noch ein neues Datenmodell hinzu. Die relevante Änderung liegt im API-Lifecycle: Aus einer seit Kubernetes 1.8 bestehenden Beta-Schnittstelle wird ein stabiler API-Vertrag.

Für Cluster-Betreiber ist das zunächst eine überschaubare Migration. Für Plattformteams und Entwickler, die Kubernetes-APIs direkt konsumieren, ist die Graduation dennoch relevant, weil sie langfristige Stabilitätsgarantien für eine Schnittstelle schafft, die häufig implizit als Bestandteil der Kubernetes-Plattform vorausgesetzt wird.

Von Kubernetes 1.6 bis 1.37

Die Resource Metrics API wurde mit Kubernetes 1.6 zunächst als Alpha eingeführt und bereits mit Kubernetes 1.8 zu Beta. Seitdem hat sich das API-Modell als ausgesprochen stabil erwiesen. Über Jahre wurde es produktiv von Kubernetes-Komponenten und externen Clients genutzt, ohne dass eine grundlegende Revision des Schemas erforderlich wurde.

Mit Kubernetes 1.37 wird diese faktische Stabilität nun formalisiert:text metrics.k8s.io/v1beta1 metrics.k8s.io/v1

Die ungewöhnlich lange Beta-Phase ist auch vor dem Hintergrund der Kubernetes-API-Strategie interessant. Beta APIs sind keineswegs mit experimentellen Alpha APIs gleichzusetzen und werden im Kubernetes-Ökosystem regelmäßig produktiv eingesetzt. Dennoch unterscheiden sie sich von Stable APIs hinsichtlich der langfristigen Kompatibilitätszusagen und ihres Deprecation Lifecycle.

Die Graduation ist daher weniger eine funktionale Erweiterung als eine Konsolidierung. Eine API, deren Datenmodell seit Jahren etabliert ist und auf die zentrale Kubernetes-Funktionalität aufbaut, wird in den Status überführt, der ihrer tatsächlichen Bedeutung entspricht.

Das Kubernetes-Projekt nennt in diesem Zusammenhang explizit das Ziel, dauerhaft in Beta verbleibende APIs zu vermeiden. metrics.k8s.io war mit fast neun Jahren Beta-Laufzeit ein offensichtlicher Kandidat.

Was metrics.k8s.io bereitstellt

Die API ist bewusst eng definiert und stellt zwei Ressourcentypen bereit:text NodeMetrics PodMetrics

NodeMetrics beschreibt die aktuelle CPU- und Memory-Nutzung eines Nodes. PodMetrics stellt entsprechende Werte für Pods bereit und differenziert dabei zusätzlich zwischen den einzelnen Containern eines Pods.

Eine Abfrage kann direkt über den Kubernetes API Server erfolgen:bash kubectl get –raw /apis/metrics.k8s.io/v1/nodes

Für die Pods eines Namespaces entsprechend:bash kubectl get –raw
/apis/metrics.k8s.io/v1/namespaces/default/pods

Eine Node-Metrik enthält neben den eigentlichen Nutzungswerten insbesondere einen Timestamp und das Messintervall:json { “kind”: “NodeMetrics”, “apiVersion”: “metrics.k8s.io/v1”, “metadata”: { “name”: “worker-01” }, “timestamp”: “2026-08-28T10:00:00Z”, “window”: “30s”, “usage”: { “cpu”: “487558164n”, “memory”: “732212Ki” } }

Diese Beschränkung auf wenige Resource Metrics ist eine wesentliche Eigenschaft der API. metrics.k8s.io ist keine allgemeine Telemetrieschnittstelle und auch kein Monitoring-Backend. Die API stellt einen standardisierten Zugriff auf diejenigen kurzfristigen Resource-Usage-Daten bereit, die Kubernetes-Komponenten für bestimmte operative Entscheidungen benötigen.

Die bekanntesten Consumer sind kubectl top und der HorizontalPodAutoscaler.

Metrics API und metrics-server sind unterschiedliche Komponenten

Im praktischen Kubernetes-Betrieb werden Metrics API und metrics-server häufig synonym verwendet. Architektonisch sollte man beide jedoch klar voneinander trennen.

metrics.k8s.io definiert die API und deren Ressourcenmodell. Der metrics-server ist eine konkrete Implementierung dieser API.

Das ist relevant, weil die Metrics API nicht als reguläre Core API vollständig innerhalb des kube-apiserver implementiert wird. Sie verwendet die Kubernetes API Aggregation Layer. Eine Implementierung wie metrics-server registriert über ein APIService eine zusätzliche API-Gruppe, die anschließend über den regulären Kubernetes API Endpoint erreichbar ist.

Der Datenpfad lässt sich vereinfacht folgendermaßen darstellen:text Container │ ▼ kubelet │ ▼ metrics-server │ │ metrics.k8s.io ▼ API Aggregation Layer / kube-apiserver │ ├── kubectl top │ └── HorizontalPodAutoscaler

Für einen Client erscheinttext /apis/metrics.k8s.io/v1/…

damit als Bestandteil der Kubernetes API. Die Requests werden über die Aggregation Layer jedoch an den API Server weitergeleitet, der die entsprechende API-Gruppe implementiert.

Diese Architektur hat unmittelbare Konsequenzen für die Einführung von v1: Ein Upgrade des Kubernetes Control Plane auf 1.37 bedeutet nicht zwangsläufig, dass die im Cluster eingesetzte Metrics-Implementierung automatisch die Stable API bereitstellt.

Die API-Implementierung muss metrics.k8s.io/v1 selbst unterstützen und über ein entsprechendes APIService registrieren.

Ob dies der Fall ist, lässt sich über die API Discovery prüfen:bash kubectl get –raw /apis/metrics.k8s.io/ | jq .

Zusätzlich kann das registrierte APIService inspiziert werden:bash kubectl get apiservice v1.metrics.k8s.io

Gerade in Plattformen, in denen Control Plane, Cluster Add-ons und deren Lifecycle unabhängig voneinander verwaltet werden, sollte diese Trennung bei der Upgrade-Planung berücksichtigt werden.

Was sich zwischen v1beta1 und v1 tatsächlich ändert

Aus Sicht des API-Schemas fällt die Migration ungewöhnlich unspektakulär aus. Kubernetes 1.37 übernimmt die bestehenden Resource Types und Fields unverändert in v1.

Das bedeutet insbesondere, dass keine Anpassung der Verarbeitung von NodeMetrics oder PodMetrics erforderlich ist. Anwendungen, die die Metrics API direkt konsumieren, müssen primär die verwendete API-Version anpassen.

Bisher:text /apis/metrics.k8s.io/v1beta1/nodes

Neu:text /apis/metrics.k8s.io/v1/nodes

Dass keine Schemaänderung mit der Graduation verbunden ist, ist für Betreiber größerer Kubernetes-Landschaften relevant. Eine API-Graduation kann andernfalls Änderungen an Clients, Serialisierung, Typdefinitionen oder nachgelagerten Verarbeitungsschritten erforderlich machen. Bei metrics.k8s.io/v1 besteht diese Kopplung nicht.

Die Migration lässt sich deshalb von funktionalen Änderungen an der Metrics Pipeline trennen.

Stable bedeutet vor allem einen verlässlicheren API-Vertrag

Der wesentliche Unterschied zwischen v1beta1 und v1 liegt nicht in den übertragenen Daten, sondern in den Stabilitätszusagen des Kubernetes-Projekts.

Kubernetes APIs folgen expliziten Regeln für Kompatibilität, Deprecation und Removal. Mit einer Stable API können Entwickler und Plattformbetreiber wesentlich langfristiger davon ausgehen, dass bestehende Integrationen über Kubernetes-Releases hinweg erhalten bleiben.

Das ist insbesondere für Software relevant, die Kubernetes nicht nur über deklarative Ressourcen verwendet, sondern direkt mit der API interagiert: eigene Controller, Operatoren, Plattformdienste, Cluster-Management-Systeme oder andere Integrationen.

Bei solchen Komponenten ist eine API-Version Teil des technischen Vertrags zwischen Kubernetes und der darüberliegenden Plattform. Eine dauerhaft verwendete Beta API erzeugt deshalb langfristig eine unnötige Unsicherheit, selbst wenn sie faktisch über Jahre stabil geblieben ist.

Die Graduation beseitigt diese Diskrepanz.

v1beta1 verschwindet nicht mit Kubernetes 1.37

Die Einführung von v1 bedeutet nicht, dass bestehende Clients unmittelbar migriert werden müssen. v1beta1 bleibt während der Übergangsphase verfügbar.

Eine Metrics-Implementierung kann damit beide API-Versionen parallel anbieten:text metrics.k8s.io/v1 metrics.k8s.io/v1beta1

Das ermöglicht einen entkoppelten Upgrade-Prozess. Zunächst können Control Plane und Metrics-Implementierung aktualisiert werden, anschließend Clients und Integrationen.

Diese Übergangsphase ist insbesondere deshalb notwendig, weil innerhalb von Kubernetes 1.37 selbst noch nicht alle Consumer auf dieselbe Weise mit der neuen API-Version umgehen.

kubectl top bevorzugt bereits v1

kubectl unterstützt in Kubernetes 1.37 sowohl metrics.k8s.io/v1 als auch v1beta1.

Für kubectl top wird zunächst über API Discovery geprüft, ob die Stable API verfügbar ist. Ist dies der Fall, verwendet der Client v1. Andernfalls kann er weiterhin auf v1beta1 zurückfallen.

Damit ist beispielsweise ein Cluster möglich, dessen Control Plane bereits auf Kubernetes 1.37 aktualisiert wurde, dessen Metrics-Implementierung aber noch ausschließlich v1beta1 anbietet. Ebenso können neuere Metrics-Implementierungen beide Versionen parallel bereitstellen.

Für eigene Clients ist dieses Verhalten ein sinnvolles Migrationsmuster. Statt ausschließlich einen Endpoint fest zu konfigurieren, kann über Kubernetes API Discovery ermittelt werden, welche Versionen der API-Gruppe tatsächlich verfügbar sind. Ein Client kann anschließend v1 priorisieren und v1beta1 während der Übergangsphase als Fallback verwenden.

Das ist vor allem in Cluster-Flotten relevant, in denen unterschiedliche Kubernetes- und Add-on-Versionen gleichzeitig betrieben werden.

Der HorizontalPodAutoscaler benötigt in 1.37 weiterhin v1beta1

Eine für den Betrieb wesentlich wichtigere Einschränkung betrifft den HorizontalPodAutoscaler. Der HPA Controller verwendet in Kubernetes 1.37 weiterhin ausschließlich metrics.k8s.io/v1beta1.

Das unterscheidet ihn von kubectl top, das bereits zwischen den verfügbaren API-Versionen wählen kann.

Für Betreiber ergibt sich daraus eine klare Konsequenz: Wer Resource-Metrics-basiertes Autoscaling verwendet, sollte v1beta1 nach Einführung von v1 nicht aus der Metrics-API-Implementierung entfernen.

Ein typischer HPA kann beispielsweise CPU-Auslastung als Scaling-Signal verwenden:yaml 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

Der Controller benötigt dafür Resource Metrics der zugehörigen Pods. In Kubernetes 1.37 erfolgt diese Abfrage weiterhin über v1beta1.

Eine Metrics-Implementierung, die ausschließlichtext metrics.k8s.io/v1

bereitstellt, wäre damit zwar grundsätzlich auf dem aktuellen Stable API Level, würde aber den HPA Controller von Kubernetes 1.37 nicht vollständig bedienen.

Für die Übergangsphase ist daher die parallele Bereitstellung beider Versionen der sinnvolle Zustand:text metrics.k8s.io/v1 metrics.k8s.io/v1beta1

Erst wenn die entsprechenden Kubernetes-Komponenten selbst auf v1 migriert wurden, kann eine spätere Entfernung der Beta-Version sinnvoll bewertet werden.

Die Metrics API ist kein Ersatz für Prometheus

Die Bezeichnung „Metrics API“ führt gelegentlich zu falschen Erwartungen an ihren Funktionsumfang. metrics.k8s.io adressiert einen wesentlich engeren Anwendungsfall als klassische Monitoring- und Observability-Systeme.

Die API liefert aktuelle CPU- und Memory-Nutzung von Nodes und Pods. Sie stellt keine allgemeine Time-Series-Datenbank bereit, bietet keine langfristige Historisierung und ist nicht als universelle Schnittstelle für Application oder Business Metrics konzipiert.

Damit beantwortet sie eine andere Fragestellung als Prometheus, VictoriaMetrics, Mimir oder vergleichbare Systeme.

Ein HPA benötigt beispielsweise einen hinreichend aktuellen Resource-Usage-Wert, um die gewünschte Replica-Anzahl zu berechnen. Ein SRE benötigt dagegen für eine Performance-Analyse unter Umständen hochauflösende Zeitreihen über mehrere Wochen, zusätzliche Labels, Applikationsmetriken und Histogramme.

Beides sind Metriken, aber die Anforderungen an Erfassung, Speicherung und Abfrage unterscheiden sich fundamental.

Die Resource Metrics API sollte deshalb als Teil der Kubernetes-Steuerungsinfrastruktur verstanden werden, nicht als Observability-Plattform.

Resource Metrics, Custom Metrics und External Metrics

Auch im Kontext des Autoscalings ist metrics.k8s.io nur ein Teil der Kubernetes-Metrics-Landschaft.

Resource Metrics adressieren CPU und Memory. Viele Anwendungen benötigen für sinnvolles Autoscaling jedoch Signale, die näher an der tatsächlichen Last oder am Geschäftsprozess liegen, beispielsweise Request Rate, Queue Depth, Kafka Consumer Lag oder andere applikationsspezifische Messgrößen.

Für solche Fälle existieren unter anderem die Custom Metrics API und External Metrics:text metrics.k8s.io custom.metrics.k8s.io external.metrics.k8s.io

Die