Diagrama de Kubernetes Ingress: el flujo de tráfico, visualizado

Casi toda documentación de arquitectura tiene uno: una caja que dice «Ingress» y una flecha que apunta directamente a una fila de Pods. Parece correcto hasta que alguien que depura un 502 pregunta dónde termina TLS, qué proxy mantiene la conexión o por qué una NetworkPolicy bloquea tráfico que «pasa por el Ingress». Un buen diagrama de Kubernetes Ingress responde esas preguntas antes de que nadie las haga. En este artículo recorres la ruta de la petición salto a salto, relacionas un manifiesto Ingress mínimo con cajas y flechas, repasas los errores más comunes en las revisiones y ves cómo construir el mismo diagrama en Archboard.

La ruta de la petición, salto a salto

Sigue https://shop.example.com/api/orders desde el cliente hasta un contenedor:

1. Cliente → DNS. El cliente resuelve shop.example.com. El registro (A/AAAA, CNAME o un alias del proveedor) apunta al balanceador de carga cloud, no a un nodo.
2. DNS → balanceador de carga cloud. El cliente se conecta al balanceador. En la mayoría de los clústeres existe porque el controlador de Ingress se expone mediante un Service de type: LoadBalancer, y la integración cloud lo aprovisiona para reenviar a los node ports o directamente a los Pods del controlador.
3. Balanceador → controlador de Ingress. El controlador es una carga de trabajo normal (un Deployment o un DaemonSet) que ejecuta un proxy inverso como NGINX, Envoy, HAProxy o Traefik. Es el componente que acepta conexiones y hace de proxy de las peticiones.
4. Reglas Ingress (host/ruta). El controlador observa los objetos Ingress de su clase y los convierte en configuración del proxy. El objeto Ingress en sí no toca ni un paquete: es configuración.
5. Service (ClusterIP). Cada regla apunta a un nombre y puerto de Service. El Service aporta un nombre estable y selecciona Pods por label.
6. EndpointSlices. El control plane registra las IP de los Pods detrás de cada Service, con una condición ready para cada una, en objetos EndpointSlice. Muchos controladores, incluido ingress-nginx, leen los EndpointSlices y envían el tráfico directamente a las IP de los Pods en lugar de a la ClusterIP. El Service tiene que existir igualmente: es como el controlador encuentra esos endpoints.
7. Pods. La petición llega a un puerto de contenedor en uno de los Pods listos.

Una nota sobre ingress-nginx: el controlador comunitario ingress-nginx se retiró en marzo de 2026 y ya no recibe versiones, correcciones de errores ni parches de seguridad. Sigue siendo el ejemplo más conocido; para un clúster nuevo, elige un controlador mantenido o Gateway API.

Terminación TLS: elige un límite y dibújalo

Hay tres sitios habituales donde termina HTTPS:

El Secret debe estar en el mismo namespace que el Ingress que lo referencia. Si terminas en el balanceador y vuelves a cifrar hacia el controlador, dibuja dos segmentos TLS, no uno.

Enrutamiento por host frente a por ruta

• El enrutamiento por host envía distintos nombres de host a distintos backends (shop.example.com frente a admin.example.com). Dibuja un grupo de conexiones por host.
• El enrutamiento por ruta divide un mismo host según la ruta de la URL. Con pathType: Prefix, la coincidencia se hace por elementos de ruta separados por /, así que /api coincide con /api/orders pero no con /apiv2. Exact solo coincide con esa ruta exacta; ImplementationSpecific depende del controlador.
• Si coinciden varias rutas, gana la más larga. La mayoría de los Ingress reales combinan reglas de host y de ruta.

Dónde se aplica NetworkPolicy

NetworkPolicy filtra el tráfico de los Pods en L3/L4, y solo si el plugin de red del clúster la aplica. No sabe nada de hosts ni de rutas y no se asocia al objeto Ingress. En el diagrama, el salto que gobierna es Pods del controlador → Pods de la aplicación. Si el namespace de la aplicación tiene una política default-deny de entrada, añade otra que permita tráfico desde el namespace del controlador, por ejemplo con un namespaceSelector sobre kubernetes.io/metadata.name: ingress-nginx. El salto balanceador → controlador lo gobiernan las reglas de firewall del cloud y las políticas que haya en el namespace del controlador.

Varias clases de Ingress

Los clústeres a menudo ejecutan más de un controlador: uno público y otro interno, o uno viejo y otro nuevo durante una migración. Cada controlador reclama una IngressClass y cada Ingress elige una con spec.ingressClassName. Una clase puede marcarse como predeterminada con la anotación ingressclass.kubernetes.io/is-default-class: "true". Dale a cada controlador su propio camino desde su propio balanceador y etiqueta cada Ingress con su clase; si no, quien lea el diagrama supondrá que un único proxy lo gestiona todo.

