Für Ingress-NGINX endet die Projektpflege im März 2026. Bestehende Deployments laufen weiter, doch das Projekt veröffentlicht danach keine neuen Releases, Fehlerkorrekturen oder Sicherheitsupdates. Bei einer neu entdeckten Schwachstelle bleiben damit nur eigene Korrekturen, vorgeschaltete Schutzmaßnahmen oder der Wechsel zu einem anderen Controller.
Eine Ingress-NGINX-Migration betrifft die Kubernetes-Manifeste, die externen Netzwerkendpunkte und das Verhalten des Controllers. Dieses Runbook führt von der Inventur über Paralleltests bis zum Cutover. Ein Rollback bleibt nur möglich, solange der alte Datenpfad vollständig erhalten ist; ein DNS-Wechsel allein stellt zwischengespeicherte Clients nicht sofort zurück.
Warum der Support für Ingress-NGINX endet
Das Support-Ende betrifft den von der Kubernetes-Community gepflegten Ingress-NGINX-Controller, nicht die stabile Kubernetes-Ingress-API. Vorhandene Ingress-Objekte verschwinden deshalb nicht aus dem Cluster. Kubernetes überträgt sie aber auch nicht automatisch auf eine andere Implementierung.
Künftige Cluster-Upgrades können sich nicht mehr auf Kompatibilitätskorrekturen des Controllers stützen. Sicherheitsfunde bleiben ebenfalls ungepatcht, sofern das Team keine eigene Korrektur entwickelt. Der Weiterbetrieb vergrößert deshalb mit der Zeit den Prüfaufwand für jede Kubernetes- oder Cloud-Änderung.
Vor der Inventur muss feststehen, wie Gateway API Zuständigkeiten und Routing anders abbildet.
Ingress und Gateway API: Was ändert sich?
Gateway API trennt die Bereitstellung des Datenpfads vom Routing der Anwendungen. Das Plattformteam verwaltet GatewayClass, Gateway, Listener und Adressen; Anwendungsteams pflegen HTTPRoute-Ressourcen. Die API leitet selbst keinen Traffic weiter: Dafür braucht der Cluster eine kompatible Gateway-Implementierung, deren unterstützte Funktionen vor der Migration geprüft werden müssen.
Ein Ingress verweist über Hostnamen und Pfade auf Kubernetes-Services. Die IngressClass bestimmt, welcher Controller diese Regeln verarbeitet. Der Kubernetes-Grundkurs behandelt die dafür benötigten Grundlagen zu Services, Controllern und deklarativen Ressourcen.
allowedRoutes begrenzt, aus welchen Namespaces Routen an einen Listener angehängt werden dürfen. Kubernetes-RBAC steuert den Zugriff auf die Ressourcen. ReferenceGrant autorisiert ausgewählte Verweise über Namespace-Grenzen hinweg.
| Funktion | Ingress-NGINX | Gateway API |
|---|---|---|
| Standard-Backend | spec.defaultBackend | Explizite HTTPRoute mit Catch-all-Match |
| TLS | spec.tls und Secret | HTTPS-Listener mit certificateRefs |
| Rewrites | rewrite-target-Annotation | URLRewrite-Filter oder Erweiterung |
| Reguläre Ausdrücke | use-regex und NGINX-Syntax | RegularExpression, sofern von der Implementierung unterstützt |
| Timeouts | Controller-spezifische Annotationen | HTTPRoute-Timeouts oder Policies der Implementierung |
| Header | Annotationen und ConfigMaps | RequestHeaderModifier und unterstützte Response-Filter |
| Zuständigkeit | Häufig gemeinsam verwalteter Controller | Gateway beim Plattformteam, HTTPRoute beim Anwendungsteam |
Diese Unterschiede legen fest, welche Ressourcen und Verhaltensweisen die Inventur erfassen muss.
Schritt 1: Ingress-NGINX vollständig inventarisieren
Die Bestandsaufnahme erfasst Ressourcen, Laufzeitkomponenten und externe Abhängigkeiten. Vier Gruppen gehören mindestens in das Inventar:
- Controller-Deployments oder DaemonSets einschließlich der zugehörigen Services
- Alle IngressClasses und Ingress-Ressourcen in sämtlichen Namespaces
- ConfigMaps, Admission-Webhooks und controller-spezifische Ressourcen
- Zertifikatsreferenzen, Secret-Metadaten und externe Netzwerkendpunkte
Die folgenden Exporte liefern einen reproduzierbaren Ausgangspunkt. Secret-Inhalte gehören nicht unverschlüsselt in das Arbeitsverzeichnis; der Export erfasst deshalb nur Namen und Typen:
kubectl get ingressclass -o yaml > 01-ingressclasses.yaml
kubectl get ingress -A -o yaml > 02-ingresses.yaml
kubectl get deploy,daemonset,service,configmap -A -o yaml > 03-runtime.yaml
kubectl get validatingwebhookconfiguration -o yaml > 04-admission.yaml
kubectl get secret -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,TYPE:.type' > 05-secret-index.txt- Hostnamen, Pfade und externe Load-Balancer-Endpunkte
- DNS-Ziele, aktuelle TTL-Werte und zuständige DNS-Zonen
- TLS-Zertifikate einschließlich Ablaufdatum und Secret-Referenz
- Annotationen, gruppiert nach Rewrites und Redirects, Authentifizierung und Sitzungen, Headern und Timeouts sowie Rate-Limits
- Abhängige Teams, Namespaces und Automatisierungsabläufe
Die Administration geteilter Cluster-Komponenten und die Fehlersuche am Netzwerkpfad sind Vertiefungsthemen im CKA- und CKS-Exam-Bundle.
Aus dem fertigen Inventar entstehen die Anforderungen an die neue Gateway-Implementierung.
Schritt 2: Anforderungen an Gateway API festlegen
Die installierte CRD-Version allein belegt keine Funktionsabdeckung. Der gewählte Controller muss jede im Inventar gefundene Funktion tatsächlich implementieren. Zu prüfen sind:
- HTTPRoute-Matches, Redirects und URL-Rewrites
- TLS-Terminierung, Zertifikatsreferenzen und Namespace-Grenzen
- Gewichtete Backend-Verteilung und Header-Filter
- Metriken, Traces und benötigte Policy-Ressourcen
Vor der Installation stehen die GatewayClass, die erlaubten Route-Namespaces und die RBAC-Regeln fest. Abnahmekriterien definieren erwartete Statuscodes, Backend-Zuordnungen, Fehlerquoten und Latenzgrenzen anhand des bisherigen Datenpfads. Weitere Schulungen zu Kubernetes-Netzwerken und Plattformbetrieb führt die Kategorie Cloud-Native-Trainings zusammen.
Mit diesen Kriterien lässt sich die Ausgabe von ingress2gateway prüfen, statt sie ungeändert zu übernehmen.
Schritt 3: Manifeste mit ingress2gateway vorübersetzen
Die Ausgabe von ingress2gateway ist ein Entwurf, kein freigegebenes Zielmanifest. Das Werkzeug liest vorhandene Ingress-Ressourcen und erzeugt daraus Gateway-API-Ressourcen, soweit der gewählte Provider die verwendeten Felder und Annotationen übersetzen kann.
ingress2gateway print --providers=ingress-nginx > generated-gateway.yamlDie generierte Datei gehört vor kubectl apply in die Versionsverwaltung. Das Review sucht gezielt nach:
- Nicht unterstützten Annotationen und ausgelassenen Funktionen
- Mehrdeutigen Pfaden oder veränderter Match-Priorität
- Fehlenden Standardwerten und Zertifikatsreferenzen
- Abweichungen von der bisherigen NGINX-Semantik
Alle offenen Markierungen wechseln anschließend in die manuelle Überarbeitung.
Schritt 4: Nicht übersetzbare Funktionen auflösen
HTTPRoute-Matches und Filter ersetzen viele NGINX-Annotationen durch strukturierte Felder. Reguläre Ausdrücke und Rewrite-Regeln benötigen Einzeltests, weil Syntax, Priorität und Ersetzung von der gewählten Gateway-Implementierung abhängen. Das frühere Standard-Backend wird als explizite Catch-all-Route modelliert.
Bei TLS prüft das Plattformteam den Listener-Hostnamen, certificateRefs und die Berechtigungen für das referenzierte Secret. Liegt das Secret in einem anderen Namespace, autorisiert ein ReferenceGrant im Namespace des Secrets den Zugriff. Dasselbe Prinzip gilt für Backend-Referenzen über Namespace-Grenzen.
Authentifizierung, Rate-Limits, Backend-Protokolle und einige Timeout-Varianten benötigen Policies oder Erweiterungen der Implementierung. Für jede Abweichung wird festgehalten, ob die Funktion erhalten, neu entworfen oder entfernt wird.
Erst nach diesen Entscheidungen sind die Manifeste für einen isolierten Parallelbetrieb bereit.
Schritt 5: Gateway API parallel betreiben
Der neue Controller verwendet seine GatewayClass, während das Test-Gateway einen separaten Load-Balancer-Endpunkt erhält. Der Produktions-DNS-Eintrag bleibt zunächst beim alten Controller. Temporäre DNS-Namen, lokale Host-Zuordnungen oder curl --resolve senden Testanfragen direkt an den neuen Endpunkt:
curl --resolve app.example.com:443:203.0.113.20 \
https://app.example.com/healthDie reservierte Beispieladresse muss durch die tatsächliche externe IP-Adresse des Test-Gateways ersetzt werden. Der Hostname bleibt unverändert, damit TLS-SNI, Zertifikatsauswahl und Host-Routing unter denselben Bedingungen wie in Produktion arbeiten.
Getrennte GatewayClass- und IngressClass-Zuordnungen verhindern konkurrierende Controller-Zugriffe und schaffen zwei vergleichbare Datenpfade für die Validierung.
Schritt 6: Routing, TLS und Fehlerfälle validieren
Die Testmatrix bildet jede produktive Route mit ihrem erwarteten Ergebnis ab. Sie enthält mindestens:
- Hostname, Pfad und HTTP-Methode
- Erwartete Redirects und Header-Änderungen
- Ziel-Backend, Statuscode und Antwortmerkmal
- 404-Antworten für unbekannte Routen
- Nicht erreichbare Backends und fehlerhafte Requests
- Zertifikatsauswahl und ungültige Zertifikatsketten
Die Auswertung vergleicht Statuscodes, Response-Header und Antwortkörper beider Datenpfade. Logs, Metriken und Traces zeigen falsche Backend-Zuordnungen, Timeouts oder fehlende Routen. Latenz und Fehlerquote werden mit der vor der Migration gemessenen Ausgangslage verglichen.
Aus den Testergebnissen entstehen verbindliche Freigabe- und Abbruchgrenzen für den Cutover.
Schritt 7: Cutover mit getestetem Rollback durchführen
Bei einem DNS-Wechsel reduziert das Team die TTL mindestens einen bisherigen TTL-Zeitraum vor dem Wartungsfenster. Bereits zwischengespeicherte Einträge können bis zum Ablauf dieses Zeitraums auf den alten Endpunkt zeigen. Das Change-Protokoll definiert Grenzwerte für HTTP-Fehler, TLS-Fehler und Latenz anhand der zuvor gemessenen Werte.
Muss ein Rollback innerhalb weniger Sekunden wirken, eignet sich ein rücksetzbarer Schalter vor beiden Endpunkten, etwa eine Load-Balancer-Konfiguration. DNS allein garantiert keine sofortige Rückkehr, weil Resolver und Clients Einträge zwischenspeichern. Der gewählte Mechanismus wird vor dem Cutover in beide Richtungen getestet.
Beide Controller bleiben während des Abnahmefensters aktiv und überwacht. Der alte Endpunkt behält seine Manifeste, Zertifikate und Netzwerkressourcen. Ein Rollback ändert nur den kontrollierenden Traffic-Endpunkt und verlangt keine Rekonstruktion gelöschter Ingress-Ressourcen.
Nach dem Abnahmefenster entscheidet die dokumentierte Checkliste über Freigabe oder Rollback.
Schritt 8: Migration abnehmen und Ingress-NGINX entfernen
Der alte Datenpfad bleibt bestehen, bis alle technischen Kriterien erfüllt und die Zuständigkeiten bestätigt sind. Erst danach beginnt der Rückbau.
Checkliste für die Migrationsabnahme
- Alle Controller, IngressClasses und Routen sind inventarisiert
- Annotationen, Zertifikate und externe Abhängigkeiten sind dokumentiert
- Generierte Manifeste und manuelle Änderungen wurden im Versionskontrollsystem geprüft
- Routing, TLS und Fehlerfälle erfüllen die Abnahmekriterien
- Logs, Metriken und Traces zeigen keine ungeklärten Abweichungen
- Der Rollback wurde ausgeführt und stellte den vorherigen Datenpfad innerhalb der festgelegten Zeit wieder her
- Neu entworfene Funktionen sind als akzeptierte Abweichungen dokumentiert
- Das Plattformteam und die zuständigen Anwendungsteams haben ausdrücklich freigegeben
Nach der Freigabe entfernt das Team alle Verweise auf den alten Controller. Der Rückbau folgt einer dokumentierten Reihenfolge:
- DNS-Einträge, Load-Balancer-Regeln und Automatisierungsabläufe aktualisieren
- Ingress-Ressourcen und controller-spezifische Konfigurationen entfernen
- Admission-Webhooks, Controller-Workloads und Services löschen
- Nicht mehr benötigte RBAC-Objekte und ConfigMaps entfernen
Die Cloud-Plattform wird anschließend auf verwaiste Load Balancer, externe IP-Adressen und Firewall-Regeln geprüft. Gemeinsam genutzte Secrets oder Zertifikate dürfen dabei nicht gelöscht werden. Migrationsprotokolle, Testergebnisse und finale Manifeste bleiben archiviert.
Der Rückbau beendet die Migration erst, nachdem der alte Datenpfad nicht mehr für einen Rollback benötigt wird.
Fazit: Parallelbetrieb gehört zum Migrationsdesign
Eine Ingress-NGINX-Migration ohne getrennten Parallelpfad ist fachlich nicht vertretbar, weil Unterschiede bei Annotationen, Route-Prioritäten und Fehlerantworten sonst bis zum Cutover unsichtbar bleiben. Beginne mit einem Export aller Ingress-Ressourcen und Annotationen, der als Anforderungsliste für die Gateway-Implementierung dient.