Migration von Ingress NGINX zur Gateway API auf Managed Kubernetes mit Cilium

Der Ingress NGINX Controller wird schrittweise abgelöst. Diese Anleitung beschreibt, wie Sie Schritt für Schritt auf die Gateway API in einem Managed-Kubernetes-Cluster mit Cilium migrieren, ohne die Verfügbarkeit Ihrer Workloads zu unterbrechen. Sie erfahren, wie TLS-Zertifikate verwaltet, ein sicherer DNS-Cutover durchgeführt und der LoadBalancer des Cloud-Anbieters für das neue Gateway konfiguriert wird. Der Migrationsansatz ermöglicht den parallelen Betrieb von Ingress und Gateway API, sodass Sie die Produktionsreife prüfen können, bevor der DNS-Traffic umgestellt wird.

Wenn Ihnen die Konzepte der Gateway API oder empfohlene Vorgehensweisen noch nicht vertraut sind, sollten Sie sich zunächst mit Gateway API in Verbindung mit Cilium sowie HTTPS-Traffic-Routing beschäftigen. Diese Grundlagen helfen dabei, das neue API-Modell, typische Konfigurationsmuster und die wichtigsten Unterschiede zum klassischen Ingress-Ansatz besser zu verstehen. Eine sorgfältige Planung und umfassende Tests sind entscheidend für eine reibungslose Migration.

Wichtig: Diese Anleitung wurde mit Managed Kubernetes Version 1.33.x getestet. Wenn Ihr Cluster eine ältere Version verwendet, sollten Sie ihn vor Beginn der Migration aktualisieren.

Wichtige Erkenntnisse

• Eine Migration von Ingress NGINX zur Gateway API auf Managed Kubernetes ist ohne Downtime möglich, wenn beide Controller parallel betrieben werden und der DNS-Cutover kontrolliert erfolgt.
• LoadBalancer-Endpunkte ändern sich. Die Gateway API erstellt einen neuen LoadBalancer mit einer neuen IP-Adresse. Planen Sie deshalb eine kurze Phase mit zwei LoadBalancern ein und ändern Sie DNS-Einträge erst, nachdem der Produktionstraffic erfolgreich validiert wurde.
• Annotationen müssen migriert werden. Ingress NGINX und Gateway API verwenden unterschiedliche Konfigurationsmodelle. Cloud-LoadBalancer-Annotationen gehören in Gateway-Ressourcen unter spec.infrastructure.annotations und nicht unter metadata.annotations.
• Zertifikate müssen explizit definiert werden. Statt Ingress-Annotationen zu nutzen, benötigt die Gateway API separate Certificate-Ressourcen. Der cert-manager Solver muss für die Gateway API und nicht für Ingress konfiguriert werden.
• HTTP-zu-HTTPS-Weiterleitungen werden über Filter umgesetzt. Die Gateway API verarbeitet keine NGINX-Redirect-Annotationen. Verwenden Sie dafür eine eigene HTTPRoute mit einem RequestRedirect-Filter.
• Testen Sie gründlich vor dem Cutover. Nutzen Sie die IP-Adresse des Gateway LoadBalancers, um die Einsatzbereitschaft zu prüfen, bevor DNS angepasst wird. Entfernen Sie Ingress erst, nachdem die Stabilität bestätigt wurde.
• Planen Sie vorübergehend doppelte Ressourcen ein. Während Test und Cutover laufen zwei LoadBalancer gleichzeitig. Berücksichtigen Sie dies in Ihrer Migrationsplanung.

Voraussetzungen

• VPC-integrierter Managed-Kubernetes-Cluster ab Version 1.33; prüfen Sie dies mit kubectl get gatewayclass cilium und bestätigen Sie ACCEPTED: True
• kubectl ist für Ihren Cluster konfiguriert
• Bestehendes Ingress-NGINX-Deployment mit cert-manager
• Domainname mit Zugriff auf die DNS-Verwaltung
• Optional: ExternalDNS ist im Namespace external-dns installiert
• Budget für den temporären Betrieb von zwei LoadBalancern während der Migration

Wichtige Migrationsaspekte

