Concepts de base d'Envoy Gateway : Gateway, Listener, Proxy et la famille Route expliqués

La première impression de beaucoup de gens face à Gateway API ressemble à ceci : "Il n'y a pas tant de termes que ça, mais mon cerveau a l'impression de regarder une liste d'acteurs avec des noms trop similaires : impossible de savoir qui est le protagoniste et qui est le second rôle." Cet article est là pour dissiper cette confusion, tout en couvrant les types de routes les plus courants.

L'architecture globale

Les concepts officiels d'Envoy Gateway découpent le système en trois couches :

User Configuration : les ressources Gateway API et les CRD d'extension Envoy Gateway que vous écrivez
Envoy Gateway Controller : lit les ressources, les valide et traduit la configuration
Envoy Proxy : le plan de données qui gère réellement le trafic

Autrement dit, ce que vous modifiez d'habitude n'est pas Envoy Proxy lui-même : vous êtes en train de "déclarer ce que vous voulez". Envoy Gateway traduit ensuite ces déclarations en configuration qu'Envoy Proxy peut exécuter. C'est ce qui rend l'approche plus agréable que l'écriture manuelle d'une configuration proxy.

Les rôles clés

Pour l'instant, retenez simplement ceci :

GatewayClass : définit "quelle implémentation de Gateway utiliser dans ce cluster"
Gateway : définit "où se trouve l'entrée et quel protocole elle parle"
Listener : définit un point d'entrée précis par port/protocole/hostname
Route : définit "quelles requêtes vont vers quel Service"
Envoy Proxy : le véritable Gateway Proxy qui reçoit et transfère le trafic

En français courant :

GatewayClass est la fiche technique
Gateway est l'entrée principale du bâtiment
Listener est le bureau d'accueil
Route est la signalétique à l'intérieur du bâtiment
Envoy Proxy est le système de sécurité qui contrôle l'accès et escorte les gens

S'il en manque un seul, le trafic n'ira pas là où vous voulez.

Un YAML minimal qui montre toute l'image

Voici le plus petit exemple réellement compréhensible :

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: backend
spec:
  parentRefs:
    - name: eg
  hostnames:
    - "www.example.com"
  rules:
    - backendRefs:
        - name: backend
          port: 3000

Assemblé, le raisonnement est :

GatewayClass dit que le contrôleur Envoy Gateway est responsable
Gateway déclare une entrée HTTP sur le port 80
HTTPRoute dit que les requêtes vers www.example.com doivent aller vers backend:3000
Envoy Gateway traduit tout cela pour Envoy Proxy

Comprendre chaque champ

`GatewayClass`

Il s'agit d'une définition de type d'entrée au niveau du cluster. Le champ le plus critique est généralement :

spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

Cela signifie simplement : "Ce GatewayClass est géré par le contrôleur Envoy Gateway."

Si le controllerName ne correspond pas, c'est comme commander une livraison à la mauvaise entreprise : personne ne vient la récupérer.

`Gateway`

Cela définit "à quoi ressemble l'entrée". Le champ le plus souvent consulté est listeners :

listeners:
  - name: http
    protocol: HTTP
    port: 80

Cela signifie :

Ouvrir un listener nommé http
Accepter du trafic HTTP
Écouter à l'extérieur sur le port 80

Pour HTTPS, vous ajouteriez généralement un autre listener avec protocol: HTTPS et une configuration TLS associée.

Gateway gère généralement :

Le port externe et le protocole
Le hostname par listener
L'endroit où la terminaison TLS se produit
Quels namespaces peuvent attacher leurs routes

Gateway relève davantage de la couche plateforme : sa responsabilité appartient généralement à l'équipe plateforme.

`Listener`

C'est le rôle que les débutants négligent le plus souvent, alors qu'il est en réalité crucial.

Un listener est un point d'entrée exposé vers l'extérieur sur le Gateway. Il définit :

name
port
protocol
hostname
tls
allowedRoutes

Exemple :

listeners:
  - name: https
    protocol: HTTPS
    port: 443
    hostname: api.example.com

Cela signifie :

Ce point s'appelle https
Il accepte HTTPS
Il écoute sur le port 443
Il est dédié à api.example.com

Si vous avez plusieurs listeners comme :

http pour le port 80
https pour le port 443
grpc pour le port 50051

Alors vous ouvrez plusieurs points d'entrée sur le même Gateway, chacun pouvant accueillir des routes différentes.

`Envoy Proxy`

Beaucoup de gens se concentrent uniquement sur le YAML et oublient que c'est Envoy Proxy qui traite réellement le trafic vivant.

Son rôle est :

Recevoir les requêtes clientes
Faire le matching avec la configuration poussée par Envoy Gateway
Transférer le trafic vers le backend approprié
Gérer TLS, headers, timeouts, retries et autres comportements du plan de données

Voyez donc Envoy Gateway comme le "plan de contrôle", et Envoy Proxy comme le "plan de données / Gateway Proxy".

La famille Route

