Aurora Libros ya se construye y se despliega sola, pero sigue viviendo en una máquina. Si esa máquina se apaga, la librería desaparece de internet. Esta lección monta tu primer clúster con Docker Swarm: la orquestación más cercana a lo que ya sabes, porque habla compose.yaml y comandos docker.

1. Qué resuelve un orquestador
2. Arquitectura de Swarm: managers, workers y Raft
3. El estado deseado y el bucle de reconciliación
4. Montar el clúster: init, join y puertos
5. Gestionar nodos: promover, degradar y drenar
6. Servicios y tareas
7. Réplicas frente a modo global
8. Escalado y restricciones de ubicación
9. Redes overlay: VXLAN entre nodos
10. La malla de enrutamiento
11. Stacks: el compose.yaml que ya tienes
12. La sección deploy completa
13. Secretos y configs nativos de Swarm
14. Aurora Libros en un clúster de tres nodos
15. Swarm en 2026: cuándo sigue siendo la elección

Advertencia. Un clúster multiplica las decisiones de red, almacenamiento y control de acceso: los puertos entre nodos, el cifrado del tráfico interno y la ubicación de los datos persistentes deben acordarse con el responsable de infraestructura y de seguridad de tu organización antes de llevar nada a producción.

Un orquestador aporta tres cosas que Compose en una sola máquina no puede dar por definición: planificación (decidir en qué nodo va cada cosa), reconciliación (mantener el estado deseado pase lo que pase) y red entre máquinas (que los contenedores se hablen aunque estén en anfitriones distintos).

El estado del clúster —qué servicios existen, cuántas réplicas, qué secretos— se replica entre los managers con el algoritmo de consenso Raft. Para aceptar un cambio hace falta el acuerdo de la mayoría, el quórum, que es (N/2) + 1.

De ahí sale la regla del número impar, que no es superstición sino aritmética:

La fila de los dos managers es la que sorprende: añadir un segundo manager empeora la disponibilidad, porque necesitas los dos vivos para alcanzar el quórum. Y hay una consecuencia importante que conviene tener clara: perder el quórum no para los contenedores en marcha, pero deja el clúster sin capacidad de decidir; no se puede escalar, ni desplegar, ni reprogramar nada hasta que vuelvan suficientes managers.

Aquí está el cambio mental respecto a todo lo anterior. Con docker run das órdenes; con un orquestador declaras cómo quieres que esté el mundo y él se encarga.

El líder ejecuta un bucle permanente: compara el estado deseado (lo que has declarado) con el estado real (lo que hay), y si difieren crea o elimina tareas hasta que coincidan. Cuando coinciden, espera al siguiente cambio y vuelve a comparar.

docker service create --replicas 3 aurora-api no significa "arranca tres contenedores": significa "quiero que siempre haya tres". Mata uno y aparece otro. Apaga un nodo entero y sus tareas renacen en los que quedan. Nadie ha ejecutado un comando de reparación: el bucle simplemente ha notado una diferencia entre lo deseado y lo real y la ha corregido.

El --advertise-addr es obligatorio en cuanto la máquina tenga más de una interfaz, y omitirlo es el primer error clásico: Swarm elige una IP cualquiera —a menudo la pública, o una de una VPN— y los demás nodos no consiguen alcanzarla.

Estos tres puertos causan la mitad de los problemas de un clúster nuevo, y siempre por lo mismo: 7946 necesita TCP y UDP, y 4789 es UDP. Un cortafuegos que solo abra TCP produce el síntoma más desconcertante posible: los nodos aparecen Ready, los servicios se despliegan, pero los contenedores de nodos distintos no se ven entre sí. Nunca abras el 2377 a internet: quien lo alcance con un token puede unirse a tu clúster.

El ciclo drain → mantenimiento → active es la rutina básica de operación de un clúster: las tareas se recolocan solas antes de que toques nada, y nadie se queda sin servicio. Ojo con un detalle: al volver a active, las tareas no regresan solas al nodo; se quedan donde están hasta el siguiente despliegue.

Swarm introduce dos conceptos nuevos sobre lo que ya conoces:

• Servicio: la declaración. "Quiero tres réplicas de esta imagen con esta configuración".
• Tarea: cada unidad de trabajo asignada a un nodo. Una tarea acaba siendo un contenedor, y es inmutable: no se modifica ni se reinicia, se sustituye por otra nueva.

docker service ps es la herramienta de diagnóstico principal, porque muestra también las tareas muertas y por qué murieron:

Esa última línea cuenta una historia completa: la tarea 3 murió en worker-1 con el código 78 que programaste en 06-01, es decir, configuración inválida, y el orquestador la recreó en worker-2. Sin la validación de arranque, ahí pondría un genérico exit (1).

El modo global es exactamente lo que necesitan los recolectores de métricas y logs del módulo 5: cada nodo necesita su cAdvisor y su Promtail, y quieres que aparezcan solos en cada máquina que añadas al clúster sin acordarte de nada.

La diferencia entre restricción y preferencia importa mucho en la práctica: una restricción imposible deja el servicio en Pending para siempre, sin ningún error evidente, mientras que una preferencia solo influye en el reparto. Si un servicio no arranca y docker service ps no muestra ningún error, sospecha de una restricción que ningún nodo cumple.

La red bridge de 03-05 solo conecta contenedores del mismo anfitrión. Una red overlay conecta contenedores de nodos distintos como si compartieran un cable.

Por dentro es un túnel VXLAN: cada paquete Ethernet del contenedor se encapsula dentro de un datagrama UDP hacia el puerto 4789 del nodo destino, que lo desencapsula y lo entrega. Para los contenedores, la existencia de dos máquinas es invisible; siguen resolviendo aurora-db por DNS y hablando por su IP de la red overlay.

El --opt encrypted merece una decisión consciente. El tráfico VXLAN viaja en claro por defecto: si tus nodos están en una red privada de un mismo centro de datos puede ser aceptable, pero si cruzan internet o una red compartida, el catálogo, las consultas y las credenciales que pasen por ahí son legibles para cualquiera con acceso al medio. Es exactamente el tipo de decisión que debes validar con tu responsable de seguridad. Ojo también: el cifrado se aplica al plano de datos, y no puede activarse ni desactivarse sin recrear la red.

Cuando publicas un puerto en modo ingress (el predeterminado), todos los nodos del clúster escuchan en él, incluso los que no ejecutan ninguna réplica de ese servicio. El nodo que recibe la conexión la reparte por IPVS entre las tareas vivas, estén donde estén.

La ventaja es enorme para el balanceador de entrada: apunta a cualquier nodo, o a todos, y no necesita saber dónde está nada. Los inconvenientes son dos y conviene conocerlos: hay un salto de red extra cuando el nodo que recibe no tiene la tarea, y la IP de origen que ve tu aplicación es la del nodo, no la del cliente real, porque hay SNAT de por medio.

El modo host es la salida cuando necesitas la IP del cliente (registro de acceso, límites por IP, geolocalización) o el último gramo de latencia, y tiene un precio: obliga al balanceador externo a saber en qué nodos hay réplicas, y no puedes tener dos réplicas del mismo servicio en un nodo, porque chocarían en el puerto.

Aquí llega la recompensa de todo el módulo 4: docker stack deploy acepta tu compose.yaml.

El --with-registry-auth es imprescindible con un registro privado como ghcr.io: sin él, el manager entiende las credenciales pero no las reenvía a los workers, y las tareas fallan con no basic auth credentials en todos los nodos menos donde hiciste docker login.

Las dos ignoradas de en medio cambian cómo diseñas la aplicación. Sin build, el flujo obliga a pasar por el registro, lo cual es correcto en producción. Y sin depends_on, tu API tiene que soportar arrancar antes que la base de datos: por eso implementaste el reintento con backoff en 04-04, y por eso las sondas de 06-01 devuelven 503 mientras las dependencias no estén.

Un matiz que separa reservations de limits y que en Compose no existía: en Swarm, las reservas afectan a la planificación. El planificador suma las reservas de las tareas ya ubicadas en cada nodo y solo coloca una nueva donde quepa. Reservar de más deja nodos vacíos con servicios en Pending; reservar de menos amontona tareas hasta que el nodo se queda sin memoria. Los números medidos de 06-01 son justo lo que necesitas aquí.

Los secretos viajan a los nodos cifrados por TLS mutuo, se guardan cifrados en el estado Raft y se montan en un tmpfs que nunca toca el disco; el ejercicio 3 lo comprueba dimensión por dimensión. Además, un secreto es inmutable: no se puede modificar. Rotarlo consiste en crear uno nuevo con otro nombre, actualizar el servicio con --secret-rm y --secret-add y eliminar el viejo. Es incómodo a propósito: fuerza que la rotación sea un despliegue trazable y no un cambio silencioso.