Änderungen an der LoadBalancer-IP

Das Gateway erstellt einen neuen Cloud-LoadBalancer mit einer neuen IP-Adresse.

Lösung: Betreiben Sie beide LoadBalancer parallel, stellen Sie DNS auf den neuen Gateway LoadBalancer um und entfernen Sie den alten Ingress LoadBalancer erst nach erfolgreicher Validierung.

Zuordnung der Annotationen

Cloud-LoadBalancer-Annotationen müssen unter spec.infrastructure.annotations eingetragen werden, nicht unter metadata.annotations. Dieser Fehler tritt häufig auf und kann verhindern, dass der LoadBalancer korrekt erstellt wird. Weitere Informationen zu Infrastruktur-Annotationen finden Sie in der Gateway-API-Dokumentation.

Zertifikatsverwaltung

• Erstellen Sie explizite Certificate-Ressourcen, anstatt einen annotationsbasierten Ansatz zu verwenden.
• Der ClusterIssuer muss den gatewayHTTPRoute-Solver verwenden und nicht den Ingress-Solver.

HTTP-zu-HTTPS-Weiterleitung

Die Gateway API benötigt eine separate HTTPRoute-Ressource mit einem RequestRedirect-Filter. Diese Weiterleitung wird direkt in der Route konfiguriert und nicht über eine Annotation.

Schritt-für-Schritt-Anleitung zur Migration

Verwenden Sie einen Blue-Green-Ansatz: Stellen Sie die Gateway API neben Ingress bereit, testen Sie über die Gateway-IP-Adresse, führen Sie den DNS-Cutover durch, überwachen Sie die Stabilität und bereinigen Sie anschließend die alte Umgebung. Beide Systeme laufen parallel, damit keine Downtime entsteht. Für gewöhnlich fallen für 24 bis 48 Stunden Kosten für zwei LoadBalancer an. Dieser Ansatz stellt sicher, dass die Gateway-Konfiguration geprüft werden kann, bevor Produktionstraffic umgeleitet wird.

Phase 1: Gateway-API-Stack vorbereiten

Schritt 1: Gateway API in cert-manager aktivieren

Damit cert-manager mit der Gateway API arbeiten kann, muss die Zertifikatsausstellung für Gateway-verwaltete Routen aktiviert werden. Der folgende Helm-Upgrade-Befehl aktualisiert die cert-manager-Installation mit dem erforderlichen Parameter:

helm upgrade cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --reuse-values \
  --set extraArgs="{--enable-gateway-api=true}"

Was dieser Befehl bewirkt:

• helm upgrade cert-manager jetstack/cert-manager: Aktualisiert oder installiert cert-manager über das Helm-Chart von Jetstack.
• --namespace cert-manager: Führt die Änderung im Namespace cert-manager aus.
• --reuse-values: Behält die vorhandene cert-manager-Konfiguration bei und ändert nur die neue Einstellung.
• --set extraArgs="{--enable-gateway-api=true}": Fügt ein Argument hinzu, damit cert-manager Gateway-API-Ressourcen zusätzlich zu klassischen Kubernetes-Ingress-Ressourcen erkennen und verwalten kann.

Fügen Sie diesen Parameter zusammen mit eventuell bereits vorhandenen extraArgs-Werten ein. Dieser Schritt ist erforderlich, damit cert-manager Zertifikate für HTTPS-Routen ausstellen kann, die über die Gateway API verwaltet werden.

Schritt 2: Gateway-Ressource erstellen

Das folgende Beispiel gateway.yaml zeigt, wie eine Kubernetes-Gateway-Ressource für die Gateway API definiert wird. Jeder Abschnitt erfüllt eine bestimmte Aufgabe:

