Comment migrer d'Ingress NGINX vers Gateway API avant la fin de support

Ce tutoriel est pour les équipes utilisant le contrôleur ingress-nginx communautaire et ayant besoin d’un chemin de migration pratique avant de se retrouver coincées avec une infrastructure edge non supportée. La partie urgente n’est pas l’API Kubernetes Ingress elle-même. La partie urgente est que de nombreux clusters s’appuient sur un comportement spécifique au contrôleur ingress-nginx, et ces comportements ne se traduisent pas proprement juste en changeant un manifeste.

Ce qui rend cette migration délicate est que Ingress et Gateway API modélisent le problème différemment. Avec Ingress, beaucoup de comportements avancés sont empaquetés dans des annotations sur un seul objet. Avec Gateway API, les points d’entrée, TLS et le routage sont répartis sur plusieurs ressources et souvent à travers différents personas. C’est un meilleur modèle à long terme, mais cela signifie que la migration est en partie traduction, en partie nettoyage et en partie re-conception du comportement.

À la fin de ce tutoriel, vous aurez un workflow de migration reproductible : auditer ce qu’ingress-nginx fait réellement aujourd’hui, installer Gateway API en toute sécurité, traduire un ingress de bout en bout, exécuter les deux chemins côte à côte, migrer les cas avancés intentionnellement et basculer le trafic avec le rollback prêt. Pour un contexte plus large sur le calendrier de fin de support et ce que cela signifie pour vos clusters, consultez Ingress NGINX Retirement: What It Means and How to Migrate.

Étape 1 : Auditer l’utilisation actuelle d’ingress

Ne commencez pas par convertir du YAML. Commencez par découvrir ce que votre cluster utilise réellement. Les migrations les plus dangereuses sont celles où les équipes supposent qu’elles n’utilisent que le routage host/path et TLS, puis découvrent tard que l’auth, les réécritures ou les défauts spécifiques au contrôleur étaient critiques. Le guide de migration de Gateway API prévient que les fonctionnalités Ingress spécifiques à l’implémentation sont la partie qui nécessite le plus de travail manuel, et les recommandations de migration ingress-nginx de Kubernetes appellent spécifiquement l’attention sur les défauts cachés et effets de bord qui peuvent causer des pannes si vous traduisez trop littéralement.

Exporter l’état ingress actuel

Lancez d’abord un export au niveau cluster.

kubectl get ingress -A -o yaml > ingress-all.yaml
kubectl get ingressclass -A -o yaml > ingressclass-all.yaml
kubectl get secret -A -o yaml > secrets-all.yaml
kubectl get configmap -A -o yaml | grep -A 40 -B 10 ingress-nginx
kubectl get pods -A -l app.kubernetes.io/name=ingress-nginx -o wide

Cette dernière commande est utile parce que Kubernetes la recommande explicitement comme un moyen rapide de déterminer si vous dépendez d’ingress-nginx.

Inventorier les hosts, chemins et TLS

Créez un fichier d’inventaire de migration qui capture le comportement, pas seulement les objets.

Fichier : ingress-migration-inventory.csv

namespace,ingress_name,host,path,path_type,tls_secret,service,service_port,ingress_class,notes
payments,payments-web,payments.example.com,/,Prefix,payments-tls,payments-web,8080,nginx,standard http app
identity,oauth-gateway,login.example.com,/oauth,Prefix,identity-tls,oauth-proxy,4180,nginx,auth headers and redirects
api,customer-api,api.example.com,/v1,Prefix,api-tls,customer-api,9000,nginx,rewrite and rate limiting
marketing,landing,www.example.com,/,Prefix,public-tls,landing,80,nginx,static content and redirect rules

Inventorier les annotations et comportements spécifiques au contrôleur

Maintenant extrayez les annotations parce que c’est là que la plupart de la douleur de migration vit.

