Antisèche des types de routes Envoy Gateway : HTTPRoute, GRPCRoute, TCPRoute ou TLSRoute ?

Si vous avez lu les articles précédents, la question qui vous bloque probablement le plus maintenant n'est pas "je ne comprends pas Gateway API", mais plutôt :

"D'accord, mais lequel dois-je vraiment écrire : HTTPRoute, GRPCRoute, TCPRoute ou TLSRoute ?"

Cet article existe précisément pour démêler cela. Gardez-le comme référence de poche. Quand un nouveau service apparaît, consultez-le d'abord : cela vous évitera d'écrire du YAML à l'aveugle et de recevoir une leçon de la part des conditions de status.

La conclusion d'abord : quatre types de routes, quatre usages

Si vous voulez une version ultra-courte :

• Inspecter path ou header → HTTPRoute
• Inspecter gRPC service/method → GRPCRoute
• Simple forwarding de connexions TCP → TCPRoute
• Pas de terminaison TLS, routage SNI uniquement → TLSRoute

Décision en trois étapes : arrêtez de deviner

Utilisez cet ordre :

1. Le Gateway va-t-il analyser la sémantique HTTP de ce trafic ?
2. Si oui, s'agit-il de HTTP/REST classique, ou de gRPC ?
3. Si non, est-ce du TCP brut, ou du TLS passthrough ?

Cartographié :

• Il y a du HTTP path/header/method à inspecter → HTTPRoute
• Il y a du gRPC service/method à inspecter → GRPCRoute
• Pas de règle L7, juste du forwarding TCP → TCPRoute
• Vous voulez préserver TLS jusqu'au backend → TLSRoute

Cette décision compte énormément. Beaucoup de gens écrivent instinctivement HTTPRoute d'abord, puis réalisent en plein milieu qu'ils manipulent en fait du trafic de base de données. Tout le YAML bascule alors en mode "mais qu'est-ce que je suis en train de faire ?"

Exemples YAML minimaux : reconnaître chacun au premier coup d'oeil

Voici les versions les plus courtes et les plus reconnaissables de chacun.

HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
spec:
  parentRefs:
    - name: eg
      sectionName: http
  hostnames:
    - "app.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-service
          port: 8080

Si vous voyez path, hostnames et backendRefs, c'est celui-ci.

GRPCRoute

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: user-grpc
spec:
  parentRefs:
    - name: eg
      sectionName: grpc
  hostnames:
    - "grpc.example.com"
  rules:
    - matches:
        - method:
            service: com.example.User
            method: Login
      backendRefs:
        - name: user-grpc-service
          port: 50051

Si vous voyez method.service et method.method, vous êtes dans la sémantique gRPC, pas dans du HTTP classique.

TCPRoute

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: postgres-route
spec:
  parentRefs:
    - name: eg
      sectionName: postgres
  rules:
    - backendRefs:
        - name: postgres
          port: 5432

TCPRoute n'a pratiquement aucune notion de path/header, parce qu'il ne les regarde pas. Il ressemble davantage à : "les connexions TCP arrivant sur ce listener vont vers ce backend".

TLSRoute

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: passthrough-route
spec:
  parentRefs:
    - name: eg
      sectionName: tls
  hostnames:
    - "db.example.com"
  rules:
    - backendRefs:
        - name: db-service
          port: 5432

Il est généralement associé à un listener protocol: TLS. L'enjeu n'est pas le déchiffrement, mais le routage basé sur SNI.

💡 TCPRoute et TLSRoute se trouvent souvent dans le canal experimental selon les versions de Gateway API. Vérifiez la version des CRD installée dans votre cluster avant d'appliquer.

Quatre pièges courants

1. gRPC ne nécessite pas forcément GRPCRoute

Si vous voulez seulement faire passer du trafic gRPC, certaines implémentations peuvent le prendre en charge via HTTPRoute, puisque gRPC tourne sur HTTP/2. Mais si vous voulez faire du matching sur la sémantique gRPC service/method, GRPCRoute est le choix le plus correct et le plus lisible.

2. TLSRoute n'est pas "HTTPS mais en plus avancé"

C'est la confusion la plus fréquente.

• HTTPS listener + HTTPRoute : le Gateway termine TLS, puis applique des règles HTTP
• TLS listener + TLSRoute : le Gateway ne termine PAS TLS, il route uniquement selon SNI

L'un déchiffre et travaille en L7. L'autre garde le trafic chiffré et fait du passthrough. Ce sont deux mondes complètement différents.

3. TCPRoute ne peut pas voir path/header

Si votre besoin est :

• /api va vers A
• /admin va vers B

Ce n'est pas le travail de TCPRoute. TCPRoute ne comprend pas les détails HTTP. Lui imposer ce type d'exigence, c'est simplement préparer votre future frustration.

4. parentRefs.sectionName est important

Lorsqu'un Gateway possède plusieurs listeners, utilisez sectionName :

parentRefs:
  - name: eg
    sectionName: https

Cela garantit que votre route s'attache précisément au listener voulu. Sans cela, vous pouvez croire avoir réservé la salle VIP et vous retrouver dans le mauvais hall.

Résumé en une ligne

Identifiez d'abord ce que vous traitez : HTTP, gRPC, TCP, ou TLS passthrough puis choisissez le bon type de route. Choisissez correctement la route, et 80 % de votre YAML s'écoulera naturellement. Choisissez mal, et vous voilà coincé dans une bataille contre les conditions de status.

Étape suivante

Une fois les types de routes compris, le prochain point de blocage courant est : Quand un même Gateway possède beaucoup de listeners, comment les structurer sans créer le chaos ?

L'article suivant couvre la conception multi-listeners : 👉 Guide de conception des listeners