Opscraft
Docker Swarm · Lesson 7 of 10 · 3 min read

Rolling updates, health and rollback

How an update rolls

docker service update \
  --image shop-api:4a1b9c0 \
  --update-parallelism 1 \
  --update-delay 10s \
  --update-order start-first \
  --update-failure-action rollback \
  --update-monitor 30s \
  api
  • parallelism — tasks updated at once.
  • delay — wait between batches.
  • order — stop-first (default: stop old, then start new — brief capacity dip) or start-first (start new, then stop old — needs spare capacity, avoids dips).
  • monitor — how long after each task update to watch for failure.
  • failure_action — pause (default), continue, or rollback.
  • max_failure_ratio — tolerated fraction of failed tasks.

With a healthcheck, a new task isn't considered running until healthy, so a bad version fails the update instead of receiving traffic. Without health checks, users see errors during updates because traffic hits tasks before they're ready.

Enlarge diagramstart new taskshop-api:4a1b9c0healthy?watched for 30 s(--update-monitor)stop old taskthen wait 10 s (--update-delay)next batchone at a time(--update-parallelism 1)failure?roll back to the previous specdoneall tasks on the new image123456
Figure 1. A rolling update with start-first and automatic rollback: new tasks must become healthy before old ones stop.
Swipe sideways to see all of it, or tap to open it full screen.

Manual rollback:

docker service rollback api          # back to the previous spec
docker service update --rollback api

docker service update --force api restarts all tasks without changing the spec (useful to rebalance or pick up a rotated config).