• apiVersion, kind und metadata: Definieren die API-Gruppe, den Ressourcentyp und den Namen der Gateway-Ressource.
• spec.gatewayClassName: Gibt Kubernetes an, welche GatewayClass verwendet werden soll, in diesem Beispiel cilium.
• spec.infrastructure.annotations: Enthält Cloud-LoadBalancer-Annotationen. Sie konfigurieren Name, Größe und Health-Check-Pfad des entstehenden LoadBalancers in der Cloud-Umgebung. Diese Annotationen sollten aus der bisherigen NGINX-Ingress-Ressource übernommen werden.
• spec.listeners: Definiert, wie das Gateway eingehenden Netzwerkverkehr annimmt.
• Es werden zwei Listener eingerichtet: einer für HTTP auf Port 80 und einer für HTTPS auf Port 443. Beide verwenden den Hostnamen www.example.com.
• Der HTTPS-Listener enthält eine TLS-Konfiguration mit mode: Terminate. Dadurch entschlüsselt das Gateway eingehenden HTTPS-Traffic. Es verweist auf ein Kubernetes Secret namens www-tls, das das TLS-Zertifikat enthält.

Passen Sie Hostname, Annotationen und den Namen des referenzierten TLS-Secrets, beispielsweise www-tls, an Ihre Anwendungskonfiguration an.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: cilium
  infrastructure:
    annotations:
      # Copy cloud LoadBalancer annotations from your Ingress
      service.beta.kubernetes.io/cloud-loadbalancer-name: "gateway-api-lb"
      service.beta.kubernetes.io/cloud-loadbalancer-size-unit: "2"
      service.beta.kubernetes.io/cloud-loadbalancer-healthcheck-path: "/"
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "www.example.com"
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "www.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: www-tls

Dieses YAML erstellt eine neue Gateway-Ressource, die einen Cloud-LoadBalancer für HTTP- und HTTPS-Traffic bereitstellt. Dabei werden eigene Annotationen genutzt und das passende TLS-Zertifikat für sichere Verbindungen referenziert.

Wenden Sie die Ressource an und prüfen Sie das Ergebnis:

kubectl apply -f gateway.yaml
kubectl get gateway my-gateway  # Should show PROGRAMMED: True, ADDRESS assigned

Schritt 3: ClusterIssuer für automatische HTTPS-Zertifikate mit Gateway API erstellen

Dieser Schritt definiert einen ClusterIssuer für cert-manager, der den HTTPRoute-Solver der Gateway API verwendet. Der ClusterIssuer legt fest, wie cert-manager Let’s-Encrypt-Zertifikate für Domains anfordern und verwalten soll, die über die Gateway API statt über einen NGINX Ingress bereitgestellt werden.

Mit dem gatewayHTTPRoute-Solver werden HTTP-Validierungs-Challenges direkt über das Gateway verarbeitet. Dadurch können Zertifikate für Anwendungen und Routen, die von der Gateway API verwaltet werden, automatisch ausgestellt und erneuert werden.

So gehen Sie vor:

• Erstellen Sie eine Datei mit dem Namen cluster-issuer-gateway.yaml.
• Konfigurieren Sie darin eine ClusterIssuer-Ressource wie unten gezeigt.
• Ersetzen Sie email durch Ihre echte E-Mail-Adresse.
• Stellen Sie sicher, dass metadata.name eindeutig ist und nicht mit bestehenden ClusterIssuers kollidiert.
• Die parentRefs müssen mit Name und Namespace des zuvor erstellten Gateways übereinstimmen.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod-gateway
spec:
  acme:
    email: your-email@example.com   # <- Replace with your real email address
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod-gateway-key
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: my-gateway       # The Gateway name you defined earlier
                namespace: default     # The namespace of your Gateway
                kind: Gateway

Wenden Sie die ClusterIssuer-Ressource auf den Cluster an:

kubectl apply -f cluster-issuer-gateway.yaml

Nach dem Anwenden der Ressource kann cert-manager Zertifikate über HTTP-01-Challenges ausstellen und erneuern, die über das neue Gateway geroutet werden. Dadurch wird HTTPS für Workloads automatisiert, die über die Gateway API verwaltet werden.

Schritt 4: Vorhandenes TLS-Zertifikat kopieren

Kopieren Sie das TLS-Secret des Ingress, damit das Gateway es verwenden kann. Zu diesem Zeitpunkt zeigt DNS weiterhin auf Ingress, daher kann noch kein neues Zertifikat ausgestellt werden. Dieser Schritt ermöglicht es dem Gateway, vorübergehend das bestehende Zertifikat zu nutzen.