Los configs funcionan igual pero sin cifrado en reposo, y son la vía natural para init.sql, nginx.conf o prometheus.yml: ficheros de configuración que deben llegar a todos los nodos sin tener que copiarlos a mano.

Advertencia sobre los datos. La constraint de aurora-db es un parche, no una solución. Los volúmenes locales no viajan: si worker-1 muere, Swarm recreará la tarea de PostgreSQL en otro nodo y encontrará un volumen vacío, con lo que el catálogo desaparece. Un clúster de verdad necesita almacenamiento de red (NFS, iSCSI, Ceph, un volumen de bloque del proveedor cloud) o una base de datos gestionada fuera del clúster. Discútelo con tu responsable de infraestructura antes de poner datos reales aquí: no es un detalle de configuración, es una decisión de arquitectura.

Swarm sigue incluido en Docker Engine y mantenido, pero es minoritario: la industria estandarizó Kubernetes, y ahí están los proveedores gestionados, las herramientas y la mayor parte de la documentación.

La comparación detallada la harás en 07-02. Lo que sí conviene retener: casi todo lo de esta lección —estado deseado, reconciliación, servicios y réplicas, red entre nodos, secretos montados como ficheros, actualizaciones progresivas— es exactamente el mismo modelo mental que vas a usar en Kubernetes, con otros nombres. Swarm no ha sido un desvío: ha sido la introducción sencilla al mismo problema.

• Dos managers. Empeora la disponibilidad respecto a uno. Siempre 1, 3, 5 o 7.
• Olvidar --advertise-addr. Con varias interfaces, Swarm elige mal y el clúster no se forma. Ponlo siempre explícito.
• Abrir solo TCP en el cortafuegos. El 7946 necesita UDP también y el 4789 es UDP puro. El síntoma es nodos Ready con overlay muerta.
• Esperar que build: funcione. Swarm no construye: publica la imagen antes y referénciala por etiqueta o digest. Y no olvides --with-registry-auth, o las tareas fallarán en todos los nodos menos donde hiciste docker login.
• Volúmenes locales para datos. La tarea se reprograma y el volumen no la sigue. Almacenamiento de red o base de datos externa.
• Restricciones que ningún nodo cumple. El servicio se queda en Pending sin mensaje claro. Verifica con docker node inspect.
• Consejo: usa docker service ps --no-trunc. La columna ERROR completa suele contener la causa exacta del fallo.
• Consejo: etiqueta los nodos desde el primer día (zona, disco, datos). Reubicar servicios después es cuestión de una restricción.

Ejercicio 1. Monta un clúster de tres nodos, despliega aurora-api con tres réplicas y demuestra la reconciliación: mata un contenedor a mano y después vacía un nodo entero, comprobando en cada caso dónde reaparecen las tareas.

Ejercicio 2. Demuestra la malla de enrutamiento: publica aurora-web con una sola réplica, comprueba que responde desde los tres nodos y averigua desde cuál se está sirviendo realmente.

Ejercicio 3. Compara un secreto de Swarm con una variable de entorno: intenta extraer ambos valores desde fuera del contenedor con docker inspect y desde dentro con /proc, y explica dónde vive físicamente cada uno.

Solución 1.

Las dos pruebas muestran la misma maquinaria a dos escalas. Al matar el contenedor, la tarea .1 se recreó en el mismo nodo, porque el nodo seguía sano y era el sitio preferido; el 137 es el SIGKILL de tu docker kill, y el historial con \_ conserva el intento fallido. Al drenar worker-2, sus dos tareas se reubicaron en los otros dos nodos, y el conteo volvió a 3/3 en unos quince segundos.

Lo importante es lo que no hiciste: no ejecutaste ningún comando de reparación. Solo declaraste "quiero tres" una vez, y el bucle de reconciliación mantiene esa afirmación cierta ante un contenedor muerto, un nodo drenado o una máquina apagada de golpe. Es el mismo mecanismo que en Kubernetes gobierna un Deployment, y por eso restart: always deja de tener sentido aquí: la política de reinicio es del servicio, no del contenedor.

Fíjate también en que la tarea .2 fue a parar a manager-1. Con la constraint node.role==worker del compose.swarm.yaml no habría podido: se habría quedado en Pending hasta que worker-2 volviera. Es el compromiso entre proteger los managers y tener sitio donde reprogramar.

Solución 2.

