Llegamos al momento que el curso lleva prometiendo desde el módulo 1: publicar Rutas Norte en internet. Tenemos cinco componentes desplegados, todos con Services ClusterIP que solo existen dentro del clúster, y ningún cliente puede comprar un billete. En 04-02 vimos que LoadBalancer resolvería el problema al precio de un balanceador y una IP pública por servicio, sin enrutado por dominio ni por ruta. Esta lección presenta la respuesta correcta: un único punto de entrada HTTP que reparte el tráfico según el dominio y la ruta pedidos. Al terminar, www.rutasnorte.example servirá la tienda y api.rutasnorte.example servirá la API, ambos desde el mismo balanceador, y sabrás distinguir con claridad entre el recurso Ingress —una regla que no hace nada por sí sola— y el controlador de Ingress, el programa que la convierte en configuración real.

1. El problema: varios servicios HTTP, un solo punto de entrada
2. Recurso frente a controlador: la distinción esencial
3. Panorama de controladores
4. IngressClass y la anotación heredada
5. Anatomía de un Ingress
6. pathType: los tres valores y los casos que confunden
7. Caso práctico: publicar la tienda y la API
8. Enrutado por host frente a enrutado por ruta y reescritura
9. Anotaciones del día a día
10. Depuración
11. Gateway API: la sucesora

Rutas Norte necesita publicar, como mínimo:

Con type: LoadBalancer serían cuatro balanceadores, cuatro IPs públicas y cuatro certificados TLS gestionados por separado, multiplicado por los tres entornos. Y aun así faltaría lo esencial: un balanceador L4 no entiende HTTP. No puede leer la cabecera Host para decidir a qué servicio va la petición, ni mirar la ruta, ni reescribirla, ni añadir cabeceras. El Ingress traslada la decisión a capa 7:

Un balanceador, una IP, un sitio donde terminar el TLS (04-05), y todos los servicios internos siguen siendo ClusterIP.

Esta es la confusión número uno de la lección y hay que fijarla antes de escribir nada.

El síntoma de crear un Ingress sin controlador engaña: kubectl apply responde created, kubectl get ingress lo lista y el dominio no responde. La pista está en la columna ADDRESS, vacía para siempre.

Un controlador es, por dentro, un bucle idéntico al del módulo 1: observa la API, lee los Ingress, Services y EndpointSlices, genera un fichero de configuración (un nginx.conf, en ingress-nginx) y recarga su proxy, usando una ServiceAccount con permisos (03-06).

Cuidado con un detalle histórico: existen dos controladores basados en NGINX. ingress-nginx es el del proyecto Kubernetes; "NGINX Ingress Controller" es el de F5/NGINX Inc. Sus anotaciones no son compatibles, y muchas horas se han perdido copiando la del controlador equivocado. Aquí usamos ingress-nginx, el del addon de minikube.

Los dos Completed son Jobs (06-03) que instalan el webhook de validación: gracias a él, un Ingress con sintaxis inválida se rechaza en el apply en lugar de romper la configuración del proxy.

Un clúster puede tener varios controladores: uno público para tienda-web y api-reservas, otro interno para el panel de administración. IngressClass dice qué controlador atiende a qué Ingress.

En el Ingress se referencia con el campo spec.ingressClassName: nginx. Antes de Kubernetes 1.18 esto se hacía con la anotación kubernetes.io/ingress.class: "nginx", que sigue funcionando en muchos controladores por compatibilidad pero está desaconsejada y desaparecerá. Verás muchísimos ejemplos en internet con ella: son antiguos. Usa ingressClassName.

Si no indicas clase y ninguna está marcada como predeterminada, ningún controlador recoge el Ingress: ADDRESS vacío y silencio.

Restricciones que provocan la mayoría de los fallos:

• El Ingress y los Services deben estar en el mismo namespace. Un Ingress de rutas-norte-pro no puede apuntar a un Service de rutas-norte-dev: es diseño de seguridad, no limitación técnica.
• El port puede ser number o name, pero no ambos. Referenciarlo por nombre sobrevive a un cambio de número.
• host acepta un comodín en el primer nivel (*.rutasnorte.example), que casa api.rutasnorte.example pero no www.api.rutasnorte.example ni el dominio desnudo. Las reglas sin host casan cualquier dominio: útil para pruebas por IP, peligroso en producción.

defaultBackend es el destino de lo que no casa nada: sin él, el controlador devuelve su 404 genérico; con él, un cliente que escriba mal el subdominio acaba en la tienda.

pathType es obligatorio desde networking.k8s.io/v1 y su semántica sorprende a casi todo el mundo.

La clave de Prefix está en las tres palabras "por segmentos de ruta". /api no es un prefijo de caracteres: casa /api y /api/loquesea, pero no casa /apificado.

Regla de desempate cuando varias casan: gana la ruta más larga, sin importar el pathType.

Una petición a /api/reservas casa las dos reglas, y va a api-reservas porque /api es más larga que /. Este orden por longitud, y no por posición en el YAML, evita el error de "he puesto la regla más específica arriba y no funciona".

Un solo Ingress publica los dos dominios de Rutas Norte.

Fíjate en lo que no hay que hacer: no se cambian los Services a NodePort ni a LoadBalancer. Siguen siendo ClusterIP, porque quien les habla es el controlador, que está dentro del clúster.

Aplicación y comprobación:

ADDRESS con la IP del nodo significa que el controlador ha recogido el Ingress. Ese campo tarda entre unos segundos y un par de minutos en aparecer; si sigue vacío pasados cinco, algo va mal (apartado 10).

Los clientes de Rutas Norte ya pueden llegar a la plataforma: es la primera vez en el curso que el tráfico entra de verdad desde fuera del clúster. Que el enrutado se hace por la cabecera Host y no por la IP lo comprobaremos en el ejercicio 1: misma IP, mismo puerto, resultados distintos según el Host. Eso es enrutado L7.

La alternativa a los dos dominios es servir la API bajo /api del dominio principal.

Rutas Norte usa ambas: api.rutasnorte.example para las agencias externas, y www.rutasnorte.example/api para que la SPA no tenga que lidiar con CORS.

El problema: la SPA pide /api/reservas pero api-reservas espera /reservas; sin reescritura recibiría /api/reservas y devolvería 404.

Cómo leer esa expresión: /api casa el prefijo literal; (/|$) es el grupo 1 (una barra o el final de la cadena, para que casen tanto /api como /api/...); (.*) es el grupo 2, todo lo que venga después; y rewrite-target: /$2 reconstruye la ruta con solo el grupo 2.

Y el aviso: pathType pasa a ImplementationSpecific porque estamos usando una expresión regular, algo que Prefix no contempla. Ese Ingress no es portable a Traefik ni al ALB de AWS. Es un compromiso consciente.

Advertencia muy repetida: la reescritura afecta a la ruta de la petición, no a las URLs que la aplicación genera en su HTML o en sus redirecciones. Si api-reservas responde Location: /reservas/33, el navegador irá ahí y no a /api/reservas/33. Las aplicaciones servidas bajo un prefijo deben conocerlo (típicamente con una variable BASE_PATH).

Las anotaciones son el mecanismo por el que cada controlador expone sus funciones; estas son las de ingress-nginx que se usan en cualquier plataforma real.

Ejemplo aplicado a los picos de tráfico de puentes y vacaciones:

Dos advertencias importantes:

• configuration-snippet está desactivado por defecto en las versiones recientes de ingress-nginx por seguridad (permitía inyectar configuración arbitraria del proxy desde cualquier namespace). Hay que habilitarlo en el ConfigMap del controlador, y conviene pensarlo dos veces.
• La limitación se aplica por réplica del controlador. Con tres réplicas, un límite de 20 rps es en la práctica 60.