Ermitteln Sie zuerst den Namen des TLS-Secrets, das vom Ingress verwendet wird:

kubectl get ingress <your-ingress-name> -o jsonpath='{.spec.tls[0].secretName}'

Der Name des Gateway-TLS-Secrets muss mit dem Wert übereinstimmen, der in der Gateway-Ressource unter spec.listeners[].tls.certificateRefs[].name angegeben ist, zum Beispiel www-tls aus Schritt 2.

Kopieren Sie das Secret:

INGRESS_TLS_SECRET=<your-ingress-tls-secret>  # From the command above
GATEWAY_TLS_SECRET=www-tls  # Must match Gateway spec.listeners[].tls.certificateRefs[].name

kubectl get secret $INGRESS_TLS_SECRET -o yaml | \
  sed "s/name: $INGRESS_TLS_SECRET/name: $GATEWAY_TLS_SECRET/" | \
  sed '/uid:/d' | sed '/resourceVersion:/d' | sed '/creationTimestamp:/d' | \
  kubectl apply -f -

Prüfen Sie das Secret:

kubectl get secret $GATEWAY_TLS_SECRET  # Should show kubernetes.io/tls type

Erstellen Sie nach dem DNS-Cutover in Phase 4 eine Certificate-Ressource, damit cert-manager das Zertifikat korrekt verwalten und erneuern kann. Ohne diese Ressource läuft das Zertifikat nach 90 Tagen ab und wird nicht automatisch verlängert.

Schritt 5: HTTPRoute für HTTPS-Traffic erstellen

Das folgende Beispiel httproute.yaml zeigt, wie eine Kubernetes-HTTPRoute-Ressource für die Gateway API definiert wird. Jeder Abschnitt hat eine eigene Aufgabe:

• apiVersion, kind und metadata: Definieren die API-Gruppe, den Ressourcentyp und den Ressourcennamen www-https.
• metadata.annotations: Fügt ExternalDNS-Annotationen für Hostname und TTL hinzu. Diese Angaben sind optional, aber hilfreich, um die DNS-Propagation nachzuverfolgen.
• spec.parentRefs: Verweist auf die Gateway-Ressource my-gateway und nutzt den Abschnittsnamen https, damit die Route zum passenden Gateway-Listener gehört.
• spec.hostnames: Listet die Hostnamen auf, auf die diese Route reagiert, hier www.example.com.
• spec.rules: Definiert die Routing-Regeln der HTTPRoute.
• matches: Definiert den Pfadpräfix / für eingehende Anfragen.
• backendRefs: Verweist auf den Backend-Service my-www-service und den Port 80, an den Traffic weitergeleitet werden soll.

Erstellen Sie httproute.yaml und passen Sie Hostname und Backend-Service an:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: www-https
  annotations:
    # Add if using ExternalDNS
    external-dns.alpha.kubernetes.io/hostname: www.example.com
    external-dns.alpha.kubernetes.io/ttl: "300"
spec:
  parentRefs:
  - name: my-gateway
    sectionName: https
  hostnames:
  - www.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: my-www-service
      port: 80

kubectl apply -f httproute.yaml

Schritt 6: HTTP-zu-HTTPS-Weiterleitung erstellen

Der folgende Codeblock definiert eine Kubernetes-HTTPRoute-Ressource, die HTTP-Traffic für die Domain auf HTTPS weiterleitet. Jeder Abschnitt erfüllt eine bestimmte Funktion:

• apiVersion, kind und metadata: Definieren eine HTTPRoute mit dem Namen http-redirect.
• spec.parentRefs: Verbindet diese Route mit der Gateway-Ressource my-gateway und ordnet sie dem Listener http zu, der üblicherweise auf Port 80 lauscht.
• spec.hostnames: Gilt für Traffic an www.example.com.
• spec.rules: Fügt eine Regel mit einem RequestRedirect-Filter hinzu. Dieser Filter weist das Gateway an, passende HTTP-Anfragen durch scheme: https auf HTTPS weiterzuleiten. Der Wert statusCode: 301 erzeugt eine dauerhafte Weiterleitung.

