Kubernetes API Versioning: Versionierung und Kompatibilitaet fuer Microservices [2026]

TL;DR

• URL Path Versioning (z.B. /api/v1, /api/v2) ist der Standard fuer oeffentliche APIs -- klar, einfach zu routen, aber fuehrt langfristig zu Versions-Wildwuchs.
• Header-based Versioning haelt URLs sauber und erlaubt feinere Kontrolle, erfordert aber bewusste Client-Konfiguration und erschwert Caching.
• Die Kubernetes API Deprecation Policy gibt mindestens 12 Monate oder 3 Minor-Releases Vorlaufzeit bevor eine API-Version entfernt wird -- das Modell ist der Goldstandard fuer eigene APIs.
• Backward Compatibility erfordert eine klare Strategie: Additive Changes sind immer sicher, Breaking Changes brauchen eine neue Major-Version.
• In Kubernetes-Umgebungen steuern Ingress Rules und Service Mesh Routing die API-Versionierung auf Infrastruktur-Ebene.

API Versioning: Warum es in Microservices unverzichtbar ist

In einem Monolithen aendern Sie die API und deployen. Alle Clients nutzen automatisch die neue Version. In einer Microservices-Architektur ist das anders: Service A ruft Service B mit einem bestimmten API-Vertrag auf. Wenn Service B seine API aendert, ohne Rueckwaertskompatibilitaet zu wahren, bricht Service A.

Das Problem verschaerft sich in Kubernetes-Umgebungen, wo Services unabhaengig voneinander deployed werden. Service B kann jederzeit ein neues Release mit geaenderter API ausrollen -- ohne dass Service A davon weiss.

API Versioning ist die Loesung: Jede API-Aenderung wird explizit versioniert, alte Versionen bleiben verfuegbar, und Clients migrieren in ihrem eigenen Tempo.

Strategie 1: URL Path Versioning

Die weitverbreitetste Strategie. Die Version ist Teil der URL und damit sofort sichtbar.

