Swarm mode — manager and worker nodes

A swarm joins several Docker hosts into a cluster; managers keep the cluster state with Raft and workers run containers.

What a swarm is

Swarm mode is built into Docker Engine: several Docker hosts form one cluster. You declare a desired state (for example "web runs 3 replicas"), and the swarm schedules, scales, load-balances, connects hosts with overlay networks and repairs drift when a node fails.

flowchart TB
  subgraph M["Managers (Raft)"]
    M1["manager1 (Leader)"] --- M2["manager2"]
    M2 --- M3["manager3"]
    M3 --- M1
  end
  M --> W1["worker1: tasks"]
  M --> W2["worker2: tasks"]
  M --> W3["worker3: tasks"]

Role	What it does
Manager	Keeps the cluster state with the Raft consensus algorithm, schedules services, serves the swarm API (`docker service`, `docker node`)
Worker	Only runs the tasks (containers) a manager assigns; no Raft, no scheduling

Managers also run tasks by default. docker node promote worker1 turns a worker into a manager; docker node demote does the opposite.

Quorum

Raft needs a majority of managers alive to change the cluster. With N managers, the swarm tolerates (N−1)/2 failed managers:

Managers	Failures tolerated
1	0
2	0 (losing 1 loses quorum)
3	1
5	2

So use an odd number of managers (3 or 5). Without quorum, running containers keep running, but you cannot create, scale or change services.

Security

Swarm has a built-in PKI: every node gets a certificate when it joins, and nodes talk to each other with mutual TLS (authentication, authorization and encryption of the control plane). Container traffic on an overlay network is only encrypted when the network is created with --opt encrypted.

Labels and placement

Node labels describe hardware or location, and services use constraints to pick nodes:

docker node update --label-add zone=a --label-add disk=ssd worker1
docker service create --name db --constraint node.labels.disk==ssd postgres:16
docker service create --name web --placement-pref spread=node.labels.zone nginx:1.27

Built-in attributes work too, such as node.role==worker or node.hostname==worker2. A placement preference spreads replicas evenly across label values, for example across zones.

Keep managers for management

In production, set managers to drain so they run no application tasks and keep their CPU for Raft and scheduling. A busy manager that misses heartbeats can trigger leader elections and slow down the whole cluster.

Protecting cluster state

The Raft log, including secrets, lives in /var/lib/docker/swarm on each manager. Back it up from a manager while Docker is stopped there. Autolock (docker swarm init --autolock or docker swarm update --autolock=true) encrypts that data with a key that must be supplied with docker swarm unlock after a restart, protecting secrets if a disk is stolen.

Swarm or Kubernetes?

	Docker Swarm	Kubernetes
Setup	Built into Docker Engine, a few commands	Separate components; managed services ease it
Learning curve	Small, reuses Compose files	Steep, many object types
Ecosystem	Smaller	Very large (operators, Helm, service meshes)
Fits	Small teams, simple clusters	Most production platforms and cloud offerings

Swarm mode is still part of Docker Engine and maintained, but Kubernetes has become the industry default. Learning Swarm first makes the core ideas (desired state, services, overlay networks, rolling updates) familiar before Kubernetes.

docker node ls marks the leader with Leader in the MANAGER STATUS column and shows each node's availability.