Gateway API : routage avancé et gouvernance réseau

Gateway API est la nouvelle approche recommandée pour les besoins de routage avancés dans Kubernetes. Elle complète et dépasse les capacités d'Ingress, dont l'API reste stable mais gelée. Ce guide présente les concepts clés, les différences avec Ingress, et comment adopter Gateway API progressivement.

Gateway API ≠ remplacement brutal d'Ingress

Gateway API ne "remplace" pas Ingress au sens de dépréciation. Kubernetes continue de documenter Ingress comme une API stable. Gateway API est une API additionnelle plus moderne, recommandée pour les nouveaux projets ou les besoins avancés.

Ce que vous allez apprendre

• Les limitations d'Ingress et pourquoi Gateway API existe
• Les ressources GatewayClass, Gateway, HTTPRoute et ReferenceGrant
• La différence entre canaux Standard et Experimental
• Créer et vérifier une configuration de routage
• Les fonctionnalités avancées (headers, redirections, weights)
• Quand choisir Ingress ou Gateway API

Pourquoi Gateway API ?

L'API Ingress date des débuts de Kubernetes et n'a plus évolué depuis sa stabilisation : tout ce qu'elle ne couvrait pas a été rajouté par les éditeurs sous forme d'annotations, propres à chaque contrôleur. Le résultat est une configuration qui ne survit pas à un changement d'implémentation. Gateway API repart de zéro avec des ressources typées et validées par l'API server, là où une annotation mal orthographiée était jusqu'ici ignorée sans le moindre message.

Ce que Gateway API change fondamentalement

Gateway API n'est pas seulement "Ingress avec plus de features". C'est une manière différente d'organiser les responsabilités réseau dans Kubernetes :

• Plus gouvernable, Séparation claire entre admin cluster, équipe plateforme et développeurs
• Plus composable, Ressources distinctes qui s'assemblent
• Plus standardisé, Modèle portable entre implémentations
• Plus exigeant, Demande plus de préparation qu'Ingress

Limitations d'Ingress

Ces limites ne sont pas des défauts d'implémentation mais des choix de conception : une ressource Ingress mélange dans un seul objet ce qui relève de l'infrastructure (ports, certificats) et ce qui relève de l'application (chemins, backends). Toute personne autorisée à créer un Ingress touche donc aux deux, ce qui interdit la délégation aux équipes de développement.

Limitation	Impact
Annotations vendor-specific	Configuration non portable
Un seul niveau de config	Pas de séparation infra/dev
HTTP(S) uniquement	Pas de TCP/UDP natif
Routage basique	Manipulation headers limitée
Pas de traffic splitting	Canary complexe à implémenter

Glissez pour voir

Ce qu'apporte Gateway API

La colonne de droite mérite d'être lue attentivement : Gateway API garantit la portabilité du modèle, pas celle du comportement. Un manifeste écrit pour Traefik s'applique tel quel sur Envoy Gateway, mais rien n'assure que le filtre exotique qu'il utilise soit implémenté des deux côtés. La page de conformité du projet reste la référence à consulter avant de s'engager sur une fonctionnalité.

Avantage	Réalité
Standardisé	Le modèle et les ressources sont portables, mais le niveau de support des fonctionnalités dépend encore de l'implémentation choisie
Expressif	Routage avancé sans annotations propriétaires
Séparation des rôles	Infra vs développeurs clairement modélisée
Multi-protocole	HTTP, HTTPS, TCP, UDP, gRPC au niveau du modèle d'API, le support opérationnel dépend du contrôleur
Extensible	Policies pour rate limiting, auth, etc.

Glissez pour voir

Portabilité ≠ identique partout

Gateway API standardise le modèle, mais pas encore l'expérience identique entre toutes les implémentations. Vérifiez la conformité de votre contrôleur avant d'utiliser une fonctionnalité avancée.

Quand choisir Ingress ou Gateway API ?

Le critère décisif n'est pas technique mais organisationnel : combien d'équipes partagent le même point d'entrée. Sur un cluster où une seule personne gère l'exposition de trois applications, Ingress fait le travail avec moins de concepts à maîtriser. Dès que plusieurs équipes publient des routes sur une infrastructure commune, la séparation des ressources devient un gain net. Les deux API cohabitent sans conflit dans un même cluster, ce qui autorise une bascule progressive.

