Docker Swarm at a glance — what you get and what it costs · Docker & Containers

Swarm mode is built into the Docker Engine you already run. There is no separate control plane to install, no new CLI, and no new file format — docker swarm init turns a host into a one-node cluster and docker stack deploy takes a Compose file.

That makes it the cheapest possible step from single-host Compose to multi-host, and the cheapness is the entire argument for it. This lesson covers what you actually get, the defaults worth changing on day one, and the risk you take on by choosing it.

The object model

Five objects, and how they relate

Node. A Docker Engine that has joined the swarm. Either a manager (participates in Raft consensus and can accept API calls) or a worker (runs tasks only). Managers also run tasks by default.
Service. The desired state for one workload: an image, a replica count, resources, constraints, an update policy. This is the object you create.
Task. One replica of a service, assigned to one node. A task maps to exactly one container and is never moved — if a node fails, the old task is marked failed and a new task is created elsewhere.
Stack. A group of services deployed together from a Compose file.
Secret / config. Cluster-stored objects mounted into task containers as files under /run/secrets and /run/configs. These exist only in Swarm; they are not available to plain docker run.

Configuration changebootstrap— A three-manager swarm. Run the first command on node 1, then join the rest.

# On the first manager
docker swarm init --advertise-addr 192.0.2.11

# Read the join tokens on the manager
docker swarm join-token manager
docker swarm join-token worker

# On each additional node, with the token printed above
TOKEN=REPLACE_ME
docker swarm join --token "$TOKEN" 192.0.2.11:2377

Read-only / Safenode ls— Manager status is the column that matters.

$ docker node ls

ID          HOSTNAME   STATUS   AVAILABILITY   MANAGER STATUS   ENGINE VERSION
p2x9k1v...  node01     Ready    Active         Leader           28.3.2
q7m4b8n...  node02     Ready    Active         Reachable        28.3.2
r5t1w6z...  node03     Ready    Active         Reachable        28.3.2
s9c3h2j...  node04     Ready    Active                          28.3.2

Illustrative output

Quorum is the thing to understand first

Managers keep the desired state in a Raft log. Writes require a majority: with N managers, quorum is (N / 2) + 1.

Managers	Quorum	Failures tolerated
1	1	0
3	2	1
5	3	2
7	4	3

Use an odd number. Going from 3 to 4 managers does not improve fault tolerance — both tolerate one failure — and it adds a node to every consensus round. Beyond 7, the write latency of consensus starts to cost more than the extra redundancy is worth.

What happens when you lose quorum?

The cluster does not stop. Existing tasks keep running, because workers execute what they were already told to execute and do not need a manager to keep a container alive.

What stops is every state change. You cannot deploy, scale, update, drain a node, or reschedule a failed task. The reconciliation loop cannot write, so a container that dies on a healthy node is not replaced. The cluster degrades silently: nothing is obviously broken until the second failure.

Recovery from a majority-of-managers loss is a documented but disruptive procedure: on one surviving manager, force a new single-manager cluster and re-join everything else.

Cluster-wide riskforce-new-cluster— Last-resort recovery on a surviving manager. Read the admin guide first; this rewrites cluster membership.

docker swarm init --force-new-cluster --advertise-addr 192.0.2.11

This is exactly the kind of procedure that must be rehearsed in a lab before it is needed, because the first time you run it will otherwise be during an outage with the desired state of your entire estate at stake.

Compose is nearly, but not entirely, the same file

docker stack deploy -c compose.yml myapp accepts a Compose file, and the differences are the source of most first-week frustration:

Compose key	In a stack
`deploy:`	Ignored by `docker compose`, used by `docker stack deploy`
`build:`	Ignored — the image must already be in a registry every node can reach
`depends_on:`	Accepted, but the `condition:` forms are ignored; there is no startup ordering
`restart:`	Ignored — use `deploy.restart_policy`
`container_name:`	Ignored — task names are generated
`ports:`	Published through the routing mesh unless you set `mode: host`
`env_file:`	Read on the machine running the deploy, not on the nodes

