Scaling Rolling Updates and Rollbacks

In this guide, you’ll learn how to scale your services, perform seamless rolling updates, and execute rollbacks in Docker Swarm. We’ll run all commands on the manager node while Swarm orchestrates tasks on worker nodes.

Table of Contents

1. Deploying a Service
2. Scaling Service Replicas
3. Rolling Updates
   • Default Update Behavior
   • Introducing an Update Delay
   • Parallel Updates
4. Inspecting Update & Rollback Configuration
5. Handling Update Failures
6. Rolling Back a Service
7. References

Deploying a Service

By default, creating a service launches a single replica. Here’s how to deploy a simple web service listening on port 80:

docker service create \
  --name web \
  --publish 80:80 \
  web:latest

Scaling Service Replicas

Adjust the replica count of an existing service with docker service update --replicas.

Scale up to three replicas:

docker service update \
  --replicas 3 \
  web

Scale down to one replica:

docker service update \
  --replicas 1 \
  web

Docker Swarm will automatically add or remove tasks on the worker nodes to match your desired state.

Rolling Updates

Rolling updates replace containers one batch at a time, ensuring zero downtime.

Default Update Behavior

After tagging your new image (e.g., web:2.0), trigger the rolling update:

docker service update \
  --image web:2.0 \
  web

Swarm will:

• Stop one container
• Deploy a new one
• Wait for it to pass health checks
• Repeat until all replicas are updated

Introducing an Update Delay

Pause between updating each batch with --update-delay:

docker service update \
  --image web:3.0 \
  --update-delay 30s \
  web

This adds a 30-second wait after each batch to monitor stability.

Parallel Updates

Increase throughput by updating multiple tasks simultaneously using --update-parallelism:

docker service update \
  --image web:2.1 \
  --update-parallelism 2 \
  web

This example updates up to two replicas at once, balancing speed and reliability.

Inspecting Update & Rollback Configuration

Use docker service inspect to review how your service handles updates and rollbacks:

docker service inspect web --format '{{json .UpdateStatus}}'

Key fields in the output:

Handling Update Failures

By default, Swarm pauses on the first failure. Change this with --update-failure-action:

docker service update \
  --image web:2.2 \
  --update-failure-action rollback \
  web

Rolling Back a Service

If an update introduces instability, quickly revert to the last known good state:

docker service update \
  --rollback \
  web

This command restores the previous image and update configuration across all replicas.

References

• Docker Service Commands
• Docker Swarm Overview
• Docker Rolling Updates