Skip to content
Tutorials Center
My learning

Topics

Lesson 93 of 111 ยท Orchestration Basics

Docker Swarm Basics

Learn how Docker Swarm turns several machines into one cluster: manager and worker nodes, services, replicas, stacks, rolling updates and rollbacks.

Everything you have done so far ran on one machine: one daemon, a handful of containers. Docker Swarm is the orchestrator built into the Docker Engine. It joins several machines into one swarm and lets you describe what should run ("three copies of this web server, reachable on port 80") instead of starting containers one by one. Swarm then places the containers on machines, restarts them when they die and replaces them one at a time when you ship a new image.

Swarm is deliberately small. If you know docker run and Compose files, you already know most of its vocabulary. That makes it a good first step into orchestration even if you end up on Kubernetes later (see From Docker to Kubernetes). This lesson covers the architecture, the core commands, stacks, rolling updates and where Swarm stops being enough.

Swarm needs real cluster behavior (several nodes, an overlay network, a manager quorum), and turning on swarm mode changes how the Docker daemon works. The daemon used to verify this track is shared, so the swarm commands below are read-only examples: the shapes and the output are written from knowledge of how Swarm behaves. What was run for real here is everything that works without a swarm: the stack file below was validated with docker stack config, and the "not a swarm manager" error is real.

The mental model

A swarm has two kinds of nodes. Managers keep the cluster state, accept your commands and make scheduling decisions. Workers only run containers. A manager can run containers too, which is the default.

TEXT
                 you: docker service create ...
                              |
                              v
        +---------------------+---------------------+
        |        manager nodes (Raft consensus)     |
        |   leader <-> manager <-> manager          |
        +----+-----------------+----------------+---+
             | schedules tasks onto nodes        |
     +-------v------+   +------v-------+   +-----v--------+
     | worker 1     |   | worker 2     |   | worker 3     |
     |  web.1  web.4|   |  web.2       |   |  web.3  api.1|
     +--------------+   +--------------+   +--------------+

The words to learn:

  • Node: one machine running Docker with swarm mode enabled.
  • Service: the definition of what to run: image, number of replicas, ports, update rules. This is what you manage.
  • Task: one running instance of a service on one node. A service with three replicas has three tasks, and each task owns exactly one container. Tasks are never moved: if a node dies, Swarm creates a new task elsewhere.
  • Stack: a group of services deployed together from one Compose-style file.
  • Overlay network: a virtual network that spans all nodes, so containers talk to each other by service name wherever they run.
  • Routing mesh: every node listens on a published port and forwards the traffic to a healthy task, even if that task is on another node.

Managers keep their shared state in a Raft log. Raft needs a majority to make decisions, so use 1 manager for experiments and 3 (or 5) for production: three managers survive the loss of one, five survive the loss of two. An even number gains nothing.

Creating a swarm

On the first machine you initialize the swarm. The command prints the join command for workers:

CONSOLE
$ docker swarm init --advertise-addr 192.0.2.10
Swarm initialized: current node (x9k2d1m4q7ab) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-<secret>-<secret> 192.0.2.10:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

