Conceptos Clave de Envoy Gateway: Gateway, Listener, Proxy y la Familia de Rutas Explicados

La primera impresión que muchas personas tienen del Gateway API es algo como: "La cantidad de términos no es tan alta, pero mi cerebro se siente como si estuviera viendo un reparto lleno de personajes con nombres similares — no puedo distinguir quién es el protagonista y quién es un personaje secundario." Este artículo está aquí para cortar esa confusión, y también cubrirá los tipos de rutas más comunes.

La Arquitectura General

Los conceptos oficiales de Envoy Gateway dividen el sistema en tres capas:

Configuración del Usuario: Los recursos de Gateway API y los CRDs de extensión de Envoy Gateway que escribes
Controlador de Envoy Gateway: Lee los recursos, los valida y traduce la configuración
Envoy Proxy: El plano de datos que realmente maneja el tráfico

Esto significa que lo que generalmente estás editando no es Envoy Proxy en sí — estás "declarando lo que quieres." Envoy Gateway traduce esas declaraciones en configuración que Envoy Proxy puede ejecutar. Eso es lo que lo hace más agradable que escribir configuración de proxy a mano.

Los Roles Clave

Por ahora, recuerda estos:

GatewayClass: Define "qué implementación de Gateway usar en este clúster"
Gateway: Define "dónde está el ingreso y qué protocolo habla"
Listener: Define un slot de ingreso específico por puerto/protocolo/hostname
Route: Define "qué solicitudes van a qué Service"
Envoy Proxy: El Gateway Proxy real que recibe y reenvía el tráfico

En palabras simples:

GatewayClass es la ficha técnica
Gateway es la entrada principal del edificio
Listener es la recepción
Route es la señalización dentro del edificio
Envoy Proxy es el sistema de seguridad que controla el acceso y acompaña a los visitantes

Sin alguno de estos, el tráfico no llegará a donde quieres.

Un YAML Mínimo que Muestra el Panorama Completo

Aquí está el ejemplo más pequeño y comprensible:

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

Encadenados, la lógica es:

GatewayClass indica que el controlador Envoy Gateway está a cargo
Gateway declara un ingreso HTTP en el puerto 80
HTTPRoute indica que las solicitudes para www.example.com deben ir a backend:3000
Envoy Gateway traduce todo esto para Envoy Proxy

Entendiendo Cada Campo

`GatewayClass`

Esta es una definición de tipo de ingreso a nivel de clúster. El campo más crítico suele ser:

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

Esto simplemente significa: "Este GatewayClass está gestionado por el controlador de Envoy Gateway."

Si el controllerName no coincide, es como pedir un delivery a la empresa equivocada — nadie lo recoge.

`Gateway`

Esto define "cómo se ve el ingreso." El campo más referenciado es listeners:

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

Esto significa:

Abrir un listener llamado http
Aceptar tráfico HTTP
Escuchar externamente en el puerto 80

Para HTTPS, normalmente agregarías otro listener con protocol: HTTPS y adjuntarías la configuración TLS.

Gateway comúnmente gestiona:

Puerto externo y protocolo
Hostname por listener
Ubicación de terminación TLS
Qué rutas de qué namespaces pueden adjuntarse

Gateway es más una preocupación de la capa de plataforma — su propiedad normalmente recae en el equipo de plataforma.

`Listener`

Este es el rol que los principiantes pasan por alto con más frecuencia, pero en realidad es crucial.

Un listener es un slot de ingreso orientado al exterior en el Gateway. Define:

name
port
protocol
hostname
tls
allowedRoutes

Ejemplo:

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

Esto significa:

Este slot se llama https
Acepta HTTPS
Escucha en el puerto 443
Dedicado a api.example.com

Si tienes múltiples listeners como:

http para el puerto 80
https para el puerto 443
grpc para el puerto 50051

Estás abriendo múltiples slots de ingreso en el mismo Gateway, cada uno capaz de adjuntar diferentes rutas.

`Envoy Proxy`

Muchas personas se centran solo en el YAML y olvidan que Envoy Proxy es lo que realmente maneja el tráfico en vivo.

Su rol es:

Recibir solicitudes de los clientes
Hacer coincidir con la configuración enviada por Envoy Gateway
Reenviar el tráfico al backend apropiado
Manejar TLS, headers, timeouts, reintentos y otros comportamientos del plano de datos

Así que piensa en Envoy Gateway como el "plano de control," y en Envoy Proxy como el "plano de datos / Gateway Proxy."

La Familia de Routes

Route no es solo HTTPRoute. Toda la familia es central en el diseño del Gateway API.

