Docker Swarm para IA local

Qué cubre este artículo

• Qué es Docker Swarm y cuándo resulta útil.
• Cómo inicializar un cluster Swarm.
• Cómo funcionan los servicios, tareas y redes overlay.
• Ejemplo práctico con Ollama u Open WebUI.
• Ventajas y desventajas frente a Kubernetes y Compose.

Introducción: Docker Swarm para IA local

Docker Swarm es la función de clustering integrada en Docker. Puedes unir varios hosts Docker en un Swarm para distribuir y escalar servicios entre ellos. Para homelabs, Swarm suele ser más simple que Kubernetes pero más potente que Docker Compose en una sola máquina. Si dispones de varios servidores y quieres distribuir servicios de IA como Ollama, Open WebUI o bases de datos, Swarm es un buen punto de partida para la orquestación de contenedores.

Este artículo explica cómo configurar Docker Swarm, definir servicios y cuándo merece la pena usarlo.

Conceptos clave

• Swarm: Cluster de múltiples nodos Docker.
• Manager: Nodo que controla el Swarm.
• Worker: Nodo que ejecuta los servicios en el Swarm.
• Service: Aplicación definida en el Swarm.
• Task: Instancia en ejecución de un servicio.
• Replica: Cantidad de tareas ejecutándose en paralelo.
• Red overlay: Red que abarca múltiples nodos.
• Stack: Grupo de servicios definido en un archivo Compose.

Cuándo usar Docker Swarm

• Tienes múltiples servidores físicos o virtuales.
• Los servicios necesitan alta disponibilidad.
• Quieres distribuir la carga entre nodos.
• Requieres actualizaciones sin tiempo de inactividad.
• Prefieres una entrada más sencilla que Kubernetes.

Si usas un solo servidor, Docker Compose es suficiente.

Inicializar el Swarm

En el primer manager:

docker swarm init --advertise-addr 192.168.1.10

El comando devuelve un token de unión. Los nodos worker y managers adicionales se unen con:

docker swarm join --token <TOKEN> 192.168.1.10:2377

Verifica el estado:

docker node ls

Crear un servicio

docker service create --name ollama \
  --publish 11434:11434 \
  --replicas 1 \
  --mount type=volume,source=ollama-data,target=/root/.ollama \
  ollama/ollama

Stack desde un archivo Compose

Puedes desplegar un archivo docker-compose.yml directamente como stack:

docker stack deploy -c docker-compose.yml ki-stack

Importante: Swarm no soporta todas las características de Compose. Por ejemplo, build no se ejecuta en el stack, así que las imágenes deben construirse previamente y alojarse en un registry.

Archivo Compose para Swarm

version: "3.8"

services:
  ollama:
    image: ollama/ollama:latest
    volumes:
      - ollama-data:/root/.ollama
    networks:
      - ki-net
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.labels.gpu == true

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "8080:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    networks:
      - ki-net
    deploy:
      replicas: 1

volumes:
  ollama-data:

networks:
  ki-net:
    driver: overlay

Ubicación y restricciones

Para ejecutar Ollama en un nodo con GPU, puedes usar etiquetas:

docker node update --label-add gpu=true node1

En el servicio:

deploy:
  placement:
    constraints:
      - node.labels.gpu == true

Escalado

docker service scale ki-stack_open-webui=3

O en Compose:

deploy:
  replicas: 3

Actualizaciones progresivas

docker service update --image ollama/ollama:latest ki-stack_ollama

Las actualizaciones se implementan automáticamente de forma sucesiva en los nodos.

Secretos y configuraciones

Docker Swarm incluye soporte integrado para secretos:

echo "mein-passwort" | docker secret create db_password -

En el servicio:

services:
  app:
    secrets:
      - db_password

secrets:
  db_password:
    external: true

Redes overlay

Los servicios en la misma red overlay pueden comunicarse usando el nombre del servicio, sin importar en qué nodo se ejecuten.

docker network create --driver overlay ki-net

Ventajas frente a Compose

• Alta disponibilidad.
• Distribución entre múltiples nodos.
• Actualizaciones progresivas.
• Load balancing integrado.
• Redes overlay.
• Secretos y configuraciones.

Desventajas frente a Kubernetes

• Ecosistema más pequeño.
• Características de orquestación limitadas.
• Sin service mesh integrado.
• Menos integraciones de monitoreo y almacenamiento.

Para muchos homelabs, Swarm es más que suficiente. Si tienes requisitos complejos, siempre puedes migrar a Kubernetes.

Errores comunes

• Las imágenes deben estar en un registry: build no se ejecuta en el stack.
• Volúmenes locales en el nodo: Los datos no se mueven automáticamente con el contenedor.
• Restricciones mal configuradas: El servicio puede iniciarse en un nodo sin GPU o recursos suficientes.
• Problemas de red: Firewall bloqueando puertos de comunicación del Swarm.
• Múltiples managers: Usa un número impar para quórum, mínimo tres.
• Sin estrategia de persistencia: Los servicios con estado necesitan almacenamiento compartido o bind mounts.

Enlaces y recursos útiles

• BotServ.de Comandos Docker
• BotServ.de Redes Docker
• BotServ.de Docker Compose
• BotServ.de Docker Registry
• BotServ.de Kubernetes

FAQ: Docker Swarm

¿Necesito Swarm para un solo servidor? No, Docker Compose puro es suficiente.

¿Está obsoleto Docker Swarm? Docker Swarm sigue siendo mantenido, pero tiene menos impulso comunitario que Kubernetes.

¿Puedo usar GPU en Swarm? Sí, mediante restricciones de ubicación y Nvidia Runtime en los nodos correspondientes.

¿Están los servicios de Swarm en alta disponibilidad? Sí, siempre que varias réplicas se ejecuten en diferentes nodos.

¿Qué es mejor: Swarm o Kubernetes? Swarm es más simple, Kubernetes más potente. Para homelabs, Swarm suele ser suficiente.

Fuentes y lecturas recomendadas

• Docker Swarm Docs: https://docs.docker.com/engine/swarm/
• Docker Stack Deploy: https://docs.docker.com/engine/reference/commandline/stack_deploy/
• Docker Swarm Networking: https://docs.docker.com/network/overlay/

Resumen: Docker Swarm para IA local

Docker Swarm es una excelente opción para distribuir servicios de IA entre múltiples servidores sin la complejidad de Kubernetes. Con simples comandos puedes inicializar clusters, desplegar servicios, escalarlos y actualizarlos. Las restricciones de ubicación para cargas de GPU, las redes overlay para la comunicación y una estrategia de persistencia son fundamentales. Para homelabs con varios nodos, Swarm ofrece alta disponibilidad y escalado sencillos, mientras que los servidores únicos típicamente se mantienen con Docker Compose.