Gateway API, en breve

Gateway API (gateway.networking.k8s.io) es la alternativa más reciente, orientada a roles: una GatewayClass describe la implementación, un Gateway define los listeners y TLS (normalmente a cargo del equipo de plataforma) y las HTTPRoutes llevan las reglas de enrutamiento (normalmente a cargo de los equipos de aplicación). Su enrutamiento HTTP principal es GA desde la v1.0 de 2023. La API Ingress sigue siendo GA y tiene soporte, pero está congelada: no recibe funciones nuevas. El diagrama apenas cambia: el Gateway ocupa el lugar del listener del controlador y las HTTPRoutes el de las reglas Ingress.

Un Ingress mínimo, mapeado al diagrama de Kubernetes Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - shop.example.com
      secretName: shop-example-com-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: orders-api
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: storefront
                port:
                  number: 80

/api/orders coincide con ambas rutas; /api es más larga, así que la petición va a orders-api.

Errores comunes

• Dibujar el Ingress como si fuera el proxy. LB → Ingress → Pods se lee como si el Ingress fuera un Pod. El proxy es el controlador; el Ingress es la configuración que lee. Pon el controlador en la ruta de datos y cuelga el Ingress de él con una conexión discontinua.
• Omitir el Service. Los backends de un Ingress referencian Services, no Pods. Aunque el tráfico vaya directo a las IP de los Pods, lo que se rompe cuando los labels se desalinean es el selector del Service, así que déjalo en el diagrama.
• Sin límite TLS. Si el diagrama no muestra dónde termina HTTPS, nadie puede saber si el tráfico dentro de la VPC va en texto plano.
• Una NetworkPolicy flotando. Una política sin conexión con el salto que gobierna no explica nada.

Cómo construirlo en Archboard

El pack Kubernetes de Archboard tiene nodos de primera clase con puertos para los objetos anteriores, incluidos IngressClass, Gateway y Route, y el pack Network cubre el DNS y el balanceador de carga. La versión terminada es el diagrama de abajo, y Abrir en Archboard lo copia en tu espacio de trabajo; /examples/kubernetes-ingress-flow es un boceto más pequeño de Ingress → Service → Pods. Para construirlo por tu cuenta:

1. Crea un diagrama y coloca un cliente (una Box o un Icon de Core, o una Person de C4), y después un nodo DNS y un nodo de balanceador del pack Network.
2. Añade un marco Namespace llamado ingress-nginx con un Deployment y un Pod para el controlador. La conexión desde el balanceador va a este Pod, porque es el proxy.
3. Añade un segundo marco Namespace llamado shop. Dentro, coloca el Ingress, un Secret (shop-example-com-tls) y dos nodos Service, orders-api y storefront, cada uno conectado a un Deployment y a un Pod.
4. Conecta los puertos a lo largo de la ruta de datos: cliente → DNS → balanceador → Pod del controlador → cada Service (etiqueta las conexiones /api y /) → Pods. Etiqueta las conexiones Service → Pod como «EndpointSlices» para que se vea cómo llega el tráfico a los Pods.
5. Conecta el controlador al Ingress con una conexión discontinua «observa», y el Secret al Ingress.
6. Añade un nodo NetworkPolicy en el marco shop y conéctalo al salto controlador → aplicación que permite.
7. Marca el límite TLS con un Frame o una Box de Core alrededor del segmento cifrado, indicando dónde termina.
8. Pega el YAML del Ingress en un bloque Markdown en el canvas, junto a las cajas que describe.

El plan Free permite 15 nodos de diagrama por diagrama, más 150 notas y textos. La construcción completa de arriba usa 18, así que quita los tres nodos Deployment, incluido el del controlador, y conecta los Services directamente a los Pods; la ruta del tráfico se mantiene. Exporta como SVG o PNG (con marca de agua en Free) o como JSON estructurado para guardarlo junto a tus manifiestos. Para la vista completa del clúster, consulta /examples/kubernetes-microservices y Archboard para Kubernetes. La referencia oficial es la documentación de Kubernetes sobre Ingress.

Preguntas frecuentes

¿El Ingress va dentro del namespace de la aplicación? Sí. Ingress es un objeto con namespace y solo puede referenciar Services y Secrets TLS de su propio namespace. El controlador suele ejecutarse en un namespace aparte.

¿El tráfico pasa por la ClusterIP del Service? Depende del controlador. Muchos hacen de proxy directamente a las IP de los Pods a partir de los EndpointSlices. Dibuja el Service de todos modos y etiqueta la conexión.

¿Ingress o Gateway API para un clúster nuevo? Gateway API, si tu controlador la soporta: la API Ingress está congelada. El método para el diagrama es el mismo.

Empieza gratis — un asiento, sin tarjeta de crédito