Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 38 ยท Scaling and Updates

Rolling Updates in Docker Swarm

Update Swarm services without downtime: parallelism, delay, start-first versus stop-first order, failure_action, monitor, and how to watch and tune a rollout.

Shipping a new version should not mean a maintenance window. Swarm replaces tasks gradually in a rolling update: a few at a time, with pauses between batches, and with the option to stop or roll back if the new version misbehaves. This lesson explains every knob and how they combine.

Swarm cannot run on this site; the commands are read-only text and the Python blocks are stand-ins that simulate rollouts so you can see how settings change the timeline.

Starting an update

Any change to a service's task template triggers a rolling update: a new image, environment variable, config, secret, resource limit or command.

Terminal
docker service update --image myorg/api:1.5 api
docker service update --env-add FEATURE_X=on api
docker stack deploy -c stack.yml shop          # changed services roll
docker service update --force api              # roll with no change

--force is handy to redistribute tasks after adding nodes or to restart everything gently.

The update settings

Terminal
docker service update \
  --update-parallelism 2 \
  --update-delay 10s \
  --update-order start-first \
  --update-failure-action rollback \
  --update-monitor 30s \
  --update-max-failure-ratio 0.2 \
  api
Setting Meaning Default
parallelism Tasks replaced at once (0 = all) 1
delay Wait between batches 0s
order stop-first or start-first stop-first
failure_action pause, continue or rollback pause
monitor How long each new task is watched for failure 5s
max_failure_ratio Fraction of failed tasks tolerated 0

In a stack file the same keys live under deploy.update_config (the deploy key).

stop-first versus start-first

With stop-first (default) Swarm stops an old task, then starts its replacement. Capacity briefly drops by parallelism. With start-first Swarm starts the new task, waits until it is healthy, and only then stops the old one, so you never go below the desired count. Start-first needs spare capacity and is only valid when two versions can run together (for example, they must not both bind a host port or grab the same exclusive lock). It is the easy route to zero downtime, and it works best together with a health check.

sequenceDiagram
  participant S as Swarm
  participant Old as Task v1
  participant New as Task v2
  Note over S: update-order start-first
  S->>New: start
  New-->>S: healthy
  S->>Old: stop
  Note over S: next batch after delay

Start-first keeps full capacity through each batch.

Watching an update

Terminal
docker service update --detach=false --image myorg/api:1.5 api
docker service ps api
docker service inspect --pretty api

Without --detach=false the command returns immediately in older releases. While the update runs, docker service inspect --pretty shows UpdateStatus with state updating, then completed, paused or rollback_started. Old tasks stay in docker service ps as Shutdown, which gives you a history of recent versions.

When a rollout fails

If a new task fails (it crashes, or its health check never passes) within the monitor window, Swarm counts a failure. When the failure ratio is exceeded, failure_action decides what happens:

  • pause: stops the rollout, leaving a mix of old and new tasks. You investigate, then run docker service update again or docker service rollback.
  • continue: keeps going regardless (rarely wise).
  • rollback: reverts to the previous spec automatically, using rollback_config.

Choose rollback for production services with good health checks. Choose pause when a person should decide.

Choosing numbers

  • Parallelism about 10-25% of replicas: fast enough, small risk. With 4 replicas use 1.
  • Delay long enough for the new tasks to receive traffic and show problems (10-30 s).
  • Monitor at least as long as your application takes to hit its first real failure, such as a bad configuration or a missed database migration.
  • Use start-first for stateless services; use stop-first for services that cannot overlap (singleton workers, port-bound jobs).

Stand-in: simulate a rolling update

Python Stand-in: rollout timeline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: failure_action decides the outcome

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Using start-first with a service that publishes a host-mode port.
  • Setting monitor too short, so a slow crash is missed and the rollout continues.
  • Skipping health checks: Swarm then treats "process started" as healthy.
  • Schema changes that break the old version while it still runs. Use backward-compatible, two-step migrations.
  • Changing parallelism to 0 (all at once) and calling it a rolling update.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which update order avoids dropping below the desired replica count?

    start-first brings up the new task and waits for it before stopping the old one.
  2. 2. A new task fails within the monitor window and failure_action is rollback. What happens?

    rollback returns the service to the previous version, governed by rollback_config.
  3. 3. Which change does NOT trigger a rolling update?

    Only changes to the task template roll. Reading status changes nothing.

Summary

  • A rolling update replaces tasks in batches controlled by parallelism, delay and order.
  • start-first preserves capacity; stop-first avoids running two versions at once.
  • monitor, max_failure_ratio and failure_action decide when a rollout stops or reverts.
  • Pair rolling updates with health checks and backward-compatible changes.

Next: Health Checks and Rollbacks