Diese Ressource sorgt dafür, dass das Gateway alle HTTP-Anfragen für die Domain abfängt und an den sicheren HTTPS-Endpunkt weiterleitet. Dadurch wird die Sicherheit verbessert und ein konsistenter Zugriff über TLS sichergestellt.

Hier ist das YAML-Manifest für die Redirect-Route:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-redirect
spec:
  parentRefs:
  - name: my-gateway
    sectionName: http
  hostnames:
  - www.example.com
  rules:
  - filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301

Wenden Sie die Weiterleitung mit diesem Befehl an:

kubectl apply -f http-redirect.yaml

Schritt 7: Prüfen, ob die HTTPRoutes verbunden sind

kubectl get httproute  # Should show both www-https and http-redirect
kubectl get gateway my-gateway  # Should show PROGRAMMED: True
kubectl describe httproute www-https
kubectl describe httproute http-redirect

Prüfen Sie in der Ausgabe von describe unter Status.Parents.Conditions folgende Werte:

• Type: Accepted mit Status: True
• Type: ResolvedRefs mit Status: True

Häufige Probleme:

• ResolvedRefs zeigt Status: False: Prüfen Sie, ob der Backend-Service existiert und ob der Port korrekt ist.
• Accepted zeigt Status: False: Stellen Sie sicher, dass sectionName und Hostnamen zu den Gateway-Listenern passen.

Phase 2: Gateway-Stack validieren

Testen Sie über die IP-Adresse, bevor Sie DNS ändern:

GATEWAY_IP=$(kubectl get gateway my-gateway -o jsonpath='{.status.addresses[0].value}')

# Test HTTP redirect (expect 301 to HTTPS, server: envoy)
curl -I --resolve www.example.com:80:$GATEWAY_IP http://www.example.com

# Test HTTPS traffic (expect 200, server: envoy)
curl -k -I --resolve www.example.com:443:$GATEWAY_IP https://www.example.com

# Verify content
curl -k --resolve www.example.com:443:$GATEWAY_IP https://www.example.com

Stellen Sie sicher, dass alle Tests die erwarteten Ergebnisse liefern, bevor Sie fortfahren.

Phase 3: DNS-Cutover durchführen

Nutzen Sie den Abschnitt, der zu Ihrer DNS-Verwaltung passt: manuell oder über ExternalDNS.

Manuelle DNS-Aktualisierung

# Optional: Lower TTL for faster rollback
cloudctl compute domain records update example.com --record-id <a-record-id> --record-ttl 60
sleep 300  # Wait for old TTL to expire

# Update A record to Gateway IP
cloudctl compute domain records update example.com --record-id <a-record-id> --record-data "$GATEWAY_IP"

# Monitor DNS propagation (Ctrl+C to stop)
while true; do echo "$(date): $(dig +short www.example.com)"; sleep 5; done

ExternalDNS mit TXT-Ownership-Transfer

Stellen Sie eine zweite ExternalDNS-Instanz für die Gateway API bereit und passen Sie secretKeyRef bei Bedarf an:

helm install external-dns-gateway external-dns/external-dns \
  --namespace external-dns \
  --set provider=cloud-provider \
  --set sources[0]=gateway-httproute \
  --set txtOwnerId=gateway \
  --set interval=1m \
  --set env[0].name=CLOUD_PROVIDER_TOKEN \
  --set env[0].valueFrom.secretKeyRef.name=external-dns \
  --set env[0].valueFrom.secretKeyRef.key=token

Übertragen Sie die TXT-Ownership, um den DNS-Cutover auszulösen. Ersetzen Sie die Beispieldomains in diesen Befehlen durch die Domain, die bei Ihrem DNS-Anbieter verwaltet wird.

# Find TXT record. Replace update pattern to find your record: a-<hostname>
TXT_RECORD_ID=$(cloudctl compute domain records list example.com --format ID,Type,Name --no-header | grep "TXT.*a-<hostname>" | awk '{print $1}')

