#kubernetes#envoy-gateway#gateway-api#httproute#grpcroute#tcproute#tlsroute

Cheatsheet de tipos de ruta en Envoy Gateway: ¿HTTPRoute, GRPCRoute, TCPRoute o TLSRoute?

5 min read

Si has leído los artículos anteriores, la pregunta que probablemente te está bloqueando ahora no es "no entiendo Gateway API" — sino:

"Bien, pero ¿cuál escribo realmente — HTTPRoute, GRPCRoute, TCPRoute o TLSRoute?"

Este artículo existe precisamente para aclarar eso. Guárdalo como referencia de bolsillo. Cuando aparezca un nuevo servicio, consúltalo primero — te ahorrará escribir YAML a ciegas y recibir una lección a través de los condition statuses.

La conclusión primero: cuatro tipos de ruta, cuatro propósitos

Tipo de ruta Capa de tráfico Qué inspecciona Ideal para No apto para
HTTPRoute L7 HTTP/HTTPS host, path, header, query, method Sitios web, REST APIs, tráfico web general TCP sin procesar, TLS passthrough
GRPCRoute L7 gRPC hostname, service, method, header Enrutamiento por servicio/método gRPC REST APIs generales, TCP sin procesar
TCPRoute L4 TCP Información de listener y nivel de conexión Bases de datos, protocolos TCP personalizados, servicios no HTTP Escenarios que requieren inspección de path/header
TLSRoute L4/L5 TLS TLS SNI hostname TLS passthrough, preservar cifrado extremo a extremo Necesitar inspeccionar detalles HTTP tras el descifrado

Si quieres una versión ultracorta:

  • Inspeccionar path o header → HTTPRoute
  • Inspeccionar service/method de gRPC → GRPCRoute
  • Solo reenviar conexiones TCP → TCPRoute
  • Sin terminación TLS, solo enrutamiento por SNI → TLSRoute

Decisión en tres pasos: deja de adivinar

Usa este orden:

  1. ¿Parseará el Gateway semántica HTTP de este tráfico?
  2. Si es sí, ¿es HTTP/REST normal o gRPC?
  3. Si es no, ¿es TCP sin procesar o TLS passthrough?

Resumido:

  • Tiene path/header/method HTTP que inspeccionar → HTTPRoute
  • Tiene service/method de gRPC que inspeccionar → GRPCRoute
  • Sin reglas L7, solo reenvío TCP → TCPRoute
  • Quiere TLS preservado hasta el backend → TLSRoute

Esta decisión importa mucho. Mucha gente escribe HTTPRoute instintivamente primero y luego se da cuenta a mitad de camino de que está tratando con tráfico de base de datos. Todo el YAML entra en modo "¿qué estoy haciendo?".

Ejemplos YAML mínimos: reconoce cada uno de un vistazo

Aquí están las versiones más cortas y reconocibles de cada uno.

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 ves path, hostnames y backendRefs — es este.

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 ves method.service y method.method — estás haciendo matching con semántica gRPC, no HTTP normal.

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 casi no tiene conceptos de path/header — porque no los examina. Es más cercano a: "las conexiones TCP que llegan a este listener van a este 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

Normalmente se combina con un listener protocol: TLS. El foco no es el descifrado — es el enrutamiento basado en SNI.

💡 TCPRoute y TLSRoute suelen vivir en el canal experimental según la versión de Gateway API. Verifica la versión del CRD instalada en tu clúster antes de aplicar.

Cuatro errores comunes

1. gRPC no necesita obligatoriamente GRPCRoute

Si solo necesitas que fluya tráfico gRPC, algunas implementaciones pueden soportarlo vía HTTPRoute ya que gRPC corre sobre HTTP/2. Pero si quieres hacer matching sobre semántica de service/method de gRPC, GRPCRoute es la opción más correcta y legible.

2. TLSRoute no es "HTTPS pero avanzado"

Este es el malentendido más común.

  • HTTPS listener + HTTPRoute: el Gateway termina TLS, luego aplica reglas HTTP
  • TLS listener + TLSRoute: el Gateway NO termina TLS, enruta solo basándose en SNI

Uno descifra y opera en L7. El otro mantiene el tráfico cifrado y hace passthrough. Mundos completamente distintos.

3. TCPRoute no puede ver path/header

Si tu requisito es:

  • /api va a A
  • /admin va a B

Ese no es el trabajo de TCPRoute. TCPRoute no entiende detalles HTTP. Forzar esos requisitos en él es prepararse para la frustración.

4. parentRefs.sectionName es importante

Cuando un Gateway tiene múltiples listeners, usa sectionName:

parentRefs:
  - name: eg
    sectionName: https

Esto asegura que tu ruta se adjunte exactamente al listener que pretendes. Sin él, podrías creer que estás reservando la sala VIP y terminar en el salón equivocado.

Resumen en una línea

Primero identifica con qué estás trabajando: HTTP, gRPC, TCP o TLS passthrough — luego elige el tipo de ruta correcto. Acierta con la ruta y el 80% de tu YAML fluye naturalmente. Falla y quedarás atrapado en una batalla con los condition statuses.

Siguiente paso

Una vez que entiendes los tipos de ruta, el siguiente obstáculo común es: Cuando el mismo Gateway tiene muchos listeners, ¿cómo los estructuras sin crear caos?

El próximo artículo cubre el diseño de multi-listener: 👉 Guía de diseño de Listeners