Route, ce n'est pas seulement HTTPRoute. Toute la famille est au coeur de la conception de Gateway API.

`HTTPRoute`

C'est celui que vous écrirez et modifierez le plus souvent. Trois champs clés :

spec:
  parentRefs:
    - name: eg
  hostnames:
    - "www.example.com"
  rules:
    - backendRefs:
        - name: backend
          port: 3000

parentRefs : à quel Gateway s'attacher
hostnames : quel header Host déclenche cette règle
backendRefs : où envoyer les requêtes correspondantes

La confusion la plus fréquente : Gateway n'est pas l'endroit où vous écrivez le routage fin, c'est HTTPRoute qui décide réellement "comment répartir le trafic".

`GRPCRoute`

Si vous gérez du gRPC, GRPCRoute est plus naturel que de forcer cela dans HTTPRoute.

Il peut faire du matching sur :

Le hostname gRPC
Le service gRPC
La méthode gRPC
Les headers

Exemple :

matches:
  - method:
      service: com.example.User
      method: Login

Cette sémantique s'aligne naturellement avec gRPC : vous ne faites pas seulement du matching sur des chemins d'URL, vous matchez directement sur le modèle service/method de gRPC.

La documentation officielle précise aussi que si GRPCRoute et HTTPRoute partagent le même listener avec des hostnames en conflit, l'implémentation doit en rejeter un. En gros, ne laissez pas HTTP et gRPC se battre pour le même hostname.

`TCPRoute`

TCPRoute gère le trafic TCP brut. Contrairement à HTTPRoute, il ne comprend pas les notions L7 comme les chemins ou les headers ; il est plus proche d'un forwarding L4.

Scénarios adaptés :

Services avec protocole non HTTP
Services TCP purs
Routage des connexions vers différents backends uniquement selon le port du listener

Les bases de données utilisant des protocoles personnalisés ou des protocoles TCP propriétaires sont des cas d'usage typiques de TCPRoute.

`TLSRoute`

TLSRoute gère le trafic TLS et apparaît particulièrement souvent dans les scénarios de TLS passthrough.

Concept central :

Le Gateway ne termine pas forcément TLS
Il peut router le trafic uniquement à partir du hostname SNI dans la négociation TLS
Le trafic chiffré est conservé jusqu'au backend

C'est important pour les scénarios qui exigent un chiffrement de bout en bout, ou quand vous ne voulez pas terminer TLS au niveau du Gateway.

Comment choisir un type de route

Besoin	Utiliser ceci
Sites web, API REST, trafic web général	`HTTPRoute`
Routage par service/method gRPC	`GRPCRoute`
Trafic TCP brut	`TCPRoute`
TLS passthrough / routage basé sur SNI	`TLSRoute`

Ce tableau compte beaucoup, car beaucoup de gens écrivent instinctivement HTTPRoute pour tout. Mais si vous traitez en réalité du gRPC ou du TCP, le forcer dans HTTPRoute ne fait que rendre le YAML de plus en plus maladroit.

Pourquoi les routes sont plus faciles à raisonner qu'Ingress

Les anciennes configurations Ingress entassaient souvent trop de responsabilités dans une seule ressource, ce qui menait à des douleurs récurrentes :

Mélange entre configuration plateforme et routage applicatif
Fonctions avancées exprimées via des annotations peu lisibles
Expressivité limitée pour les protocoles non HTTP

L'approche de Gateway API consiste à séparer les responsabilités :

Les équipes plateforme gèrent GatewayClass / Gateway
Les équipes applicatives gèrent leur propre HTTPRoute

Cette séparation fonctionne bien pour la collaboration à plusieurs. Vous n'avez pas besoin de toucher toute la couche d'entrée juste pour changer un chemin, et le taux de "les équipes se marchent dessus" baisse fortement.

Commencez à prêter attention au status

Au-delà de spec, prenez progressivement l'habitude de vérifier status. En particulier pour HTTPRoute et Gateway :

kubectl get gateway eg -o yaml
kubectl get httproute backend -o yaml

Commencez par regarder :

Si la route a été Accepted
Si le listener du gateway est Ready
Si une adresse a été attribuée avec succès

C'est comme vérifier le résultat d'un examen. Ne vérifiez pas seulement que vous avez rendu votre copie ; vérifiez qu'elle a été corrigée et validée.

Résumé en une ligne

Pensez à GatewayClass, Gateway, Listener, Route et Envoy Proxy comme à "qui gère, comment l'entrée s'ouvre, comment chaque point d'entrée se connecte, comment le trafic se répartit et qui l'exécute" — et vous avez déjà saisi 80 % des concepts de base.

💡 Les débutants plongent souvent directement dans les détails des CRD. Ne vous pressez pas : mettez d'abord ces rôles au clair, et le YAML cessera de donner l'impression de rencontrer des inconnus à chaque fois.

Étape suivante

Maintenant que les concepts sont en place, l'article suivant se concentre sur les scénarios de routage HTTP les plus courants — hôte, chemin, header et répartition de trafic : 👉 Routage HTTP en pratique