`HTTPRoute`

Este es el que escribirás y modificarás con mayor frecuencia. Tres campos clave:

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

parentRefs: A qué Gateway adjuntarse
hostnames: Qué header Host activa esta regla
backendRefs: A dónde enviar las solicitudes coincidentes

La confusión más común: Gateway no es donde escribes el enrutamiento detallado — HTTPRoute es lo que realmente decide "cómo dividir el tráfico."

`GRPCRoute`

Si manejas gRPC, GRPCRoute es más natural que forzarlo dentro de HTTPRoute.

Puede hacer coincidir por:

Hostname de gRPC
Servicio de gRPC
Método de gRPC
Headers

Ejemplo:

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

Esta semántica se alinea naturalmente con gRPC — no solo estás haciendo coincidir rutas de URL, sino que estás haciendo coincidir directamente con el modelo de servicio/método de gRPC.

La documentación oficial también señala: si GRPCRoute y HTTPRoute comparten el mismo listener y tienen hostnames en conflicto, las implementaciones deberían rechazar uno. Básicamente, no dejes que HTTP y gRPC peleen por el mismo hostname.

`TCPRoute`

TCPRoute maneja tráfico TCP sin procesar. A diferencia de HTTPRoute, no entiende la semántica de rutas o headers en L7 — está más cerca del reenvío en L4.

Escenarios apropiados:

Servicios con protocolos no HTTP
Servicios TCP puros
Enrutar conexiones a diferentes backends basándose únicamente en el puerto del listener

Las bases de datos con protocolos personalizados o protocolos TCP propietarios son casos de uso típicos de TCPRoute.

`TLSRoute`

TLSRoute maneja tráfico TLS y es particularmente común en escenarios de TLS passthrough.

Concepto central:

El Gateway no necesariamente termina TLS
Puede enrutar el tráfico basándose únicamente en el hostname SNI en el handshake TLS
El tráfico cifrado se preserva hasta el backend

Esto importa en escenarios que requieren cifrado de extremo a extremo, o donde no quieres que TLS se termine en el Gateway.

Cómo Elegir un Tipo de Route

Requisito	Usar Esto
Sitios web, REST APIs, tráfico web general	`HTTPRoute`
Enrutamiento por servicio/método de gRPC	`GRPCRoute`
Tráfico TCP sin procesar	`TCPRoute`
TLS passthrough / enrutamiento basado en SNI	`TLSRoute`

Esta tabla importa porque muchas personas instintivamente escriben HTTPRoute para todo. Pero si realmente estás manejando gRPC o TCP, forzarlo en HTTPRoute solo hace que el YAML sea cada vez más torpe.

Por Qué las Routes Son Más Fáciles de Razonar que Ingress

Las configuraciones antiguas de Ingress a menudo apretaban demasiadas responsabilidades en un solo recurso, lo que llevaba a algunos puntos de dolor persistentes:

Configuración de plataforma y enrutamiento de aplicaciones mezclados
Características avanzadas expresadas mediante anotaciones con poca legibilidad
Expresividad limitada para protocolos no HTTP

El enfoque del Gateway API es dividir responsabilidades:

Los equipos de plataforma gestionan GatewayClass / Gateway
Los equipos de aplicación gestionan sus propios HTTPRoute

Esta separación funciona bien para la colaboración en equipo. No necesitas tocar toda la capa de ingreso solo para cambiar una ruta — las tasas de conflictos entre equipos bajan significativamente.

Empieza a Prestar Atención al Status

Más allá de spec, construye gradualmente el hábito de revisar status. Especialmente para HTTPRoute y Gateway:

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

Comienza revisando:

Si la ruta fue Accepted
Si el listener del gateway está Ready
Si se asignó correctamente una dirección

Es como revisar los resultados de un examen. No solo verifiques que lo enviaste — verifica que fue calificado y aprobado.

Resumen en Una Línea

Piensa en GatewayClass, Gateway, Listener, Route y Envoy Proxy como "quién lo gestiona, cómo se abre el ingreso, cómo se conecta cada slot, cómo se divide el tráfico y quién lo ejecuta" — y ya habrás captado el 80% de los conceptos clave.

💡 Los principiantes a menudo se lanzan directamente a los detalles de los CRD. No te apresures — primero aclara estos roles, y el YAML dejará de sentirse como conocer extraños cada vez.

Siguiente Paso

Ahora que los conceptos están en su lugar, el próximo artículo profundiza en los escenarios de enrutamiento HTTP más comunes — host, path, header y división de tráfico: 👉 HTTP Routing en la Práctica