kubectl get ingress -A -o jsonpath='{range .items[*]}{.metadata.namespace},{.metadata.name},{.metadata.annotations}{"\n"}{end}' > ingress-annotations.txt

Cherchez spécifiquement des patterns comme :

• nginx.ingress.kubernetes.io/rewrite-target
• nginx.ingress.kubernetes.io/use-regex
• nginx.ingress.kubernetes.io/auth-url
• nginx.ingress.kubernetes.io/auth-signin
• nginx.ingress.kubernetes.io/configuration-snippet
• nginx.ingress.kubernetes.io/server-snippet
• nginx.ingress.kubernetes.io/limit-rps
• nginx.ingress.kubernetes.io/canary
• nginx.ingress.kubernetes.io/upstream-vhost

Ceux-ci ne sont pas tous équivalents dans Gateway API. Certains se mappent proprement aux fonctionnalités HTTPRoute. D’autres nécessitent des politiques spécifiques à l’implémentation ou une reconception.

Vous devriez maintenant avoir une liste de tous les objets Ingress, leurs hosts et chemins, leurs liaisons TLS et les annotations ou comportements les plus susceptibles de casser pendant la migration.

Étape 2 : Décider d’une cible de migration

Ne supposez pas que Gateway API est une seule chose. Gateway API est une API Kubernetes plus une implémentation. Votre vraie cible de migration est une implémentation Gateway API ou un autre contrôleur supporté, et le comportement varie entre les implémentations.

Pourquoi Gateway API est généralement la cible par défaut

Gateway API existe pour résoudre plusieurs limitations d’Ingress : fonctionnalités limitées, dépendance excessive aux annotations et un modèle de permission insuffisant pour l’infrastructure partagée. Il fournit aussi un support standard pour les fonctionnalités courantes comme le matching de headers, la manipulation de requêtes/réponses, la répartition de trafic et un routage plus expressif.

Choisir en se basant sur des exigences concrètes

Faites une courte matrice de décision.

Fichier : gateway-target-matrix.yaml

requirements:
  standard_http_routing: required
  tls_termination: required
  weighted_routing: required
  request_header_modification: required
  auth_policy: required
  rate_limiting: required
  regex_path_matching: required
  cross_namespace_backend_refs: maybe

candidates:
  gateway_api_envoy:
    core_conformance: yes
    extended_features_needed: yes
    policy_extensions_for_auth: yes
    rate_limit_extension: yes
  gateway_api_istio:
    core_conformance: yes
    extended_features_needed: yes
    policy_extensions_for_auth: yes
    rate_limit_extension: yes
  existing_vendor_ingress:
    direct_feature_match: maybe
    long_term_portability: lower
    migration_effort: maybe_lower_short_term

Vous devriez maintenant savoir si votre cible est une implémentation Gateway API, laquelle c’est et quels comportements avancés nécessiteront des politiques spécifiques à l’implémentation ou une reconception.

Étape 3 : Installer les composants Gateway API

Gateway API est un add-on, pas quelque chose que chaque cluster a par défaut. Installez les CRDs Gateway API du canal standard.

# Replace v1.4.0 with the latest stable release
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

Puis vérifiez :

kubectl get crd | grep gateway.networking.k8s.io

Installez votre contrôleur choisi, puis vérifiez les objets GatewayClass :

kubectl get gatewayclass

Créer un Gateway de base

Fichier : gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: edge-system
spec:
  gatewayClassName: envoy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-example-com
      allowedRoutes:
        namespaces:
          from: All

kubectl apply -f gateway.yaml
kubectl get gateway -n edge-system

Étape 4 : Traduire un Ingress en ressources Gateway

Maintenant migrez un ingress représentatif. Gardez la première traduction ennuyeuse : routage host/path standard avec terminaison TLS et un seul backend.

Fichier : payments-httproute.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payments-web
  namespace: payments
spec:
  parentRefs:
    - name: public-gateway
      namespace: edge-system
      sectionName: https
  hostnames:
    - "payments.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: payments-web
          port: 8080