Los tres nodos responden 200 aunque solo worker-2 ejecuta la réplica. Eso es la malla de enrutamiento: al publicar en modo ingress, cada nodo abre el puerto 80 y reenvía por IPVS a través de la red overlay hasta donde estén las tareas vivas.

Y ahí aparece el efecto secundario que hay que conocer: la IP registrada es 10.0.0.2, una dirección de la red ingress, no la del cliente real. El DNAT de la tabla nat reescribe el destino y, por el camino, el SNAT sustituye el origen. Si Aurora Libros necesitara la IP real —para limitar peticiones por cliente o para analítica—, tendrías que publicar en mode=host, aceptando que entonces solo responderían los nodos con réplica y que el balanceador externo debe saberlo.

La ventaja compensa en la mayoría de los casos: el balanceador de entrada puede apuntar a los tres nodos sin saber nada de dónde vive cada servicio, y añadir o quitar réplicas no le obliga a cambiar su configuración.

Solución 3.

La asimetría ya es total en la primera comprobación: la variable se lee entera en la especificación del servicio, que cualquiera con acceso a la API de Docker puede consultar; del secreto solo se ve el nombre y el punto de montaje.

El tmpfs de la segunda línea es la clave del diseño: el secreto nunca toca el disco en ningún nodo. Al parar la tarea, el sistema de ficheros se desmonta y el valor deja de existir; no queda en una capa de imagen, ni en un volumen, ni en un fichero de log, ni en un backup del sistema de ficheros del nodo.

La fila de la herencia es la que más incidentes provoca en la práctica. Una variable de entorno la ven todos los subprocesos: si tu API invoca pg_dump, un script de despliegue o cualquier herramienta de terceros, esa contraseña va con ellos, y basta con que una librería registre su entorno al fallar —cosa que hacen muchas— para que la credencial acabe en un servicio externo de gestión de errores. El fichero de /run/secrets/ solo lo lee quien decide leerlo, que es justo lo que hace tu config.js de 06-01, una vez, al arrancar.

Aurora Libros ya no depende de una máquina. Sabes qué aporta un orquestador —planificación, reconciliación y red entre nodos— y has montado un clúster de Swarm con docker swarm init --advertise-addr, tokens distintos por rol y los tres puertos que hay que abrir, con el detalle que cuesta tardes enteras: 7946 en TCP y UDP, 4789 en UDP. Entiendes por qué los managers deben ser impares y por qué dos son peores que uno, y manejas la rutina de drain → mantenimiento → active que permite tocar una máquina sin que nadie deje de comprar libros.

Has cambiado de modelo mental: ya no das órdenes, declaras un estado deseado y un bucle lo mantiene cierto. Lo has comprobado matando un contenedor y drenando un nodo entero, viendo cómo las tareas reaparecen solas sin que ejecutaras ninguna reparación. Distingues servicio de tarea, réplicas de modo global —el que necesitan Promtail y cAdvisor—, y sabes que una restricción imposible deja un servicio en Pending mudo. Has creado redes overlay sobre túneles VXLAN, con la decisión consciente sobre --opt encrypted para el tráfico que cruza redes que no controlas, y has visto la malla de enrutamiento responder desde los tres nodos con una sola réplica viva, junto con su precio: la IP que registra Nginx es la de la red ingress, no la del cliente.

El compose.yaml del módulo 4 se ha convertido en un stack con docker stack deploy, con la tabla de lo que Swarm ignora —build, depends_on, restart— y la sección deploy completa, donde las reservations ya no son decorativas porque gobiernan la planificación. Los secretos nativos han demostrado su ventaja de forma medible: invisibles en inspect, ausentes de /proc/<pid>/environ, montados en un tmpfs que nunca toca el disco y sin heredarse a los subprocesos, mientras el patrón _FILE de 06-01 sigue funcionando sin tocar una línea de código. Y queda anotada en rojo la limitación real: los volúmenes locales no viajan, así que aurora-db está anclada por una etiqueta de nodo y eso es un parche que hay que sustituir por almacenamiento de red o una base de datos gestionada antes de poner datos reales.

En la siguiente lección, Introducción a Kubernetes, cambias de herramienta pero no de ideas. Verás el plano de control con su kube-apiserver, su etcd y su planificador, los objetos fundamentales —Pod, Deployment, Service, Ingress, ConfigMap, Secret, PVC— con su YAML mínimo comentado, el papel central de las etiquetas y los selectores, la tabla de kubectl traducida a los comandos de Docker que ya dominas, y montarás un clúster local con kind para dar tus primeros pasos.