Courses Docker in depthOrchestration with Swarm

Swarm mode & architecture

Managers, workers, and the raft log.

Intermediate14 min · lesson 16 of 30

Compose runs a stack on one machine; Swarm turns a group of Docker hosts into a single cluster you drive with the same docker CLI. You initialize a swarm on one node, join others with a token, and from then on you deploy services to the swarm rather than containers to a host — the swarm decides which node runs what and keeps it running. It is Docker’s built-in orchestrator: lighter than Kubernetes and built from concepts you already know.

terminal

$ docker swarm init --advertise-addr 10.0.1.10
Swarm initialized: current node (abc123) is now a manager.
To add a worker: docker swarm join --token SWMTKN-1-xxxx 10.0.1.10:2377
 
$ docker node ls        # on a manager: the whole cluster at a glance
ID         HOSTNAME   STATUS   AVAILABILITY   MANAGER STATUS
abc123 *   mgr-1      Ready    Active         Leader
def456     node-1     Ready    Active

Managers and workers

Nodes have two roles. Managers hold cluster state and make scheduling decisions, keeping that state consistent with the Raft consensus algorithm — which is why you run an odd number (3 or 5) so a majority is always reachable. Workers just run assigned tasks. Managers are workers too by default, but in production you keep a small, dedicated manager quorum and let workers scale out.

Swarm roles

managers (odd count — Raft quorum)

store desired state

in the replicated Raft log

schedule tasks

decide who runs what

serve the API

you talk to a manager

workers (scale out)

run tasks

the actual containers

report status

back to the managers

3 managers tolerate 1 failure, 5 tolerate 2. Lose the manager majority and the swarm can no longer schedule.

Scenario: take a node down for maintenance

You need to patch node-1 without dropping its workloads or risking the cluster. Drain it — Swarm reschedules its tasks elsewhere and stops placing new ones there — do the maintenance, then set it Active again. If it is a manager you are removing for good, demote it first so the Raft quorum math stays sound (keep the count odd). Promotion and demotion move nodes between roles without rebuilding them.

terminal

$ docker node update --availability drain node-1     # evacuate its tasks
$ docker node ps node-1                              # confirm nothing runs there
# ...patch the host...
$ docker node update --availability active node-1    # back into rotation
$ docker node promote node-2                          # make a worker a manager
$ docker node demote mgr-3                            # step a manager down first

The model is the one Kubernetes uses: you declare desired state — three replicas of this service — and the swarm continuously reconciles reality toward it. A service becomes a set of tasks, each task is one container, and if a task or a whole node dies, the managers schedule replacements to restore the count. You describe the what; the orchestrator handles the how.

Raft quorum is non-negotiable

Managers need a majority to make any decision, so the count must be odd — three tolerate one failure, five tolerate two; an even count buys nothing. Lose the majority (two of three managers down) and the swarm goes read-only: running tasks keep running, but nothing new schedules until quorum returns. Never run exactly two managers.

Network troubleshootingServices, replicas & scaling