Services, replicas & scaling

The declarative unit of Swarm.

The unit you deploy to a swarm is a service: a declarative description of a container plus how many copies to keep and how to update them. docker service create is the swarm counterpart of docker run, but instead of one container on this host it tells the swarm to maintain that workload across the cluster. Replicated mode keeps a fixed number of copies; global mode runs exactly one on every node.

$ docker service create --name web --replicas 3 -p 80:80 nginx:1.27
$ docker service ls
ID       NAME   MODE         REPLICAS   IMAGE
z1y2x3   web    replicated   3/3        nginx:1.27
$ docker service ps web        # the tasks and which node each runs on
NAME    NODE     CURRENT STATE
web.1   node-1   Running 2 minutes ago
web.2   node-2   Running 2 minutes ago
web.3   node-1   Running 2 minutes ago

Scenario: scale for a traffic spike

Traffic climbs and three replicas are not enough. Scaling is one command — set the replica count and the swarm schedules new tasks across nodes with spare capacity, then load-balances across all of them automatically. Scale back down when the spike passes and it stops the extra tasks. No manual placement, no editing each node.

$ docker service scale web=10
web scaled to 10
$ docker service ps web --filter desired-state=running --format '{{.Node}}' | sort | uniq -c
   4 node-1
   3 node-2
   3 node-3         # spread across the cluster

Scenario: a rolling update that can roll itself back

You ship a new image and want zero downtime — and automatic recovery if the new version is broken. Configure the rollout: replace tasks a few at a time with a delay, and set the failure action to roll back so a task that fails its health check aborts and reverts the whole update instead of marching the outage across every replica.

$ docker service update \
    --image registry.internal/web:1.28 \
    --update-parallelism 1 --update-delay 15s \
    --update-failure-action rollback \
    web
$ docker service rollback web        # or revert manually to the previous spec

Scenario: an agent on every node

A log shipper or metrics agent must run exactly once on every node, including nodes you add later. That is global mode: the swarm places one task per node and automatically starts one on any node that joins. Use global for per-host infrastructure and replicated for scalable application copies — the distinction decides whether “scale” even makes sense for the service.

$ docker service create --mode global --name node-agent \
    --mount type=bind,source=/var/log,target=/var/log,readonly \
    registry.internal/log-agent:1.0
$ docker service ps node-agent        # exactly one task per node, always