Aurora Libros ja es construeix i es desplega sola, però continua vivint en una màquina. Si aquesta màquina s'apaga, la llibreria desapareix d'internet. Aquesta lliçó munta el teu primer clúster amb Docker Swarm: l'orquestració més propera al que ja saps, perquè parla compose.yaml i comandes docker.

1. Què resol un orquestrador
2. Arquitectura de Swarm: managers, workers i Raft
3. L'estat desitjat i el bucle de reconciliació
4. Muntar el clúster: init, join i ports
5. Gestionar nodes: promoure, degradar i drenar
6. Serveis i tasques
7. Rèpliques davant del mode global
8. Escalat i restriccions d'ubicació
9. Xarxes overlay: VXLAN entre nodes
10. La malla d'encaminament
11. Stacks: el compose.yaml que ja tens
12. La secció deploy completa
13. Secrets i configs natius de Swarm
14. Aurora Libros en un clúster de tres nodes
15. Swarm el 2026: quan continua sent l'elecció

Advertència. Un clúster multiplica les decisions de xarxa, emmagatzematge i control d'accés: els ports entre nodes, el xifratge del trànsit intern i la ubicació de les dades persistents s'han d'acordar amb el responsable d'infraestructura i de seguretat de la teva organització abans de portar res a producció.