Besoin	Ingress	Gateway API
Exposer vite une appli simple	✅ Bien adapté	⚠️ Possible mais plus structuré
Routage avancé multi-équipes	⚠️ Limité	✅ Très adapté
Politique claire infra/dev	❌ Faible	✅ Forte
Portabilité inter-contrôleurs	⚠️ Moyenne (annotations)	✅ Meilleure
Adoption dans cluster existant simple	✅ Plus facile	⚠️ Demande plus de préparation
Traffic splitting natif	❌ Non	✅ Oui
TCP/UDP/gRPC	❌ Non	✅ Selon contrôleur

Glissez pour voir

Recommandation :

• Nouveau projet avec besoins avancés → Gateway API
• Projet existant stable et simple → Ingress reste acceptable
• Besoin de gouvernance multi-équipes → Gateway API

Architecture et concepts

Gateway API sépare les responsabilités en trois niveaux :

Ressource	Qui la gère	Responsabilité
GatewayClass	Cluster admin	Choix du contrôleur
Gateway	Équipe plateforme	Ports, TLS, domaines autorisés
HTTPRoute	Développeurs	Règles de routage applicatif
ReferenceGrant	Équipe plateforme	Autorise les références cross-namespace

Glissez pour voir

Canaux Standard et Experimental

Gateway API publie ses fonctionnalités via deux canaux :

Canal	Usage	Stabilité
Standard	Production	Fonctionnalités GA, stables
Experimental	Tests, labs	Fonctionnalités en développement, peuvent changer

Glissez pour voir

Règle simple

Pour la production, restez sur le Standard channel. N'utilisez l'Experimental channel que pour des tests ou des besoins très spécifiques.

Pour connaître les fonctionnalités de chaque canal, consultez le guide Getting Started officiel.

Installation

Le déploiement se fait en deux temps, et les oublier tous les deux est l'erreur d'installation la plus fréquente. Les CRDs (Custom Resource Definitions) ajoutent les types Gateway, HTTPRoute et consorts au vocabulaire de l'API server ; le contrôleur est le programme qui lit ces objets et configure réellement un proxy. Sans contrôleur, vos ressources sont acceptées par le cluster mais aucun trafic n'est routé.

Installer les CRDs

Gateway API n'est pas inclus par défaut. Installez les CRDs depuis le Standard channel :

# Consultez la dernière version sur https://gateway-api.sigs.k8s.io/guides/
# Exemple avec une version récente (à adapter) :
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml

# Vérification
kubectl get crd | grep gateway

Vérifiez la version

Ne figez pas une vieille version. Consultez toujours le guide officiel d'installation pour la dernière version du Standard channel (v1.6+ selon la date).

Installer un contrôleur

Les CRDs seuls ne suffisent pas. Vous avez besoin d'un contrôleur qui implémente Gateway API :

Contrôleur	Notes
Traefik	Support complet, simple à déployer
Envoy Gateway	Référence Gateway API, très complet
NGINX Gateway Fabric	Performant, support enterprise
Cilium	eBPF-based, intégré au CNI
Istio	Service mesh complet
Kong	API Gateway avec plugins

Glissez pour voir

Compatibilité CRDs / Contrôleur

Installer une version récente des CRDs ne garantit pas que votre contrôleur implémente toutes les ressources ou filtres. Avant d'utiliser une fonctionnalité, vérifiez qu'elle est prise en charge par votre contrôleur et sa version via la page de conformité.

Ressources Gateway API

Quatre ressources composent le modèle, et elles s'emboîtent dans un ordre imposé : une HTTPRoute ne sert à rien sans un Gateway qui l'accepte, lequel ne démarre pas sans une GatewayClass prise en charge par un contrôleur. Le ReferenceGrant s'ajoute dès qu'une référence traverse une frontière de namespace. Les manifestes qui suivent forment un ensemble cohérent, à lire dans cet ordre.

GatewayClass

Définit l'implémentation utilisée (géré par l'admin cluster). Le champ controllerName désigne le contrôleur qui prendra en charge cette classe : c'est une chaîne fixée par l'éditeur, à reprendre exactement telle qu'elle figure dans sa documentation. Une GatewayClass est une ressource de portée cluster, elle n'appartient à aucun namespace :

gatewayclass.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: traefik
spec:
  controllerName: traefik.io/gateway-controller

GatewayClass souvent automatique

Dans la plupart des implémentations populaires, la GatewayClass est créée automatiquement à l'installation du contrôleur. Vous manipulerez surtout Gateway et HTTPRoute.