# Validate TXT_RECORD_ID has a value
echo $TXT_RECORD_ID

# Transfer ownership from default to gateway
cloudctl compute domain records update example.com \
  --record-id $TXT_RECORD_ID \
  --record-data "heritage=external-dns,external-dns/owner=gateway,external-dns/resource=gateway/default/my-gateway"

Überwachen Sie den Cutover und beenden Sie den Befehl bei Bedarf mit Strg+C:

while true; do echo "$(date): $(dig +short www.example.com)"; sleep 5; done

Sobald die IP auf die Gateway-IP umgestellt wurde, prüfen Sie das Ergebnis:

curl -I https://www.example.com  # Should return 200, server: envoy

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: www-tls-gateway
spec:
  secretName: www-tls
  issuerRef:
    name: letsencrypt-prod-gateway
    kind: ClusterIssuer
  dnsNames:
  - www.example.com

kubectl apply -f certificate.yaml
kubectl get certificate www-tls-gateway -w  # Wait for READY: True

Ohne diese Certificate-Ressource schlägt die Zertifikatserneuerung nach 90 Tagen fehl. Die Certificate-Ressource weist cert-manager an, das Zertifikat vor Ablauf automatisch über den ClusterIssuer zu erneuern, der in Phase 1, Schritt 3 erstellt wurde.

Schritt 2: Stabilität überwachen

Überwachen Sie die Umgebung 24 bis 48 Stunden, bevor Sie Ingress entfernen. Beobachten Sie Traffic-Volumen, den READY-Status des Zertifikats, Fehlerraten und Antwortzeiten. Dieser Überwachungszeitraum bestätigt, dass das Gateway Produktionstraffic korrekt verarbeitet, bevor die alte Ingress-Umgebung als Sicherheitsnetz entfernt wird.

Schritt 3: Bereinigung

Bestätigen Sie vor der Bereinigung, dass die Zertifikatsverwaltung funktioniert:

kubectl get certificate www-tls-gateway  # Must show READY = True
# Must show letsencrypt-prod-gateway or the name of the ClusterIssuer you created in Phase 1 Step 3
kubectl get certificate www-tls-gateway -o jsonpath='{.spec.issuerRef.name}'

Führen Sie die Bereinigung durch:

helm uninstall external-dns -n external-dns  # If using ExternalDNS
helm uninstall ingress-nginx -n ingress-nginx
kubectl delete namespace ingress-nginx

Prüfen Sie den finalen Zustand:

curl -I https://www.example.com  # Should return 200, server: envoy
cloudctl compute load-balancer list --format ID,Region,Name,IP  # Should show only Gateway LoadBalancer

Rollback-Verfahren

Ein Rollback ist sinnvoll, wenn das Gateway nicht erreichbar ist, Zertifikatsprobleme auftreten, Fehlerraten deutlich steigen oder kritische Funktionslücken festgestellt werden. Der Rollback ist schnell möglich, üblicherweise innerhalb von 2 bis 6 Minuten, da die Ingress-NGINX-Umgebung während der Überwachungsphase bestehen bleibt.

ExternalDNS-Rollback

Dieser Befehl aktualisiert den von ExternalDNS verwalteten TXT-Eintrag für die Domain example.com, um DNS-Ownership und Traffic-Routing zurück zum Ingress-NGINX-Controller zu verschieben. Dabei wird über die CLI des Cloud-Anbieters der TXT-Record so gesetzt, dass er wieder auf die ursprüngliche Ingress-Ressource verweist. Dadurch aktualisiert ExternalDNS den A-Record der Domain zurück auf die alte Ingress-LoadBalancer-IP.

cloudctl compute domain records update example.com \
  --record-id $TXT_RECORD_ID \
  --record-data "heritage=external-dns,external-dns/owner=default,external-dns/resource=ingress/default/sample-nginx"
# Wait ~60s for DNS update

Manueller DNS-Rollback