Routing mit Kubernetes Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: order-api-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  ingressClassName: nginx
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /v1/orders(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: order-service-v1
                port:
                  number: 8080
          - path: /v2/orders(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: order-service-v2
                port:
                  number: 8080

Separate Deployments pro API-Version

# API v1 -- Legacy, im Maintenance-Modus
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service-v1
  namespace: production
  labels:
    app: order-service
    version: v1
spec:
  replicas: 2
  selector:
    matchLabels:
      app: order-service
      version: v1
  template:
    metadata:
      labels:
        app: order-service
        version: v1
    spec:
      containers:
        - name: order-service
          image: registry.example.com/order-service:1.9.3
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 500m
              memory: 512Mi
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            periodSeconds: 5
---
# API v2 -- Aktuelle Version
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service-v2
  namespace: production
  labels:
    app: order-service
    version: v2
spec:
  replicas: 5
  selector:
    matchLabels:
      app: order-service
      version: v2
  template:
    metadata:
      labels:
        app: order-service
        version: v2
    spec:
      containers:
        - name: order-service
          image: registry.example.com/order-service:2.3.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: "1"
              memory: 1Gi
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            periodSeconds: 5

Fuer Health Check Konfigurationen lesen Sie Kubernetes Health Checks: Liveness, Readiness und Startup Probes.

Vor- und Nachteile

Strategie 2: Header-based Versioning

Die Version wird im HTTP-Header mitgesendet. Die URL bleibt identisch, ein Router entscheidet basierend auf dem Header.

Routing mit Istio VirtualService

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: order-api-vs
  namespace: production
spec:
  hosts:
    - api.example.com
  http:
    # Header-basiertes Routing: Accept-Version Header
    - match:
        - headers:
            Accept-Version:
              exact: "v2"
      route:
        - destination:
            host: order-service-v2
            port:
              number: 8080
    - match:
        - headers:
            Accept-Version:
              exact: "v1"
      route:
        - destination:
            host: order-service-v1
            port:
              number: 8080
    # Default: Aktuelle Version
    - route:
        - destination:
            host: order-service-v2
            port:
              number: 8080

Client-seitiger Aufruf

# Explizit v1 aufrufen
curl -H "Accept-Version: v2" https://api.example.com/orders

# Ohne Header: Default-Version (v2)
curl https://api.example.com/orders

Vorteil: URLs bleiben stabil. Bookmarks und Dokumentation funktionieren auch nach Version-Upgrades. Nachteil: Clients muessen den Header aktiv setzen. Vergessene Header fuehren zu unerwarteten Ergebnissen.

Kubernetes API Deprecation Policy als Vorbild

Die Kubernetes API Deprecation Policy ist einer der ausgereiftesten Prozesse fuer API-Versionierung. Sie definiert klare Regeln, die als Vorbild fuer eigene APIs dienen koennen.

Kubernetes API Lifecycle

Deprecation-Regeln

1. GA APIs: Muessen mindestens 12 Monate oder 3 Minor-Releases nach Deprecation verfuegbar bleiben
2. Beta APIs: Muessen mindestens 9 Monate oder 3 Minor-Releases nach Deprecation verfuegbar bleiben
3. Alpha APIs: Koennen jederzeit ohne Vorwarnung entfernt werden
4. Eine API-Version darf erst deprecated werden, wenn eine gleichwertige oder bessere Nachfolge-Version GA ist

Kubernetes API Deprecation pruefen

# Deprecated APIs in Ihrem Cluster finden
kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis

# Alle API-Versionen auflisten
kubectl api-versions

# API-Ressourcen mit bevorzugter Version anzeigen
kubectl api-resources --sort-by=name

Migration mit kubectl convert

# Manifest von alter API-Version in neue konvertieren
kubectl convert -f old-deployment.yaml --output-version apps/v1

# Alle Manifeste in einem Verzeichnis konvertieren
kubectl convert -f ./manifests/ --output-version apps/v1 -o yaml

Eigene Deprecation Policy fuer Microservices

Basierend auf der Kubernetes-Policy empfehlen wir folgende Regeln fuer interne APIs:

Deprecation-Lifecycle implementieren

# ConfigMap mit API-Lifecycle-Konfiguration
apiVersion: v1
kind: ConfigMap
metadata:
  name: api-lifecycle-config
  namespace: production
data:
  lifecycle.yaml: |
    apis:
      order-service:
        versions:
          v1:
            status: deprecated
            deprecated_since: "2025-09-01"
            sunset_date: "2026-03-01"
            migration_guide: "https://docs.internal/order-api-v2-migration"
          v2:
            status: stable
            released: "2025-09-01"
          v3:
            status: alpha
            released: "2026-01-15"

Deprecation-Header in Responses

Clients muessen ueber bevorstehende Aenderungen informiert werden. Drei Standard-HTTP-Header sind dafuer relevant:

• Deprecation: true -- signalisiert, dass die API-Version veraltet ist
• Sunset: Sat, 01 Mar 2026 00:00:00 GMT -- das Datum, ab dem die API entfernt wird
• Link mit rel="successor-version" -- verweist auf die Migrations-Dokumentation

Diese Header koennen ueber Istio EnvoyFilter oder direkt in der Anwendung gesetzt werden.

Backward Compatibility: Regeln fuer sichere API-Aenderungen

Sichere Aenderungen (kein neues Major-Version noetig)

• Neue optionale Felder hinzufuegen
• Neue Endpoints hinzufuegen
• Neue optionale Query-Parameter hinzufuegen
• Neue Response-Felder hinzufuegen (wenn Clients unbekannte Felder ignorieren)
• Enum-Werte hinzufuegen (wenn Clients unbekannte Werte tolerieren)

Breaking Changes (neue Major-Version noetig)

• Felder entfernen oder umbenennen
• Datentypen aendern (String zu Integer)
• Pflichtfelder hinzufuegen
• Response-Struktur aendern
• HTTP-Methoden aendern
• Fehler-Codes aendern
• Semantik bestehender Felder aendern

Versionierung in der Deployment-Pipeline

Neue API-Versionen sollten immer als Canary deployed werden: Eine einzelne Replica der neuen Version erhaelt einen kleinen Prozentsatz des Traffics. Erst nach erfolgreicher Validierung wird die neue Version voll ausgerollt.

Fuer detaillierte Deployment-Strategien wie Canary und Blue-Green lesen Sie Kubernetes Deployment Strategien.

Monitoring: API-Versionen ueberwachen

Wichtige Metriken pro API-Version

Drei Metriken sind entscheidend fuer das API-Version-Monitoring:

1. Traffic-Verteilung: Wie viel Prozent des Traffics nutzt welche Version? Wenn die deprecated Version noch ueber 50% hat, ist die Migration nicht auf Kurs.
2. Error-Rate pro Version: Hat die neue Version eine hoehere Fehlerrate? Dann muss der Rollout gestoppt werden.
3. Sunset-Countdown: Wie viele Tage bis zum Sunset-Datum? Alerts bei 30 und 7 Tagen geben Teams genug Vorlaufzeit.

Nutzen Sie Prometheus Labels wie api_version="v1" auf http_requests_total, um diese Metriken sauber zu tracken. Details zum Monitoring-Setup finden Sie in Kubernetes Performance Probleme identifizieren und loesen.

Entscheidungsmatrix: Welche Strategie passt?

Fuer Skalierungs-Aspekte bei Multi-Version-Deployments lesen Sie Kubernetes Scalability Patterns.

Verwandte Artikel

• Kubernetes Health Checks: Liveness, Readiness und Startup Probes
• Kubernetes Deployment Strategien
• Kubernetes Scalability Patterns
• Kubernetes Performance Probleme identifizieren und loesen
• Kubernetes Taints und Tolerations

Fazit

API Versioning ist in Microservices-Architekturen auf Kubernetes nicht optional. Ohne klare Versionierung fuehrt jede API-Aenderung zu potentiellen Ausfaellen. Die Kubernetes API Deprecation Policy ist ein hervorragendes Vorbild: klare Lifecycle-Phasen, definierte Mindest-Vorlaufzeiten, und automatische Warnungen an Clients.

Fuer die meisten Teams ist URL Path Versioning der pragmatische Einstieg: einfach zu implementieren, einfach zu debuggen, und mit Standard-Kubernetes-Ingress routbar. Header-based Versioning eignet sich fuer interne APIs in Service-Mesh-Umgebungen.

Unabhaengig von der Strategie: Definieren Sie eine Deprecation Policy, implementieren Sie Sunset-Header, monitoren Sie die Traffic-Verteilung nach Version, und geben Sie Teams mindestens 3 Monate Vorlaufzeit vor dem Entfernen einer Version.

Falls Sie Unterstuetzung bei der API-Strategie fuer Ihre Kubernetes-Umgebung brauchen, stehen wir unter /kontakt fuer ein Beratungsgespraech zur Verfuegung.