The second difference nobody expects: there is no startup ordering. Swarm starts every service at once and relies on applications retrying their dependencies. An application that exits when its database is not yet reachable will crash-loop through the first minute of every deploy. If you cannot fix the application, its entrypoint needs to wait and retry.

Defaults worth changing on day one

Three rolling-update defaults that behave differently from what people assume

--update-order defaults to stop-first. Each task is stopped before its replacement is started. With 3 replicas and --update-parallelism 1, you run at two-thirds capacity for the duration of every rolling update. For a service that can tolerate two versions running simultaneously, start-first keeps capacity flat.

--update-failure-action defaults to pause. When a task fails to start during an update, the update stops. It does not roll back and it does not fail loudly — the service simply sits half-updated, some replicas on the new image and some on the old, and docker service ls shows a replica count that looks fine. rollback is almost always the better default; either way, check docker service ps after every deploy.

--update-delay defaults to 0s. Tasks are replaced as fast as they become healthy, with no soak time. For anything with a warm-up period — a JIT runtime, a cache to fill, a connection pool to establish — a delay of a minute or two between batches is what turns a rolling update into a safe one.

services:
  web:
    image: registry.example.com/myorg/myapp:1.4.2
    deploy:
      replicas: 4
      update_config:
        parallelism: 1
        delay: 60s
        order: start-first
        failure_action: rollback
      rollback_config:
        parallelism: 0
        order: stop-first
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
      resources:
        limits:
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

Note reservations versus limits: the scheduler places tasks using reservations, and the kernel enforces limits. A service with limits and no reservations can be scheduled onto a node that cannot actually satisfy it, and you find out when the OOM killer does.

The routing mesh, and the source IP

By default a published port is reachable on every node in the swarm, even nodes not running a task for that service. The ingress network forwards the request to a node that is.

That is convenient — any node’s address works as a load balancer target — and it has a cost: by the time the request reaches your container, the source address is the ingress network’s, not the client’s. Access logs show internal addresses. Rate limiting by IP does not work. Geo-lookup does not work.

Two ways out, both with trade-offs:

mode: host publishing. The port is bound only on nodes running a task, and the real source IP is preserved. You lose the “any node works” property, so your external load balancer must know which nodes are running the service.
A reverse proxy at the edge that sets X-Forwarded-For, with the application configured to trust it. Standard practice, and the usual answer.

The honest costs

What you are accepting by choosing Swarm

Ecosystem risk, which is the real one. Swarm mode ships in Docker Engine and continues to receive maintenance, but it has seen very little feature development for years, and its ecosystem is a small fraction of Kubernetes’. Concretely: fewer operators and integrations, fewer people who have run it before, less community material when you hit something odd, and a smaller hiring pool. If your organisation expects to be running this in five years, that is a genuine input to the decision — not a reason to reject Swarm, but one to weigh explicitly and write down.

No autoscaling. Replica counts are set by you. There is no built-in horizontal autoscaler, and adding one means writing it.

No native storage orchestration. There is no equivalent of a PersistentVolumeClaim. Stateful services either pin to a node with a constraint — giving up the rescheduling you adopted Swarm for — or use a volume driver plugin, of which few are actively maintained.

Autolock is a foot-gun. docker swarm init --autolock encrypts the Raft log at rest and requires an unlock key each time a manager restarts. Lose the key and the managers cannot start. If you enable it, the key belongs in the same place as your other break-glass credentials, and the restore procedure belongs in the runbook.

Certificates expire. Node certificates default to a 90-day validity and rotate automatically while nodes are running. A node that has been powered off for longer than that may need to re-join rather than simply starting.

Against those: a Swarm cluster is three Docker hosts and a docker swarm init. There is no separate control plane to patch, no CNI plugin to choose, no ingress controller to operate, and no quarterly upgrade treadmill. For a team of two running a dozen services, that difference is not small.