INGRESS_IP=$(kubectl get svc -n ingress-nginx ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
cloudctl compute domain records update example.com --record-id <a-record-id> --record-data "$INGRESS_IP"
# Wait for DNS propagation (~60-300s)

Validieren Sie den Rollback mit dig +short www.example.com. Die Ausgabe sollte die Ingress-IP anzeigen. Die gesamte Rollback-Dauer liegt in der Regel bei 2 bis 6 Minuten.

Häufig gestellte Fragen

Können Ingress NGINX und Gateway API während der Migration gleichzeitig betrieben werden?

Ja. Dies ist die empfohlene Methode für eine Migration ohne Downtime. Beide Systeme können parallel laufen. Die Gateway API erstellt einen neuen Cloud-LoadBalancer mit eigener IP-Adresse, sodass die Gateway-Konfiguration getestet werden kann, bevor DNS geändert wird. Nachdem das Gateway erfolgreich validiert wurde, wird DNS auf die neue LoadBalancer-IP umgestellt. Die alte Ingress-NGINX-Umgebung wird erst entfernt, nachdem die Stabilität überwacht und bestätigt wurde.

Was passiert mit vorhandenen TLS-Zertifikaten während der Migration?

Vorhandene TLS-Zertifikate, die von Ingress NGINX verwendet werden, können zunächst zur Gateway API kopiert werden. In Phase 1, Schritt 4, wird das TLS-Secret von Ingress zum Gateway übertragen. Nach dem DNS-Cutover muss jedoch eine explizite Certificate-Ressource erstellt werden, wie in Phase 4, Schritt 1 gezeigt. Nur so kann cert-manager das Zertifikat korrekt verwalten und automatisch erneuern. Ohne diese Certificate-Ressource läuft das Zertifikat nach 90 Tagen ab und wird nicht automatisch verlängert.

Warum wird ein separater ClusterIssuer für die Gateway API benötigt?

Die Gateway API verwendet einen anderen Zertifikats-Challenge-Solver als Ingress. Ingress nutzt den Ingress-Solver, während die Gateway API den gatewayHTTPRoute-Solver verwendet. Deshalb muss ein neuer ClusterIssuer mit einer gatewayHTTPRoute-Konfiguration erstellt werden, die auf die Gateway-Ressource verweist. Außerdem muss cert-manager mit dem Flag --enable-gateway-api=true gestartet werden, damit die Unterstützung für die Gateway API aktiv ist.

Wie lange dauert die Migration?

Die technische Migration kann innerhalb weniger Stunden abgeschlossen werden. Dennoch sollte vor dem Entfernen der alten Ingress-NGINX-Umgebung eine Überwachungsphase von 24 bis 48 Stunden eingeplant werden. Die tatsächliche Cutover-Zeit hängt von der DNS-Propagation ab, die nach einer DNS-Änderung typischerweise 60 bis 300 Sekunden dauert. Die Phase mit zwei parallel betriebenen LoadBalancern, in der beide Ressourcen berechnet werden, dauert meist 24 bis 48 Stunden, während die Stabilität überprüft wird.

Was passiert, wenn nach der Migration ein Rollback erforderlich ist?

Der Rollback ist unkompliziert. Wenn ExternalDNS verwendet wird, wird die TXT-Ownership zurück auf den ursprünglichen Ingress übertragen. Bei manueller DNS-Verwaltung wird der A-Record wieder auf die Ingress-LoadBalancer-IP gesetzt. Der Rollback dauert in der Regel insgesamt 2 bis 6 Minuten, abhängig von der DNS-Propagation. Da die Ingress-NGINX-Umgebung während der Überwachungsphase aktiv bleibt, ist die Rückkehr zum vorherigen Setup bei Bedarf einfach möglich.

Fazit

Die Migration von Ingress NGINX zur Gateway API auf Managed Kubernetes kann ohne Downtime umgesetzt werden. Das Gateway nutzt den integrierten Controller von Cilium und bietet modernes, erweiterbares Traffic-Management mit expliziter Konfiguration und erweiterten Routing-Möglichkeiten. Die Gateway API ermöglicht außerdem eine klarere Trennung von Verantwortlichkeiten, rollenbasierte Zugriffskontrolle und ausdrucksstärkere Routing-Optionen als die klassische Ingress API.