Vérifiez les GatewayClass disponibles :

kubectl get gatewayclass

Gateway

Configure les points d'entrée (géré par l'équipe plateforme). Chaque listener décrit une combinaison port, protocole et politique d'attachement ; c'est également ici que se termine le TLS, avec mode: Terminate qui déchiffre au niveau du Gateway. La création d'un Gateway provoque en général celle d'un Service de type LoadBalancer par le contrôleur, donc l'allocation d'une adresse publique :

gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: gateway-system
spec:
  gatewayClassName: traefik
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: wildcard-cert
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            gateway-access: "true"

Points clés :

• listeners, Définit les ports et protocoles
• allowedRoutes, Contrôle quels namespaces peuvent attacher des routes
• tls, Configuration TLS par listener

allowedRoutes.namespaces.from

• Same : seul le namespace du Gateway peut attacher des routes (sécurisé)
• Selector : les namespaces avec un label spécifique peuvent attacher des routes
• All : tous les namespaces peuvent attacher des routes, très permissif, évitez en production

certificateRefs cross-namespace

Si le Secret TLS est dans un autre namespace que le Gateway, vous devrez créer un ReferenceGrant pour autoriser la référence.

HTTPRoute

Définit les règles de routage (géré par les développeurs). Le champ parentRefs désigne le Gateway auquel la route demande à s'attacher : la demande n'aboutit que si la politique allowedRoutes du Gateway l'autorise, ce qui donne à l'équipe plateforme le dernier mot. Les hostnames déclarés ici doivent être compatibles avec ceux du listener, sans quoi la route est acceptée mais ne reçoit aucun trafic :

httproute.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-routes
  namespace: mon-app
spec:
  parentRefs:
  - name: main-gateway
    namespace: gateway-system
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/v1
    backendRefs:
    - name: api-service
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /api/v2
    backendRefs:
    - name: api-v2-service
      port: 80

ReferenceGrant

Autorise les références cross-namespace (essentiel pour la gouvernance). Par défaut, Kubernetes refuse qu'une ressource pointe vers un objet situé dans un autre namespace : sans cette autorisation explicite, n'importe quelle route pourrait monter le Secret TLS du voisin. Le ReferenceGrant se crée toujours dans le namespace qui détient l'objet convoité, ici celui du certificat, et c'est donc son propriétaire qui consent :

referencegrant.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-gateway-to-secret
  namespace: cert-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    namespace: gateway-system
  to:
  - group: ""
    kind: Secret
    name: wildcard-cert

Ce ReferenceGrant permet au Gateway dans gateway-system de référencer le Secret wildcard-cert dans cert-namespace.

Quand utiliser ReferenceGrant

• TLS : Gateway référence un Secret dans un autre namespace
• Backend : HTTPRoute référence un Service dans un autre namespace
• Tout ce qui croise les frontières de namespaces

Vérifier l'état des ressources

Gateway API fournit un status riche sur chaque ressource. Utilisez-le pour diagnostiquer :

Vérifier les GatewayClass

Une classe ACCEPTED: True prouve qu'un contrôleur l'a reconnue et se déclare responsable. Si la colonne reste vide ou à False, le contrôleur n'est pas installé ou le controllerName ne correspond pas au sien.

kubectl get gatewayclass
# La colonne ACCEPTED doit être True

Vérifier les Gateway

Deux conditions distinctes se suivent : Accepted signifie que la configuration est valide, Programmed que le proxy sous-jacent l'a réellement appliquée et écoute. Un Gateway Accepted mais pas Programmed traduit souvent une adresse de load balancer jamais attribuée.

kubectl get gateways -A

kubectl describe gateway main-gateway -n gateway-system
# Cherchez les conditions : Accepted, Programmed

Vérifier les HTTPRoute

Le bloc Parents du statut est renseigné par le Gateway lui-même, ce qui en fait la preuve que l'attachement a été accepté. La condition ResolvedRefs concerne les backends : elle passe à False si un Service référencé n'existe pas ou n'expose pas le port demandé.

kubectl get httproutes -A

kubectl describe httproute api-routes -n mon-app
# Cherchez : Parents (le Gateway parent) et les conditions Accepted/ResolvedRefs

Dépannage : HTTPRoute non attaché

C'est le problème le plus courant. Votre HTTPRoute existe mais le trafic ne passe pas.

