Arribem al moment que el curs porta prometent des del mòdul 1: publicar Rutas Norte a internet. Tenim cinc components desplegats, tots amb Services ClusterIP que només existeixen dins del clúster, i cap client no pot comprar un bitllet. A 04-02 vam veure que LoadBalancer resoldria el problema al preu d'un balancejador i una IP pública per servei, sense encaminament per domini ni per ruta. Aquesta lliçó presenta la resposta correcta: un únic punt d'entrada HTTP que reparteix el trànsit segons el domini i la ruta demanats. En acabar, www.rutasnorte.example servirà la botiga i api.rutasnorte.example servirà l'API, tots dos des del mateix balancejador, i sabràs distingir amb claredat entre el recurs Ingress —una regla que no fa res per si sola— i el controlador d'Ingress, el programa que la converteix en configuració real.

1. El problema: diversos serveis HTTP, un sol punt d'entrada
2. Recurs davant de controlador: la distinció essencial
3. Panorama de controladors
4. IngressClass i l'anotació heretada
5. Anatomia d'un Ingress
6. pathType: els tres valors i els casos que confonen
7. Cas pràctic: publicar la botiga i l'API
8. Encaminament per host davant d'encaminament per ruta i reescriptura
9. Anotacions del dia a dia
10. Depuració
11. Gateway API: la successora

Rutas Norte necessita publicar, com a mínim:

Amb type: LoadBalancer serien quatre balancejadors, quatre IP públiques i quatre certificats TLS gestionats per separat, multiplicat pels tres entorns. I tot i així faltaria l'essencial: un balancejador L4 no entén HTTP. No pot llegir la capçalera Host per decidir a quin servei va la petició, ni mirar la ruta, ni reescriure-la, ni afegir capçaleres. L'Ingress trasllada la decisió a capa 7:

Un balancejador, una IP, un lloc on acabar el TLS (04-05), i tots els serveis interns continuen sent ClusterIP.

Aquesta és la confusió número u de la lliçó i cal fixar-la abans d'escriure res.

El símptoma de crear un Ingress sense controlador enganya: kubectl apply respon created, kubectl get ingress el llista i el domini no respon. La pista és a la columna ADDRESS, buida per sempre.

Un controlador és, per dins, un bucle idèntic al del mòdul 1: observa l'API, llegeix els Ingress, Services i EndpointSlices, genera un fitxer de configuració (un nginx.conf, a ingress-nginx) i recarrega el seu proxy, fent servir una ServiceAccount amb permisos (03-06).

Compte amb un detall històric: existeixen dos controladors basats en NGINX. ingress-nginx és el del projecte Kubernetes; "NGINX Ingress Controller" és el de F5/NGINX Inc. Les seves anotacions no són compatibles, i moltes hores s'han perdut copiant la del controlador equivocat. Aquí fem servir ingress-nginx, el de l'addon de minikube.

Els dos Completed són Jobs (06-03) que instal·len el webhook de validació: gràcies a ell, un Ingress amb sintaxi invàlida es rebutja a l'apply en lloc de trencar la configuració del proxy.

Un clúster pot tenir diversos controladors: un de públic per a botiga-web i api-reserves, un altre d'intern per al panell d'administració. IngressClass diu quin controlador atén quin Ingress.

A l'Ingress es referencia amb el camp spec.ingressClassName: nginx. Abans de Kubernetes 1.18 això es feia amb l'anotació kubernetes.io/ingress.class: "nginx", que continua funcionant en molts controladors per compatibilitat però està desaconsellada i desapareixerà. Veuràs moltíssims exemples a internet amb ella: són antics. Fes servir ingressClassName.

Si no indiques classe i cap no està marcada com a predeterminada, cap controlador no recull l'Ingress: ADDRESS buit i silenci.

Restriccions que provoquen la majoria de les fallades:

• L'Ingress i els Services han de ser al mateix namespace. Un Ingress de rutas-norte-pro no pot apuntar a un Service de rutas-norte-dev: és disseny de seguretat, no limitació tècnica.
• El port pot ser number o name, però no tots dos. Referenciar-lo per nom sobreviu a un canvi de número.
• host accepta un comodí al primer nivell (*.rutasnorte.example), que casa api.rutasnorte.example però no www.api.rutasnorte.example ni el domini nu. Les regles sense host casen qualsevol domini: útil per a proves per IP, perillós en producció.

defaultBackend és la destinació d'allò que no casa res: sense ell, el controlador retorna el seu 404 genèric; amb ell, un client que escrigui malament el subdomini acaba a la botiga.

pathType és obligatori des de networking.k8s.io/v1 i la seva semàntica sorprèn gairebé tothom.

La clau de Prefix és a les tres paraules "per segments de ruta". /api no és un prefix de caràcters: casa /api i /api/elquesigui, però no casa /apificat.

Regla de desempat quan diverses casen: guanya la ruta més llarga, sense importar el pathType.

Una petició a /api/reserves casa les dues regles, i va a api-reserves perquè /api és més llarga que /. Aquest ordre per longitud, i no per posició al YAML, evita l'error de "he posat la regla més específica a dalt i no funciona".

Un sol Ingress publica els dos dominis de Rutas Norte.

Fixa't en el que no cal fer: no es canvien els Services a NodePort ni a LoadBalancer. Continuen sent ClusterIP, perquè qui els parla és el controlador, que és dins del clúster.

Aplicació i comprovació:

ADDRESS amb la IP del node significa que el controlador ha recollit l'Ingress. Aquest camp triga entre uns segons i un parell de minuts a aparèixer; si continua buit passats cinc, alguna cosa va malament (apartat 10).

Els clients de Rutas Norte ja poden arribar a la plataforma: és la primera vegada al curs que el trànsit entra de debò des de fora del clúster. Que l'encaminament es fa per la capçalera Host i no per la IP ho comprovarem a l'exercici 1: mateixa IP, mateix port, resultats diferents segons el Host. Això és encaminament L7.

L'alternativa als dos dominis és servir l'API sota /api del domini principal.

Rutas Norte fa servir totes dues: api.rutasnorte.example per a les agències externes, i www.rutasnorte.example/api perquè la SPA no hagi de lidiar amb CORS.

El problema: la SPA demana /api/reserves però api-reserves espera /reserves; sense reescriptura rebria /api/reserves i retornaria 404.

Com llegir aquesta expressió: /api casa el prefix literal; (/|$) és el grup 1 (una barra o el final de la cadena, perquè casin tant /api com /api/...); (.*) és el grup 2, tot el que vingui després; i rewrite-target: /$2 reconstrueix la ruta amb només el grup 2.

I l'avís: pathType passa a ImplementationSpecific perquè estem fent servir una expressió regular, cosa que Prefix no contempla. Aquell Ingress no és portable a Traefik ni a l'ALB d'AWS. És un compromís conscient.

Advertència molt repetida: la reescriptura afecta la ruta de la petició, no les URL que l'aplicació genera al seu HTML o a les seves redireccions. Si api-reserves respon Location: /reserves/33, el navegador hi anirà i no a /api/reserves/33. Les aplicacions servides sota un prefix l'han de conèixer (típicament amb una variable BASE_PATH).

Les anotacions són el mecanisme pel qual cada controlador exposa les seves funcions; aquestes són les d'ingress-nginx que es fan servir en qualsevol plataforma real.

Exemple aplicat als pics de trànsit de ponts i vacances:

Dues advertències importants:

• configuration-snippet està desactivat per defecte a les versions recents d'ingress-nginx per seguretat (permetia injectar configuració arbitrària del proxy des de qualsevol namespace). Cal habilitar-lo al ConfigMap del controlador, i convé pensar-s'ho dues vegades.
• La limitació s'aplica per rèplica del controlador. Amb tres rèpliques, un límit de 20 rps és a la pràctica 60.