Ajoutez une redirection HTTP vers HTTPS explicite :

Fichier : payments-http-redirect.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payments-http-redirect
  namespace: payments
spec:
  parentRefs:
    - name: public-gateway
      namespace: edge-system
      sectionName: http
  hostnames:
    - "payments.example.com"
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

Vérifiez les routes traduites :

export GATEWAY_IP=$(kubectl get gateway public-gateway -n edge-system -o jsonpath='{.status.addresses[0].value}')
curl -I -H "Host: payments.example.com" http://$GATEWAY_IP/
curl -k -I -H "Host: payments.example.com" https://$GATEWAY_IP/

Étape 5 : Exécuter les deux côte à côte

Ne supprimez pas ingress-nginx après la première conversion. Utilisez des points d’entrée séparés pendant la validation.

export OLD_IP=$(kubectl get svc -n ingress-nginx ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
export NEW_IP=$(kubectl get gateway public-gateway -n edge-system -o jsonpath='{.status.addresses[0].value}')

curl -sS -H "Host: payments.example.com" http://$OLD_IP/health
curl -sS -H "Host: payments.example.com" http://$NEW_IP/health

Étape 6 : Migrer les cas avancés

Réécritures

Fichier : api-rewrite-route.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: customer-api
  namespace: api
spec:
  parentRefs:
    - name: public-gateway
      namespace: edge-system
      sectionName: https
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: customer-api
          port: 9000

Routage canary ou pondéré

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payments-canary
  namespace: payments
spec:
  parentRefs:
    - name: public-gateway
      namespace: edge-system
      sectionName: https
  hostnames:
    - "payments.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: payments-web
          port: 8080
          weight: 90
        - name: payments-web-canary
          port: 8080
          weight: 10

Étape 7 : Basculer en toute sécurité

Documentez le plan de bascule :

Fichier : cutover-plan.yaml

service: payments.example.com
current_entrypoint: ingress-nginx
target_entrypoint: gateway-api
cutover_method: dns
stages:
  - stage: internal-validation
    percent: 0
  - stage: pilot-traffic
    percent: 10
  - stage: partial-cutover
    percent: 50
  - stage: full-cutover
    percent: 100

rollback:
  trigger_window_minutes: 30
  action: restore_old_dns_target

Problèmes courants de configuration

Pas de remplacement direct

Symptôme : L’équipe attend qu’une traduction de manifeste préserve automatiquement le comportement.

Correction : Traitez la migration comme une revue de comportement. Inventoriez les annotations, choisissez un contrôleur délibérément et validez le comportement côte à côte.

Le comportement des annotations change

Symptôme : Les routes compilent, mais le matching de chemin ou les réécritures se comportent différemment.

Correction : Traduisez chaque annotation risquée intentionnellement. Testez les regex, réécritures, redirections et l’auth séparément.

Fonctionnalités spécifiques au contrôleur

Symptôme : L’auth, les limites de débit ou les fonctionnalités WAF n’ont pas d’équivalent YAML Gateway évident.

Correction : Utilisez le modèle de politique de votre implémentation. Gardez ces politiques séparées des ressources Gateway et HTTPRoute de base pour que la frontière soit évidente.

Conclusion

La façon sûre de migrer d’ingress-nginx vers Gateway API n’est pas “tout convertir et espérer.” C’est : auditer le comportement actuel, choisir un contrôleur cible basé sur les fonctionnalités que vous utilisez vraiment, installer Gateway API comme infrastructure de plateforme partagée, traduire un ingress proprement, valider les deux chemins côte à côte, puis basculer avec le rollback prêt.

Cette migration n’est pas juste remplacer un contrôleur. C’est une occasion de réduire la dette d’annotations, rendre la propriété du routage plus claire et déplacer votre configuration edge vers un modèle Kubernetes-natif plus portable.