1. Vérifiez que le Gateway existe et est ACCEPTED

   kubectl get gateway main-gateway -n gateway-system
   # Status doit être ACCEPTED

2. Vérifiez que l'HTTPRoute référence le bon Gateway

   kubectl describe httproute api-routes -n mon-app | grep -A5 "Parent Refs"

3. Vérifiez les conditions de l'HTTPRoute

   kubectl describe httproute api-routes -n mon-app | grep -A10 "Status"
   # Cherchez : Accepted, ResolvedRefs

4. Vérifiez que le namespace est autorisé

   Si le Gateway utilise allowedRoutes.namespaces.from: Selector, vérifiez que votre namespace a le bon label :

   kubectl get ns mon-app --show-labels

5. Vérifiez que le Service backend existe

   kubectl get svc api-service -n mon-app

Symptôme	Cause probable	Solution
HTTPRoute Accepted: False	Gateway introuvable ou mauvais namespace	Vérifiez parentRefs
HTTPRoute ResolvedRefs: False	Service backend introuvable	Vérifiez le nom/port du Service
Gateway Programmed: False	Contrôleur pas prêt	Vérifiez les logs du contrôleur
Trafic ne passe pas	Namespace non autorisé	Vérifiez allowedRoutes et labels

Glissez pour voir

Exemples pratiques

Les extraits qui suivent ne montrent que le bloc spec d'une HTTPRoute : ajoutez-y les parentRefs et les hostnames de votre contexte pour obtenir un manifeste applicable. Ils couvrent les cinq besoins qui reviennent en production, du simple découpage par chemin jusqu'à la réécriture d'en-têtes.

Routage par chemin

L'ordre des règles dans le fichier n'a aucune importance : la spécification impose de retenir la correspondance la plus spécifique, un chemin exact l'emportant sur un préfixe, et le préfixe le plus long sur le plus court. Inutile donc de classer vos règles de la plus fine à la plus large comme le réflexe nginx y pousse.

spec:
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /users
    backendRefs:
    - name: users-service
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /orders
    backendRefs:
    - name: orders-service
      port: 80

Routage par header

La comparaison est exacte par défaut et sensible à la casse pour la valeur, pas pour le nom de l'en-tête. Ce mécanisme sert surtout aux déploiements sombres : les testeurs positionnent l'en-tête et atteignent la version candidate, tous les autres restent sur la version stable.

spec:
  rules:
  - matches:
    - headers:
      - name: X-Version
        value: "beta"
    backendRefs:
    - name: api-beta
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-stable
      port: 80

Traffic splitting (Canary)

Les weight ne sont pas des pourcentages mais des parts relatives : la proportion reçue par un backend vaut son poids divisé par la somme des poids de la règle. Un poids à 0 retire un backend de la répartition sans supprimer sa déclaration, ce qui permet de couper un canari en une seule modification.

spec:
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-v1
      port: 80
      weight: 90
    - name: api-v2
      port: 80
      weight: 10

Traffic splitting

Le traffic splitting est pris en charge par le modèle Gateway API via les backendRefs pondérés, sans recourir à des annotations propriétaires. Vérifiez néanmoins le support exact de votre implémentation.

Redirections

Le filtre RequestRedirect répond directement au client, sans jamais joindre de backend : une règle qui l'utilise n'a donc pas besoin de backendRefs. Le statusCode accepte 301 (permanent, mis en cache par les navigateurs) ou 302, et le choix se corrige mal une fois la réponse mémorisée côté client.

spec:
  rules:
  - matches:
    - path:
        type: Exact
        value: /old-page
    filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        hostname: new.example.com
        statusCode: 301

Manipulation de headers

RequestHeaderModifier agit sur la requête envoyée au backend, jamais sur la réponse renvoyée au client, qui relève du filtre ResponseHeaderModifier. Retirer un en-tête interne avant de transmettre est une bonne pratique de sécurité : cela empêche un client de forger un en-tête auquel votre application ferait confiance.

spec:
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Environment
          value: "staging"
        remove:
        - X-Internal-Header
    backendRefs:
    - name: api-service
      port: 80

Migration depuis Ingress

Migrer ne consiste pas à convertir des fichiers un par un : un Ingress correspond à deux ressources Gateway API portées par deux équipes différentes. La bascule se fait donc application par application, en gardant les deux API actives le temps de la transition, puisqu'elles peuvent servir le même nom de domaine sur des points d'entrée distincts.