Els ajustos globals (capçaleres per defecte, mides de memòria intermèdia, format de log) no van en anotacions sinó al ConfigMap del controlador, ingress-nginx-controller del namespace ingress-nginx.

La primera parada sempre:

El que cal mirar, en aquest ordre: Address emplenat (algú ha recollit l'Ingress); Ingress Class correcta; els backends amb IP de pod entre parèntesis —si posa <error: endpoints "botiga-web" not found> o una llista buida, el problema no és de l'Ingress, és el Service, i tornes al diagnòstic de 02-05—; i Events amb Sync, que confirma que el controlador va aplicar la configuració.

Els camps entre claudàtors són or: [rutas-norte-pro-api-reserves-http] és l'upstream triat, i 10.244.0.31:3000 el pod concret. Si l'upstream apareix buit, cap regla no ha casat.

La distinció mereix memoritzar-se: 503 és que no hi ha a qui enviar (endpoints buits) i 502 és que hi ha a qui enviar però no respon bé. Capes diferents.

Veure el nginx.conf que el controlador ha generat a partir del teu Ingress tanca qualsevol discussió sobre què està passant: kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- cat /etc/nginx/nginx.conf | grep -A5 "server_name api.rutasnorte.example".

L'Ingress ha envellit malament. La seva especificació és tan mínima que tot allò interessant va acabar en anotacions propietàries: reescriptura, CORS, limitació, capçaleres... Res d'això no és portable. A més barreja responsabilitats: qui administra la infraestructura i qui publica una aplicació editen el mateix objecte.

La Gateway API (gateway.networking.k8s.io) és la resposta oficial, ja estable per als seus recursos principals.

Avantatges concrets davant d'Ingress: separació de rols (l'equip de Rutas Norte crea el seu HTTPRoute sense tocar el punt d'entrada); funcions al model, no en anotacions —reescriptura, redirecció, capçaleres i repartiment per pesos són camps de l'API, així que el canari de 11-04 deixa de necessitar anotacions específiques—; rutes entre namespaces amb permís explícit del propietari del Gateway; i portabilitat real entre implementacions.

L'Ingress no està obsolet i continuarà funcionant molts anys: hi ha massa desplegat. Però per a una plataforma nova el 2026 val la pena avaluar la Gateway API, sobretot si ja es fa servir Istio, Cilium o Traefik. Aquí continuem amb Ingress perquè és el que et trobaràs i el que avaluen les certificacions del mòdul 12.

• Crear l'Ingress sense controlador. L'apply va bé i res no funciona. Comprova kubectl get pods -n ingress-nginx abans.
• Apuntar a un Service d'un altre namespace. No és possible. L'Ingress viu al namespace dels seus Services.
• Copiar anotacions del controlador equivocat. nginx.ingress.kubernetes.io/* és d'ingress-nginx; el de F5 fa servir nginx.org/*. No són intercanviables.
• Fer servir kubernetes.io/ingress.class. Obsoleta. Fes servir ingressClassName.
• Esperar que Prefix compari caràcters. /api no casa /apificat. Compara segments.
• Confondre 503 amb 502. El primer és "no hi ha endpoints"; el segon, "el pod no respon bé". Diagnòstics diferents.
• Reescriure rutes sense que l'aplicació ho sàpiga. Els enllaços i redireccions que generi continuaran sense el prefix. Configura el BASE_PATH de l'aplicació.
• Oblidar que l'encaminament depèn de la capçalera Host. Provar amb curl http://IP/ sense -H 'Host: ...' donarà 404 encara que tot estigui bé.
• Consell: un Ingress per aplicació, no un de gegant per clúster. Es despleguen i es reverteixen de manera independent.
• Consell: les anotacions de temps d'espera i mida de cos són de les primeres que es necessiten en producció. Posa-les des del principi amb valors raonables en lloc d'esperar al primer 413 en un pont.

Activa l'addon ingress de minikube, crea l'Ingress que publica www.rutasnorte.example contra botiga-web i api.rutasnorte.example contra api-reserves, resol els dominis a /etc/hosts i comprova les dues rutes. Demostra a més que l'encaminament es fa per capçalera Host.

Afegeix al domini www.rutasnorte.example una ruta /api que arribi a api-reserves sense el prefix. Verifica als logs del controlador quina ruta rep realment el backend i què passa amb /apificat.

Reprodueix i diagnostica: (A) un Ingress amb ingressClassName: traefik en un clúster amb només ingress-nginx; (B) un Ingress correcte el Service del qual apunta a un selector que no casa; (C) un Ingress el backend.service.port.number del qual és 8080 quan el Service exposa el 80. Indica el símptoma exacte de cadascun i l'ordre que l'identifica.

Exercici 1

El 404 del tercer prova que la decisió es pren llegint la capçalera Host, no la IP de destinació.

Exercici 2

El client va demanar /api/salut; el backend va rebre /salut. Amb /apificat, la regex /api(/|$)(.*) sí que casaria (perquè use-regex compara caràcters, no segments) i el backend rebria /ficat — un motiu més per preferir Prefix tret que la reescriptura sigui imprescindible, i per ancorar millor l'expressió si és un problema.

Exercici 3

L'error de C és especialment freqüent: el port de l'Ingress és el del Service (port), no el del contenidor (targetPort). Confondre'ls produeix un Ingress que sembla correcte i retorna 503.

Rutas Norte ja està publicada. Entens la distinció que ordena tota la resta: el recurs Ingress és una declaració d'intencions que per si sola no fa absolutament res, i el controlador d'Ingress és el programa que l'observa, genera configuració de proxy i encamina el trànsit de debò; si falta el segon, el primer es crea sense errors i l'ADDRESS es queda buit per sempre. Coneixes el panorama de controladors, el perill de confondre ingress-nginx amb el controlador homònim de F5, i saps seleccionar el teu amb ingressClassName en lloc de l'anotació obsoleta kubernetes.io/ingress.class.

Domines l'anatomia de l'objecte: rules amb host i http.paths, backend.service.name amb el port del Service (no el del contenidor), i el defaultBackend per a allò que no casa res. Tens clar que pathType: Prefix compara segments de ruta i no caràcters —/api no casa /apificat— que Exact distingeix la barra final i les majúscules, que ImplementationSpecific és la porta a les expressions regulars al preu de la portabilitat, i que quan diverses regles casen guanya la més llarga.

Sobretot, has fet la feina: vas activar l'addon ingress, vas publicar www.rutasnorte.example contra botiga-web i api.rutasnorte.example contra api-reserves amb un sol Ingress i un sol punt d'entrada, vas resoldre els dominis amb /etc/hosts i vas demostrar que el repartiment es fa llegint la capçalera Host. Vas afegir la ruta /api amb rewrite-target entenent grup a grup l'expressió regular, i coneixes les anotacions que es necessiten en producció des del primer dia: mida de cos, temps d'espera, limitació de peticions i capçaleres de seguretat. Saps depurar amb describe, amb els logs del controlador i, en últim extrem, llegint el nginx.conf generat, i distingeixes sense dubtar un 503 (sense endpoints) d'un 502 (backend que no respon). I saps que la Gateway API és la successora, amb separació de rols i funcions al model en lloc d'en anotacions.

Queda un problema greu, i és dels que no admeten demora: tot això va per HTTP en clar. Les dades personals que els clients escriuen per reservar —nom, DNI, telèfon, correu— i les dades que viatgen cap a la passarel·la de pagaments estan recorrent internet sense xifrar. A 04-05 posarem HTTPS als dos dominis: primer amb un certificat autosignat per a desenvolupament, i després amb cert-manager emetent i renovant automàticament certificats de Let's Encrypt mitjançant els desafiaments ACME HTTP-01 i DNS-01.