Los ajustes globales (cabeceras por defecto, tamaños de búfer, formato de log) no van en anotaciones sino en el ConfigMap del controlador, ingress-nginx-controller del namespace ingress-nginx.

La primera parada siempre:

Lo que hay que mirar, en este orden: Address relleno (alguien ha recogido el Ingress); Ingress Class correcta; los backends con IPs de pod entre paréntesis —si pone <error: endpoints "tienda-web" not found> o una lista vacía, el problema no es del Ingress, es el Service, y vuelves al diagnóstico de 02-05—; y Events con Sync, que confirma que el controlador aplicó la configuración.

Los campos entre corchetes son oro: [rutas-norte-pro-api-reservas-http] es el upstream elegido, y 10.244.0.31:3000 el pod concreto. Si el upstream aparece vacío, ninguna regla casó.

La distinción merece memorizarse: 503 es que no hay a quién enviar (endpoints vacíos) y 502 es que hay a quién enviar pero no responde bien. Capas distintas.

Ver el nginx.conf que el controlador ha generado a partir de tu Ingress cierra cualquier discusión sobre qué está pasando: kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- cat /etc/nginx/nginx.conf | grep -A5 "server_name api.rutasnorte.example".

El Ingress ha envejecido mal. Su especificación es tan mínima que todo lo interesante acabó en anotaciones propietarias: reescritura, CORS, limitación, cabeceras... Nada de eso es portable. Además mezcla responsabilidades: quien administra la infraestructura y quien publica una aplicación editan el mismo objeto.

La Gateway API (gateway.networking.k8s.io) es la respuesta oficial, ya estable para sus recursos principales.

Ventajas concretas frente a Ingress: separación de roles (el equipo de Rutas Norte crea su HTTPRoute sin tocar el punto de entrada); funciones en el modelo, no en anotaciones —reescritura, redirección, cabeceras y reparto por pesos son campos de la API, así que el canary de 11-04 deja de necesitar anotaciones específicas—; rutas entre namespaces con permiso explícito del propietario del Gateway; y portabilidad real entre implementaciones.

El Ingress no está obsoleto y seguirá funcionando muchos años: hay demasiado desplegado. Pero para una plataforma nueva en 2026 merece la pena evaluar la Gateway API, sobre todo si ya se usa Istio, Cilium o Traefik. Aquí seguimos con Ingress porque es lo que te vas a encontrar y lo que evalúan las certificaciones del módulo 12.