Prérequis pour migrer

La migration depuis Ingress suppose généralement qu'une équipe plateforme ait déjà :

1. Déployé un contrôleur compatible Gateway API
2. Créé une GatewayClass (ou utilisé celle créée automatiquement)
3. Publié un Gateway auquel les équipes applicatives peuvent rattacher leurs routes

Les développeurs ne "remplacent" pas juste un Ingress par un HTTPRoute, ils attachent leur route à un Gateway existant.

Équivalence des concepts

Ce tableau sert de grille de lecture pour traduire un manifeste existant. Les deux dernières lignes concentrent le vrai travail : ce qui vivait dans des annotations propriétaires devient un champ typé, dont le nom et la structure changent d'un contrôleur à l'autre. Toutes les annotations n'ont pas d'équivalent, certaines correspondent à des fonctionnalités encore en canal Experimental.

Ingress	Gateway API
IngressClass	GatewayClass
Ingress	Gateway + HTTPRoute
host:	HTTPRoute hostnames:
path:	HTTPRoute matches.path:
backend:	HTTPRoute backendRefs:
Annotations TLS	Gateway listeners.tls:
Annotations rewrite	HTTPRoute filters.URLRewrite:

Glissez pour voir

Exemple de migration

Cet exemple illustre le déplacement de responsabilité : l'annotation rewrite-target, spécifique à NGINX, devient un filtre URLRewrite standard, et tout ce qui touchait au point d'entrée disparaît du manifeste du développeur. Le fichier final est plus long mais ne contient plus rien de propriétaire.

Ingress (avant) :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 80

Gateway API (après) :

# L'équipe plateforme a déjà créé le Gateway
# Le développeur crée uniquement l'HTTPRoute :
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: mon-app
spec:
  parentRefs:
  - name: main-gateway
    namespace: gateway-system
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /
    backendRefs:
    - name: api-service
      port: 80

Maturité et évolution

Le socle HTTP est stable et utilisable en production sans réserve ; ce sont les protocoles autres que HTTP et les politiques avancées qui restent mouvants. La mention « selon certaines implémentations » est déterminante : une ressource peut être GA dans la spécification tout en n'étant supportée par aucun contrôleur que vous envisagez. Vérifiez toujours le couple ressource et contrôleur, jamais la ressource seule.

Aspect	État (2026)
HTTPRoute, Gateway, GatewayClass	GA (Standard channel)
GRPCRoute, TLSRoute	GA sur certaines implémentations
ReferenceGrant	GA
TCPRoute, UDPRoute	Experimental sur certaines implémentations
BackendTLSPolicy	Experimental

Glissez pour voir

Gateway API est en GA pour son socle principal et continue d'évoluer via les canaux Standard et Experimental. Consultez régulièrement les release notes pour suivre les nouveautés.

À retenir

Ressource	Rôle	Géré par
GatewayClass	Choix implémentation	Admin cluster
Gateway	Listeners, TLS, namespaces autorisés	Équipe plateforme
HTTPRoute	Règles de routage	Développeurs
ReferenceGrant	Autorise références cross-namespace	Équipe plateforme

Glissez pour voir

Ce que Gateway API apporte :

1. Gouvernance, Séparation claire des responsabilités infra/dev
2. Portabilité, Configuration standardisée (mais vérifiez le support du contrôleur)
3. Traffic splitting, Canary natif sans annotations
4. Manipulation headers, Filtres intégrés
5. Multi-protocole, HTTP, TCP, gRPC (selon implémentation)

Ce que Gateway API demande :

1. Plus de préparation, Gateway doit exister avant les routes
2. Vérification de conformité, Toutes les features ne sont pas supportées partout
3. Compréhension du modèle, Plus de concepts qu'Ingress

Message clé : Ingress reste acceptable pour les cas simples. Gateway API devient le meilleur choix dès qu'on veut de la gouvernance, du routage avancé, ou une standardisation durable.

Testez vos connaissances

Ces questions portent sur les points qui coûtent le plus cher en pratique : le rôle de chaque ressource, les conditions de statut et les règles d'attachement entre namespaces. Un score inférieur à 70 % désigne les sections à relire avant de déployer.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

8 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Pod Networking : Le chemin réseau réel entre la Gateway et les Pods de destination.
• mTLS pod-to-pod : Le chiffrement du trafic interne, complément du TLS terminé en bordure.

×

📖 Voir la documentation →