Swarm Architecture

In one sentence: A swarm turns many engines into one logical engine: manager nodes keep the cluster's desired state in a Raft-replicated store (surviving minority failure), while worker nodes just run what they're told.

Two roles, one truth

Every node runs the same engine plus a cluster agent, but roles differ. Managers hold the truth: every service definition, node record, and task assignment lives in a state store replicated across managers with the Raft consensus algorithm — one elected leader orders all writes, and a write commits only when a majority (quorum) has stored it. Three managers tolerate one loss; five tolerate two. Lose quorum and the cluster becomes read-only: running containers keep running, but nothing new can be decided — a deliberate choice of consistency over availability, because two half-clusters each scheduling their own copies would be worse. Workers hold no truth at all: they receive task assignments, run containers, and report status. Losing a worker loses only capacity.

flowchart TB
  subgraph MGRS["managers (the truth)"]
    M1["manager 1 — LEADER
orders all writes"]
    M2["manager 2 (follower)"]
    M3["manager 3 (follower)"]
    M1 -- "Raft replication" --- M2
    M1 -- "Raft replication" --- M3
  end
  ST[("replicated state store
services · nodes · tasks")]
  M1 --- ST
  W1["worker 1
runs tasks, reports status"]
  W2["worker 2
runs tasks, reports status"]
  M1 -- "assign tasks" --> W1
  M1 -- "assign tasks" --> W2
  U["user: service create"] --> M1
    

sequenceDiagram
  participant U as User
  participant L as Leader
  participant F1 as Follower 2
  participant F2 as Follower 3
  U->>L: service create web (replicas 3)
  L->>F1: replicate log entry
  L->>F2: replicate log entry
  F1-->>L: stored
  note over L: 2 of 3 = majority → COMMIT
(no need to wait for F2)
  L-->>U: accepted — state is durable
  note over L,F2: if the leader dies now, a new leader
is elected from nodes holding the entry