Docker Swarm

Docker Swarm#

Docker Swarm is the orchestrator built into Docker Engine. One docker swarm init makes a manager; one docker swarm join makes a worker; docker stack deploy runs docker-compose files across the cluster. The lightest orchestrator that still covers service discovery, rolling updates, secrets, and overlay networking.

Swarm is a fit for small fleets, labs, and edge sites where Kubernetes is too heavy and Compose-style YAML is good enough. It is mostly maintenance-mode upstream (no new features for years) but still ships in every Docker install.

Architecture#

        flowchart LR
  subgraph mgr[Managers]
    M1[manager 1, leader]
    M2[manager 2]
    M3[manager 3]
    M1 --- M2 --- M3
  end
  subgraph wkr[Workers]
    W1[worker 1]
    W2[worker 2]
    W3[worker 3]
  end
  OP[operator + docker CLI] --> M1
  M1 --> W1
  M1 --> W2
  M1 --> W3

Concept

Detail

Manager

Runs the Raft store and the scheduler. Odd number (1, 3, 5); 3 is the usual production minimum.

Worker

Runs tasks. Promoted from worker to manager with docker node promote.

Service

The declarative spec of replicas, image, ports, networks. The Deployment equivalent.

Task

One container, one scheduling slot. service × replicas = tasks.

Stack

A set of services defined in a Compose v3 file, deployed together.

Overlay network

VXLAN-based L2 across all nodes. Containers attached to it share a flat address space.

Routing mesh

Built-in L4 ingress. Any node accepts traffic on a published port; the mesh forwards to a container.

Setup#

# On the first manager:
$ docker swarm init --advertise-addr <ip>
# Outputs a token; copy it.

# On each additional manager:
$ docker swarm join --token <manager-token> <ip>:2377

# On each worker:
$ docker swarm join --token <worker-token> <ip>:2377

$ docker node ls

Deploying a service#

$ docker service create \
    --name web \
    --replicas 3 \
    --publish published=80,target=8080 \
    --update-parallelism 1 \
    --update-delay 10s \
    myorg/app:1.0

$ docker service ls
$ docker service ps web                # task placements
$ docker service logs -f web
$ docker service update --image myorg/app:1.1 web
$ docker service scale web=5
$ docker service rollback web

Stacks (Compose v3 across the cluster)#

# docker-compose.yml
version: "3.9"
services:
  web:
    image: myorg/app:1.0
    deploy:
      replicas: 3
      update_config: { parallelism: 1, delay: 10s }
      restart_policy: { condition: on-failure }
    ports:
      - "80:8080"
    networks: [appnet]
  redis:
    image: redis:7
    deploy: { replicas: 1 }
    networks: [appnet]
networks:
  appnet: { driver: overlay }

$ docker stack deploy -c docker-compose.yml app
$ docker stack services app
$ docker stack ps app
$ docker stack rm app

Secrets and configs#

Native primitives, encrypted at rest in the Raft store.

$ echo "supersecret" | docker secret create db_password -
$ docker config create nginx.conf nginx.conf
$ docker service create --name web \
    --secret db_password \
    --config nginx.conf \
    myorg/app:1.0

Secrets land in /run/secrets/<name> inside the container. Configs land at /<name> by default; --config source=...,target=/etc/nginx/nginx.conf controls placement.

Operational gotchas#

  • Manager quorum is non-negotiable. Lose more than (N-1)/2 managers and the cluster goes read-only until quorum is restored. Three managers tolerate one failure; five tolerate two.

  • Single overlay encryption flag. --opt encrypted=true on a network turns on IPSec for inter-node pod traffic. Off by default; turn it on for cross-DC overlays.

  • No autoscaler. Replicas are static unless the operator wires up an external controller. orbiter and a few community tools exist, none mainstream.

  • Limited RBAC. Docker Swarm has roles (manager / worker) and unix socket access; nothing like Kubernetes RBAC. Multi-tenancy is weak.

  • Future. Mirantis owns Docker Engine; Swarm is supported but not actively developed. Plan a migration path before scale or compliance demands it.

When to pick Swarm#

  • Two to ten nodes, one team, docker-compose is already in use.

  • Edge sites where the orchestrator must fit on a single small VM.

  • Labs and learning environments where the operator wants the Compose mental model end to end.

When not to#

  • Multi-team estates needing RBAC, namespaces, policy.

  • Anywhere the operator needs the broader Kubernetes ecosystem (Helm charts, operators, CSI drivers, ingress controllers, observability stacks built around Kubernetes objects).

References#

Contents