Un orquestrador aporta tres coses que Compose en una sola màquina no pot donar per definició: planificació (decidir en quin node va cada cosa), reconciliació (mantenir l'estat desitjat passi el que passi) i xarxa entre màquines (que els contenidors es parlin encara que siguin en amfitrions diferents).

L'estat del clúster —quins serveis existeixen, quantes rèpliques, quins secrets— es replica entre els managers amb l'algorisme de consens Raft. Per acceptar un canvi cal l'acord de la majoria, el quòrum, que és (N/2) + 1.

D'aquí surt la regla del nombre senar, que no és superstició sinó aritmètica:

La fila dels dos managers és la que sorprèn: afegir un segon manager empitjora la disponibilitat, perquè necessites tots dos vius per assolir el quòrum. I hi ha una conseqüència important que convé tenir clara: perdre el quòrum no atura els contenidors en marxa, però deixa el clúster sense capacitat de decidir; no es pot escalar, ni desplegar, ni reprogramar res fins que tornin prou managers.

Aquí hi ha el canvi mental respecte de tot l'anterior. Amb docker run dones ordres; amb un orquestrador declares com vols que estigui el món i ell se n'encarrega.

El líder executa un bucle permanent: compara l'estat desitjat (el que has declarat) amb l'estat real (el que hi ha), i si difereixen crea o elimina tasques fins que coincideixin. Quan coincideixen, espera el canvi següent i torna a comparar.

docker service create --replicas 3 aurora-api no vol dir "arrenca tres contenidors": vol dir "vull que sempre n'hi hagi tres". En mates un i n'apareix un altre. Apagues un node sencer i les seves tasques renaixen als que queden. Ningú no ha executat cap comanda de reparació: el bucle simplement ha notat una diferència entre el desitjat i el real i l'ha corregida.

L'--advertise-addr és obligatori tan bon punt la màquina tingui més d'una interfície, i ometre'l és el primer error clàssic: Swarm tria una IP qualsevol —sovint la pública, o una d'una VPN— i els altres nodes no aconsegueixen arribar-hi.

Aquests tres ports causen la meitat dels problemes d'un clúster nou, i sempre pel mateix: 7946 necessita TCP i UDP, i 4789 és UDP. Un tallafocs que només obri TCP produeix el símptoma més desconcertant possible: els nodes apareixen Ready, els serveis es despleguen, però els contenidors de nodes diferents no es veuen entre ells. No obris mai el 2377 a internet: qui hi arribi amb un token es pot unir al teu clúster.

El cicle drain → manteniment → active és la rutina bàsica d'operació d'un clúster: les tasques es recol·loquen soles abans que toquis res, i ningú no es queda sense servei. Compte amb un detall: en tornar a active, les tasques no tornen soles al node; es queden on són fins al desplegament següent.

Swarm introdueix dos conceptes nous sobre el que ja coneixes:

• Servei: la declaració. "Vull tres rèpliques d'aquesta imatge amb aquesta configuració".
• Tasca: cada unitat de treball assignada a un node. Una tasca acaba sent un contenidor, i és immutable: no es modifica ni es reinicia, se substitueix per una de nova.

docker service ps és l'eina de diagnòstic principal, perquè mostra també les tasques mortes i per què van morir:

Aquesta última línia explica una història completa: la tasca 3 va morir a worker-1 amb el codi 78 que vas programar a 06-01, és a dir, configuració invàlida, i l'orquestrador la va recrear a worker-2. Sense la validació d'arrencada, aquí hi hauria un genèric exit (1).

El mode global és exactament el que necessiten els recol·lectors de mètriques i logs del mòdul 5: cada node necessita el seu cAdvisor i el seu Promtail, i vols que apareguin sols a cada màquina que afegeixis al clúster sense recordar-te'n.

La diferència entre restricció i preferència importa molt a la pràctica: una restricció impossible deixa el servei en Pending per sempre, sense cap error evident, mentre que una preferència només influeix en el repartiment. Si un servei no arrenca i docker service ps no mostra cap error, sospita d'una restricció que cap node no compleix.

La xarxa bridge de 03-05 només connecta contenidors del mateix amfitrió. Una xarxa overlay connecta contenidors de nodes diferents com si compartissin un cable.

Per dins és un túnel VXLAN: cada paquet Ethernet del contenidor s'encapsula dins d'un datagrama UDP cap al port 4789 del node destí, que el desencapsula i l'entrega. Per als contenidors, l'existència de dues màquines és invisible; continuen resolent aurora-db per DNS i parlant per la seva IP de la xarxa overlay.

El --opt encrypted mereix una decisió conscient. El trànsit VXLAN viatja en clar per defecte: si els teus nodes són en una xarxa privada d'un mateix centre de dades pot ser acceptable, però si travessen internet o una xarxa compartida, el catàleg, les consultes i les credencials que hi passin són llegibles per qualsevol amb accés al medi. És exactament el tipus de decisió que has de validar amb el teu responsable de seguretat. Compte també: el xifratge s'aplica al pla de dades, i no es pot activar ni desactivar sense recrear la xarxa.

Quan publiques un port en mode ingress (el predeterminat), tots els nodes del clúster hi escolten, fins i tot els que no executen cap rèplica d'aquell servei. El node que rep la connexió la reparteix per IPVS entre les tasques vives, siguin on siguin.

L'avantatge és enorme per al balancejador d'entrada: apunta a qualsevol node, o a tots, i no li cal saber on és res. Els inconvenients són dos i convé conèixer-los: hi ha un salt de xarxa extra quan el node que rep no té la tasca, i la IP d'origen que veu la teva aplicació és la del node, no la del client real, perquè hi ha SNAT pel mig.

El mode host és la sortida quan necessites la IP del client (registre d'accés, límits per IP, geolocalització) o l'últim gram de latència, i té un preu: obliga el balancejador extern a saber en quins nodes hi ha rèpliques, i no pots tenir dues rèpliques del mateix servei en un node, perquè xocarien al port.

Aquí arriba la recompensa de tot el mòdul 4: docker stack deploy accepta el teu compose.yaml.

El --with-registry-auth és imprescindible amb un registre d'imatges privat com ghcr.io: sense ell, el manager entén les credencials però no les reenvia als workers, i les tasques fallen amb no basic auth credentials a tots els nodes menys on vas fer docker login.

Les dues ignorades del mig canvien com dissenyes l'aplicació. Sense build, el flux obliga a passar pel registre d'imatges, cosa que és correcta en producció. I sense depends_on, la teva API ha de suportar arrencar abans que la base de dades: per això vas implementar el reintent amb backoff a 04-04, i per això les sondes de 06-01 retornen 503 mentre les dependències no hi siguin.

Un matís que separa reservations de limits i que a Compose no existia: a Swarm, les reserves afecten la planificació. El planificador suma les reserves de les tasques ja ubicades a cada node i només en col·loca una de nova on càpiga. Reservar de més deixa nodes buits amb serveis en Pending; reservar de menys amuntega tasques fins que el node es queda sense memòria. Els números mesurats de 06-01 són just el que necessites aquí.

Els secrets viatgen als nodes xifrats per TLS mutu, es desen xifrats a l'estat Raft i es munten en un tmpfs que no toca mai el disc; l'exercici 3 ho comprova dimensió per dimensió. A més, un secret és immutable: no es pot modificar. Rotar-lo consisteix a crear-ne un de nou amb un altre nom, actualitzar el servei amb --secret-rm i --secret-add i eliminar el vell. És incòmode expressament: força que la rotació sigui un desplegament traçable i no un canvi silenciós.

Els configs funcionen igual però sense xifratge en repòs, i són la via natural per a init.sql, nginx.conf o prometheus.yml: fitxers de configuració que han d'arribar a tots els nodes sense haver-los de copiar a mà.

Advertència sobre les dades. La constraint d'aurora-db és un pedaç, no una solució. Els volums locals no viatgen: si worker-1 mor, Swarm recrearà la tasca de PostgreSQL en un altre node i hi trobarà un volum buit, amb la qual cosa el catàleg desapareix. Un clúster de debò necessita emmagatzematge de xarxa (NFS, iSCSI, Ceph, un volum de bloc del proveïdor de núvol) o una base de dades gestionada fora del clúster. Discuteix-ho amb el teu responsable d'infraestructura abans de posar-hi dades reals: no és un detall de configuració, és una decisió d'arquitectura.

Swarm continua inclòs a Docker Engine i mantingut, però és minoritari: la indústria va estandarditzar Kubernetes, i allà hi ha els proveïdors gestionats, les eines i la major part de la documentació.

La comparació detallada la faràs a 07-02. El que sí que convé retenir: gairebé tot el d'aquesta lliçó —estat desitjat, reconciliació, serveis i rèpliques, xarxa entre nodes, secrets muntats com a fitxers, actualitzacions progressives— és exactament el mateix model mental que faràs servir a Kubernetes, amb altres noms. Swarm no ha estat una desviació: ha estat la introducció senzilla al mateix problema.

• Dos managers. Empitjora la disponibilitat respecte d'un. Sempre 1, 3, 5 o 7.
• Oblidar --advertise-addr. Amb diverses interfícies, Swarm tria malament i el clúster no es forma. Posa-ho sempre explícit.
• Obrir només TCP al tallafocs. El 7946 necessita UDP també i el 4789 és UDP pur. El símptoma són nodes Ready amb la overlay morta.
• Esperar que build: funcioni. Swarm no construeix: publica la imatge abans i referencia-la per etiqueta o digest. I no oblidis --with-registry-auth, o les tasques fallaran a tots els nodes menys on vas fer docker login.
• Volums locals per a dades. La tasca es reprograma i el volum no la segueix. Emmagatzematge de xarxa o base de dades externa.
• Restriccions que cap node no compleix. El servei es queda en Pending sense missatge clar. Verifica-ho amb docker node inspect.
• Consell: fes servir docker service ps --no-trunc. La columna ERROR completa sol contenir la causa exacta de la fallada.
• Consell: etiqueta els nodes des del primer dia (zona, disc, dades). Reubicar serveis després és qüestió d'una restricció.

Exercici 1. Munta un clúster de tres nodes, desplega aurora-api amb tres rèpliques i demostra la reconciliació: mata un contenidor a mà i després buida un node sencer, comprovant en cada cas on reapareixen les tasques.

Exercici 2. Demostra la malla d'encaminament: publica aurora-web amb una sola rèplica, comprova que respon des dels tres nodes i esbrina des de quin s'està servint realment.

Exercici 3. Compara un secret de Swarm amb una variable d'entorn: intenta extreure'n els dos valors des de fora del contenidor amb docker inspect i des de dins amb /proc, i explica on viu físicament cadascun.

Solució 1.

Les dues proves mostren la mateixa maquinària a dues escales. En matar el contenidor, la tasca .1 es va recrear al mateix node, perquè el node continuava sa i era el lloc preferit; el 137 és el SIGKILL del teu docker kill, i l'historial amb \_ conserva l'intent fallit. En drenar worker-2, les seves dues tasques es van reubicar als altres dos nodes, i el recompte va tornar a 3/3 en uns quinze segons.

L'important és el que no vas fer: no vas executar cap comanda de reparació. Només vas declarar "en vull tres" una vegada, i el bucle de reconciliació manté aquella afirmació certa davant d'un contenidor mort, un node drenat o una màquina apagada de cop. És el mateix mecanisme que a Kubernetes governa un Deployment, i per això restart: always deixa de tenir sentit aquí: la política de reinici és del servei, no del contenidor.

Fixa't també que la tasca .2 va anar a parar a manager-1. Amb la constraint node.role==worker del compose.swarm.yaml no hi hauria pogut anar: s'hauria quedat en Pending fins que worker-2 tornés. És el compromís entre protegir els managers i tenir lloc on reprogramar.

Solució 2.

Els tres nodes responen 200 encara que només worker-2 executa la rèplica. Això és la malla d'encaminament: en publicar en mode ingress, cada node obre el port 80 i reenvia per IPVS a través de la xarxa overlay fins on siguin les tasques vives.

I aquí apareix l'efecte secundari que cal conèixer: la IP registrada és 10.0.0.2, una adreça de la xarxa ingress, no la del client real. El DNAT de la taula nat reescriu el destí i, pel camí, l'SNAT substitueix l'origen. Si Aurora Libros necessités la IP real —per limitar peticions per client o per a analítica—, hauries de publicar en mode=host, acceptant que llavors només respondrien els nodes amb rèplica i que el balancejador extern ho ha de saber.

L'avantatge compensa en la majoria dels casos: el balancejador d'entrada pot apuntar als tres nodes sense saber res d'on viu cada servei, i afegir o treure rèpliques no l'obliga a canviar la seva configuració.

Solució 3.

L'asimetria ja és total a la primera comprovació: la variable es llegeix sencera a l'especificació del servei, que qualsevol amb accés a l'API de Docker pot consultar; del secret només se'n veu el nom i el punt de muntatge.

El tmpfs de la segona línia és la clau del disseny: el secret no toca mai el disc en cap node. En aturar la tasca, el sistema de fitxers es desmunta i el valor deixa d'existir; no queda en cap capa d'imatge, ni en un volum, ni en un fitxer de log, ni en una còpia de seguretat del sistema de fitxers del node.

La fila de l'herència és la que més incidents provoca a la pràctica. Una variable d'entorn la veuen tots els subprocessos: si la teva API invoca pg_dump, un script de desplegament o qualsevol eina de tercers, aquesta contrasenya hi va amb ells, i n'hi ha prou que una llibreria registri el seu entorn en fallar —cosa que fan moltes— perquè la credencial acabi en un servei extern de gestió d'errors. El fitxer de /run/secrets/ només el llegeix qui decideix llegir-lo, que és justament el que fa el teu config.js de 06-01, una vegada, en arrencar.

Aurora Libros ja no depèn d'una màquina. Saps què aporta un orquestrador —planificació, reconciliació i xarxa entre nodes— i has muntat un clúster de Swarm amb docker swarm init --advertise-addr, tokens diferents per rol i els tres ports que cal obrir, amb el detall que costa tardes senceres: 7946 en TCP i UDP, 4789 en UDP. Entens per què els managers han de ser senars i per què dos són pitjor que un, i domines la rutina de drain → manteniment → active que permet tocar una màquina sense que ningú deixi de comprar llibres.

Has canviat de model mental: ja no dones ordres, declares un estat desitjat i un bucle el manté cert. Ho has comprovat matant un contenidor i drenant un node sencer, veient com les tasques reapareixen soles sense que executessis cap reparació. Distingeixes servei de tasca, rèpliques de mode global —el que necessiten Promtail i cAdvisor—, i saps que una restricció impossible deixa un servei en Pending mut. Has creat xarxes overlay sobre túnels VXLAN, amb la decisió conscient sobre --opt encrypted per al trànsit que travessa xarxes que no controles, i has vist la malla d'encaminament respondre des dels tres nodes amb una sola rèplica viva, juntament amb el seu preu: la IP que registra Nginx és la de la xarxa ingress, no la del client.

El compose.yaml del mòdul 4 s'ha convertit en un stack amb docker stack deploy, amb la taula del que Swarm ignora —build, depends_on, restart— i la secció deploy completa, on les reservations ja no són decoratives perquè governen la planificació. Els secrets natius han demostrat el seu avantatge de manera mesurable: invisibles a inspect, absents de /proc/<pid>/environ, muntats en un tmpfs que no toca mai el disc i sense heretar-se als subprocessos, mentre el patró _FILE de 06-01 continua funcionant sense tocar ni una línia de codi. I queda anotada en vermell la limitació real: els volums locals no viatgen, així que aurora-db està ancorada per una etiqueta de node i això és un pedaç que cal substituir per emmagatzematge de xarxa o una base de dades gestionada abans de posar-hi dades reals.

A la lliçó següent, Introducció a Kubernetes, canvies d'eina però no d'idees. Veuràs el pla de control amb el seu kube-apiserver, el seu etcd i el seu planificador, els objectes fonamentals —Pod, Deployment, Service, Ingress, ConfigMap, Secret, PVC— amb el seu YAML mínim comentat, el paper central de les etiquetes i els selectors, la taula de kubectl traduïda a les comandes de Docker que ja domines, i muntaràs un clúster local amb kind per fer els teus primers passos.