(Read-only example. 192.0.2.10 is a documentation address; use the machine's real IP, reachable by the other nodes.) The --advertise-addr matters when a machine has several network interfaces. On each other machine you paste the printed docker swarm join line. Then, on a manager:

CONSOLE
$ docker node ls
ID                            HOSTNAME   STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
x9k2d1m4q7ab *                node1      Ready     Active         Leader           29.8.1
p3t8w0c5n2ef                  node2      Ready     Active                          29.8.1
k7r1y6h9s4gh                  node3      Ready     Active                          29.8.1

The * marks the node you are talking to. Only managers can run docker node ls; on a machine that is not part of a swarm (like the one used to write this track) you get:

CONSOLE
$ docker node ls
Error response from daemon: This node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again.

Ports to open between nodes: 2377/tcp (manager API), 7946/tcp and udp (node gossip) and 4789/udp (overlay network traffic). Keep them closed to the internet, and consider encrypting the overlay (docker network create --opt encrypted). Swarm already uses mutual TLS between nodes and rotates the certificates automatically.

Services

A service is created with docker service create. The options look like the ones you know from docker run:

CONSOLE
$ docker service create --name web --replicas 3 --publish 8080:80 nginx:alpine
n2v8s0q1x7t3d5e6f9g0h1j2k
overall progress: 3 out of 3 tasks
1/3: running   [==================================================>]
2/3: running   [==================================================>]
3/3: running   [==================================================>]
verify: Service n2v8s0q1x7t3d5e6f9g0h1j2k converged

(Read-only example.) The word converged is the heart of orchestration. You declared a desired state (3 replicas); Swarm compares it with the actual state and keeps working until they match. Two commands show the result:

CONSOLE
$ docker service ls
ID             NAME   MODE         REPLICAS   IMAGE          PORTS
n2v8s0q1x7t3   web    replicated   3/3        nginx:alpine   *:8080->80/tcp

$ docker service ps web
ID             NAME    IMAGE          NODE    DESIRED STATE   CURRENT STATE           ERROR   PORTS
a1b2c3d4e5f6   web.1   nginx:alpine   node1   Running         Running 40 seconds ago
b2c3d4e5f6a1   web.2   nginx:alpine   node2   Running         Running 40 seconds ago
c3d4e5f6a1b2   web.3   nginx:alpine   node3   Running         Running 39 seconds ago

Notice that the container names are web.1.<task-id>, so docker ps on each node looks different from what you are used to. Use docker service logs web to see the combined logs of all replicas.

Self-healing

If you kill a container behind a task, or a whole node disappears, Swarm notices that the actual state (2 of 3) no longer matches the desired state (3) and starts a replacement task, usually on a healthy node. The failed task stays in the history, which is why docker service ps shows Shutdown rows with an error message. This is also why you should never fix a swarm service by editing a single container: the next restart would undo it. Change the service instead.

Scaling

CONSOLE
$ docker service scale web=5
web scaled to 5
overall progress: 5 out of 5 tasks
verify: Service web converged

docker service update --replicas 5 web does the same. A service can also run in global mode (--mode global): exactly one task on every node, which suits agents such as log shippers and monitors.

Placement and resources

By default Swarm spreads tasks across nodes. You can restrict or influence this with constraints, such as "only on managers" or "only on nodes with the label disk=ssd":

CONSOLE
$ docker node update --label-add disk=ssd node2
$ docker service create --name db --constraint 'node.labels.disk == ssd' \
    --reserve-memory 512m --limit-memory 1g postgres:17-alpine

--limit-* is the hard cap you know from Resource Limits. --reserve-* is what the scheduler must find free on a node before it places the task. A task that cannot be placed stays Pending; docker service ps --no-trunc shows why ("no suitable node").

Networking

Services on the same overlay network reach each other by service name, with Swarm's DNS spreading requests over the replicas (a virtual IP per service):

CONSOLE
$ docker network create --driver overlay appnet
$ docker service create --name api --network appnet myorg/api:1.0.0
$ docker service create --name web --network appnet --publish 8080:80 myorg/web:1.0.0

Inside web, http://api:3000 works no matter which node api tasks run on. Published ports go through the routing mesh: you can send a request for port 8080 to any node's IP, and it arrives at a healthy web task. The design is simple, but remember that the mesh load balances at the connection level and hides the client IP unless you publish in host mode (--publish published=8080,target=80,mode=host).

Stacks: services from a file

Typing docker service create for every part of an application does not scale. A stack deploys a whole application from a Compose-format file. The deploy: key, which plain docker compose mostly ignores, carries the Swarm settings. This file was checked with the real docker stack config:

YAML
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
        order: start-first
        failure_action: rollback
      restart_policy:
        condition: on-failure
      resources:
        limits:
          cpus: "0.5"
          memory: 128M
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
      interval: 10s
  cache:
    image: redis:alpine
    deploy:
      placement:
        constraints:
          - node.role == manager

docker stack config merges and resolves the file exactly as docker stack deploy would, without needing a swarm. It prints the normalized form, where, for example, the port became a structured mode: ingress entry and the memory limit became bytes:

CONSOLE
$ docker stack config -c stack.yaml
version: "3.13"
services:
  cache:
    deploy:
      placement:
        constraints:
          - node.role == manager
    image: redis:alpine
  web:
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
        failure_action: rollback
        order: start-first
      resources:
        limits:
          cpus: "0.5"
          memory: "134217728"
      restart_policy:
        condition: on-failure
    healthcheck:
      test:
        - CMD
        - wget
        - -qO-
        - http://127.0.0.1/
      interval: 10s
    image: nginx:alpine
    ports:
      - mode: ingress
        target: 80
        published: 8080
        protocol: tcp

Deploying and inspecting it on a swarm looks like this (read-only example):

CONSOLE
$ docker stack deploy -c stack.yaml shop
Creating network shop_default
Creating service shop_cache
Creating service shop_web

$ docker stack services shop
ID             NAME         MODE         REPLICAS   IMAGE          PORTS
q1w2e3r4t5y6   shop_cache   replicated   1/1        redis:alpine
u7i8o9p0a1s2   shop_web     replicated   3/3        nginx:alpine   *:8080->80/tcp

$ docker stack rm shop

Services get the stack name as a prefix (shop_web) and share a stack-wide network. Running docker stack deploy again with an edited file updates the stack in place, which is how you ship new versions.

Two differences from docker compose up trip people up:

  • Swarm cannot build images. build: is ignored by docker stack deploy. Build and push to a registry every node can reach, then reference the tag (see Working with Registries). Every node must be able to pull it, which for private registries means docker login plus docker stack deploy --with-registry-auth.
  • Some Compose keys do nothing, like depends_on ordering and container_name. Swarm expects services to cope with their neighbours being late: use healthchecks and retries.

Rolling updates and rollbacks

The update_config block above defines how a new image is rolled out: parallelism: 1 replaces one task at a time, delay waits between batches, and order: start-first starts the new task before stopping the old one so capacity never drops (the default is stop-first). With failure_action: rollback, a new version that never becomes healthy is reverted automatically.

You trigger an update by changing the image:

CONSOLE
$ docker service update --image nginx:1.29-alpine web
web
overall progress: 3 out of 3 tasks
1/3: running   [==================================================>]
2/3: running   [==================================================>]
3/3: running   [==================================================>]
verify: Service web converged

And you can return to the previous definition manually:

CONSOLE
$ docker service rollback web
web
rollback: manually requested rollback
overall progress: rolling back update: 3 out of 3 tasks
verify: Service web converged

The healthcheck is what makes this safe. Without one, Swarm considers a task healthy as soon as its process starts, even if the application is still booting or crashed in its first second. With a healthcheck (see HEALTHCHECK), a new task is only counted when the check passes, and a failing check makes Swarm replace the container.

Config, secrets and node maintenance

Swarm has two objects for settings that do not belong in an image. Secrets are encrypted at rest in the Raft log, sent only to nodes whose tasks need them, and mounted as in-memory files under /run/secrets/<name>. Configs are the same idea for non-sensitive files such as an nginx.conf.

CONSOLE
$ printf 's3cr3t-value' | docker secret create db_password -
$ docker service create --name db --secret db_password \
    -e POSTGRES_PASSWORD_FILE=/run/secrets/db_password postgres:17-alpine

(Read-only example.) This is the safest built-in way to hand a password to a container; more on the idea in Managing Secrets.

To patch a node, drain it. Swarm moves its tasks elsewhere, and you can reboot the machine safely:

CONSOLE
$ docker node update --availability drain node2
node2
$ docker node update --availability active node2
node2

When to use Swarm, and when not

Swarm shines when you have a few machines, a small team, and want to reuse your Compose knowledge: it needs no extra installation, a swarm is running in minutes, and the mental load is low. It is a fair choice for internal tools, small SaaS products and edge deployments.

It is a weaker choice when you need an ecosystem. Kubernetes has far more tooling (operators, autoscaling on custom metrics, service meshes, managed offerings from every cloud), and most hiring, tutorials and vendor support assume it. Swarm's development is slow, and it lacks built-in autoscaling and advanced scheduling. A pragmatic rule: if one server with Compose is enough, stay there (see Deploying on a Single Host); if you need a cluster and care about the broader ecosystem, go to Kubernetes; Swarm fits in between. The decision guide at the end of the track, Choosing Your Deployment Path, compares the options side by side.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In Swarm terminology, what is a task?

    A service defines what to run; each of its replicas is a task assigned to a node. A stack is the group of services, and a node is the machine.
  2. 2. You run docker service scale web=5 and then a worker node loses power. What does Swarm do?

    Swarm continuously reconciles the desired state with reality. Tasks are never moved; new ones are created elsewhere.
  3. 3. Why do production swarms usually have 3 managers instead of 2?

    With 2 managers a majority is both of them, so losing one blocks all changes. With 3, the remaining two still form a majority.
  4. 4. What happens to a build: key in a file passed to docker stack deploy?

    docker stack deploy does not build. Build and push the image, then use image: with a tag every node can pull.
  5. 5. What does order: start-first in update_config change?

    The default is stop-first. With start-first Swarm brings up the new task and waits for it to be healthy before removing the old one.

Summary

  • Swarm mode joins machines into one cluster of manager nodes (state and scheduling, Raft quorum) and worker nodes (run containers).
  • You declare a service (image, replicas, ports, limits); Swarm creates tasks and continuously reconciles actual state with desired state, replacing failed ones.
  • docker swarm init, docker swarm join, docker service create/ls/ps/scale/update/rollback and docker node ls/update are the core commands.
  • A stack deploys a Compose-format file with a deploy: section; docker stack config validates it without a swarm. Swarm cannot build images, so push them to a registry first.
  • Rolling updates (parallelism, delay, order, failure_action: rollback) and healthchecks give safe releases; secrets and configs deliver settings without baking them into images.
  • Swarm is simple and good for small clusters; Kubernetes offers the larger ecosystem.

Next: From Docker to Kubernetes