• Crear el Ingress sin controlador. El apply va bien y nada funciona. Comprueba kubectl get pods -n ingress-nginx antes.
• Apuntar a un Service de otro namespace. No es posible. El Ingress vive en el namespace de sus Services.
• Copiar anotaciones del controlador equivocado. nginx.ingress.kubernetes.io/* es de ingress-nginx; el de F5 usa nginx.org/*. No son intercambiables.
• Usar kubernetes.io/ingress.class. Obsoleta. Usa ingressClassName.
• Esperar que Prefix compare caracteres. /api no casa /apificado. Compara segmentos.
• Confundir 503 con 502. El primero es "no hay endpoints"; el segundo, "el pod no responde bien". Diagnósticos distintos.
• Reescribir rutas sin que la aplicación lo sepa. Los enlaces y redirecciones que genere seguirán sin el prefijo. Configura el BASE_PATH de la aplicación.
• Olvidar que el enrutado depende de la cabecera Host. Probar con curl http://IP/ sin -H 'Host: ...' dará 404 aunque todo esté bien.
• Consejo: un Ingress por aplicación, no uno gigante por clúster. Se despliegan y se revierten de forma independiente.
• Consejo: las anotaciones de tiempo de espera y tamaño de cuerpo son de las primeras que se necesitan en producción. Ponlas desde el principio con valores razonables en lugar de esperar al primer 413 en un puente.

Activa el addon ingress de minikube, crea el Ingress que publica www.rutasnorte.example contra tienda-web y api.rutasnorte.example contra api-reservas, resuelve los dominios en /etc/hosts y comprueba las dos rutas. Demuestra además que el enrutado se hace por cabecera Host.

Añade al dominio www.rutasnorte.example una ruta /api que llegue a api-reservas sin el prefijo. Verifica en los logs del controlador qué ruta recibe realmente el backend y qué ocurre con /apificado.

Reproduce y diagnostica: (A) un Ingress con ingressClassName: traefik en un clúster con solo ingress-nginx; (B) un Ingress correcto cuyo Service apunta a un selector que no casa; (C) un Ingress cuyo backend.service.port.number es 8080 cuando el Service expone el 80. Indica el síntoma exacto de cada uno y el comando que lo identifica.

Ejercicio 1

El 404 del tercero prueba que la decisión se toma leyendo la cabecera Host, no la IP de destino.

Ejercicio 2

El cliente pidió /api/salud; el backend recibió /salud. Con /apificado, la regex /api(/|$)(.*) sí casaría (porque use-regex compara caracteres, no segmentos) y el backend recibiría /ficado — un motivo más para preferir Prefix salvo cuando la reescritura sea imprescindible, y para anclar mejor la expresión si es un problema.

Ejercicio 3

El error de C es especialmente frecuente: el port del Ingress es el del Service (port), no el del contenedor (targetPort). Confundirlos produce un Ingress que parece correcto y devuelve 503.

Rutas Norte ya está publicada. Entiendes la distinción que ordena todo lo demás: el recurso Ingress es una declaración de intenciones que por sí sola no hace absolutamente nada, y el controlador de Ingress es el programa que la observa, genera configuración de proxy y enruta el tráfico de verdad; si falta el segundo, el primero se crea sin errores y el ADDRESS se queda vacío para siempre. Conoces el panorama de controladores, el peligro de confundir ingress-nginx con el controlador homónimo de F5, y sabes seleccionar el tuyo con ingressClassName en lugar de la anotación obsoleta kubernetes.io/ingress.class.

Dominas la anatomía del objeto: rules con host y http.paths, backend.service.name con el puerto del Service (no el del contenedor), y el defaultBackend para lo que no casa nada. Tienes claro que pathType: Prefix compara segmentos de ruta y no caracteres —/api no casa /apificado— que Exact distingue la barra final y las mayúsculas, que ImplementationSpecific es la puerta a las expresiones regulares al precio de la portabilidad, y que cuando varias reglas casan gana la más larga.

Sobre todo, has hecho el trabajo: activaste el addon ingress, publicaste www.rutasnorte.example contra tienda-web y api.rutasnorte.example contra api-reservas con un solo Ingress y un solo punto de entrada, resolviste los dominios con /etc/hosts y demostraste que el reparto se hace leyendo la cabecera Host. Añadiste la ruta /api con rewrite-target entendiendo grupo a grupo la expresión regular, y conoces las anotaciones que se necesitan en producción desde el primer día: tamaño de cuerpo, tiempos de espera, limitación de peticiones y cabeceras de seguridad. Sabes depurar con describe, con los logs del controlador y, en último extremo, leyendo el nginx.conf generado, y distingues sin dudar un 503 (sin endpoints) de un 502 (backend que no responde). Y sabes que la Gateway API es la sucesora, con separación de roles y funciones en el modelo en lugar de en anotaciones.

Queda un problema grave, y es de los que no admiten demora: todo esto va por HTTP en claro. Los datos personales que los clientes escriben para reservar —nombre, DNI, teléfono, correo— y los datos que viajan hacia la pasarela de pagos están recorriendo internet sin cifrar. En 04-05 pondremos HTTPS en los dos dominios: primero con un certificado autofirmado para desarrollo, y después con cert-manager emitiendo y renovando automáticamente certificados de Let's Encrypt mediante los desafíos ACME HTTP-01 y DNS-01.