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 ?

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

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

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 ?

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 :

┌─────────────────────────────────────────────────────────┐
│  GatewayClass (Cluster Admin)                          │
│  → Définit l'implémentation (Traefik, Envoy, NGINX...) │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│  Gateway (Platform Team)                                │
│  → Configure les listeners (ports, TLS, domaines)       │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│  HTTPRoute / GRPCRoute (Developers)                     │
│  → Définit le routage vers les Services                 │
└─────────────────────────────────────────────────────────┘

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

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.2.1/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.3+, v1.4+, etc. 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

GatewayClass

Définit l’implémentation utilisée (géré par l’admin cluster) :

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) :

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) :

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) :

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

kubectl get gatewayclass
# La colonne ACCEPTED doit être True

Vérifier les Gateway

kubectl get gateways -A

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

Vérifier les HTTPRoute

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

Routage par chemin

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

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)

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

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

Manipulation de headers

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

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

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

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

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.

Prochaines étapes

Traefik Déployez Traefik avec support Gateway API

TLS avec Traefik Automatisez les certificats ACME

Network Policies Sécurisez le trafic entre Pods

Les Ingress L'approche classique pour le routage HTTP

×

📖 Voir la documentation →