Skip to main content
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
  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
Ensure the web:latest image is available locally or on your registry before creating the service.

​
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:
ConfigurationDescription
ParallelismNumber of tasks updated simultaneously
DelayTime to wait between update batches
Failure ActionBehavior when an update fails (pause, continue, rollback)
Monitoring PeriodDuration Swarm waits for a task to become healthy

​
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
Failure ActionDescription
pauseHalt the update on error (default)
continueIgnore failures and proceed to next batch
rollbackRevert immediately to the previous image/version
Using continue can leave your cluster in a mixed-version state. Test thoroughly before choosing this option in production.

​
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

Watch Video