Rolling updates are a deployment strategy designed to introduce new application versions gradually while keeping the service continuously available. Instead of stopping all running instances at once, updates are applied in controlled batches. This approach minimizes user impact, reduces deployment risk, and allows rapid rollback when issues are detected.olling updates are a deployment strategy designed to introduce new application versions gradually while keeping the service continuously available. Instead of stopping all running instances at once, updates are applied in controlled batches. This approach minimizes user impact, reduces deployment risk, and allows rapid rollback when issues are detected.
Zero-downtime deployment is the practical outcome of a correctly configured rolling update. When update parameters are carefully chosen, traffic continues to flow to healthy tasks while updated tasks are created, started, verified, and promoted.
This article explains rolling updates from fundamentals to advanced configuration, focusing on how deployment behavior is controlled, how failures are handled, and how predictable, interruption-free releases are achieved.
Understanding Rolling Updates
A rolling update replaces existing running tasks with new ones incrementally. At no point is the entire service stopped unless explicitly configured to do so.
Key characteristics of rolling updates:
- Tasks are updated in batches
- Old and new versions coexist temporarily
- Availability is preserved during updates
- Failures can halt or roll back the update
Rolling updates apply to changes such as:
- New container image versions
- Environment variable updates
- Resource limit modifications
- Command or argument changes
Any service specification change triggers an update cycle.
Update Lifecycle Overview
A rolling update progresses through a predictable sequence:
- Select tasks eligible for update
- Stop or remove a subset of existing tasks
- Create replacement tasks with the new specification
- Start and verify new tasks
- Continue to the next batch until completion
The size, speed, and safety of this process are governed entirely by update configuration parameters.
Default Update Behavior
Without explicit configuration, updates proceed with conservative defaults:
- One task updated at a time
- New task created before old task removal
- Failure pauses the update
- No automatic rollback
While safe, defaults may be too slow or too permissive for production workloads. Explicit configuration is strongly recommended.
Configuring Rolling Updates
Rolling update behavior is defined using update parameters when creating or modifying a service.
Basic Update Configuration
docker service create \ --name webapp \ --replicas 4 \ --update-parallelism 1 \ --update-delay 10s \ webapp:v1
This configuration:
- Updates one task at a time
- Waits 10 seconds between updates
- Maintains service availability throughout
Update Parallelism
Update parallelism controls how many tasks are updated simultaneously.
--update-parallelism <number>
Low Parallelism
--update-parallelism 1
Characteristics:
- Maximum safety
- Slower deployments
- Ideal for stateful or critical services
High Parallelism
--update-parallelism 3
Characteristics:
- Faster updates
- Higher temporary load
- Requires sufficient capacity
Parallelism should never exceed the number of replicas required to keep the service available.
Update Delay
Update delay defines how long the system waits between updating task batches.
--update-delay 15s
Purpose of delay:
- Allow new tasks to stabilize
- Observe runtime behavior
- Reduce cascading failures
Delays are especially important when applications require warm-up time or perform initialization logic at startup.
Update Order
Update order defines whether new tasks start before or after old tasks stop.
Start-First Strategy
--update-order start-first
Behavior:
- New task starts first
- Old task stops only after new task is running
- Temporary capacity increase
This is the preferred option for zero-downtime deployments.
Stop-First Strategy
--update-order stop-first
Behavior:
- Old task stops first
- New task starts afterward
- Temporary capacity reduction
Stop-first may cause brief unavailability if replicas are limited.
Achieving Zero-Downtime Deployments
Zero-downtime is not automatic. It requires correct configuration.
Minimum requirements:
- Multiple replicas
- Start-first update order
- Parallelism lower than replica count
- Application readiness on startup
Example configuration:
docker service update \ --update-parallelism 1 \ --update-delay 10s \ --update-order start-first \ webapp
This ensures at least three healthy tasks remain available while one task updates.
Health Awareness During Updates
Rolling updates rely on task health to determine progress.
If a new task:
- Fails to start
- Exits unexpectedly
- Does not reach a running state
The update process pauses automatically.
This behavior prevents faulty versions from propagating further.
Failure Handling During Updates
Failures can occur due to:
- Application startup errors
- Invalid images
- Misconfiguration
- Runtime crashes
When a failure occurs:
- The update stops
- Already updated tasks remain running
- Remaining tasks stay on the previous version
This containment is critical for production safety.
Automatic Rollbacks
Rollbacks allow the system to revert to the previous service version when an update fails.
Enabling Rollbacks
--update-failure-action rollback
Example:
docker service update \ --update-failure-action rollback \ webapp
If any task fails during the update:
- The update stops
- Tasks revert to the previous configuration
- Service stability is restored automatically
Rollback Configuration
Rollback behavior can be controlled independently.
--rollback-parallelism 1 --rollback-delay 5s --rollback-order stop-first
This ensures rollbacks are:
- Controlled
- Predictable
- Non-disruptive
Rollbacks use the last known good service specification.
Manual Rollbacks
Manual rollback is possible at any time.
docker service rollback webapp
Use cases:
- Post-deployment issue discovery
- Performance regression
- Functional errors not detected at startup
Manual rollback immediately starts reverting tasks.
Update Monitoring
During a rolling update, progress can be observed in real time.
docker service ps webapp
Key indicators:
- Desired state
- Current state
- Error messages
- Task version differences
Monitoring output helps verify correct behavior and identify failures early.
Versioned Image Updates
Rolling updates are commonly triggered by image version changes.
docker service update \ --image webapp:v2 \ webapp
Best practices:
- Use immutable image tags
- Avoid latest in production
- Verify images before deployment
Versioned images provide traceability and rollback safety.
Controlled Configuration Changes
Rolling updates apply equally to non-image changes.
Examples:
- Environment variables
- Commands
- Resource limits
docker service update \ --env-add FEATURE_FLAG=true \ webapp
Each configuration change is rolled out incrementally using the same update mechanism.
Handling Long-Running Connections
Applications with long-lived connections must support graceful shutdown.
Recommendations:
- Handle termination signals correctly
- Finish in-flight requests
- Exit cleanly
Rolling updates depend on applications exiting predictably when replaced.
Update Pausing and Resuming
Updates can be paused manually.
docker service update --pause webapp
Paused updates:
- Stop further task replacement
- Leave current state unchanged
To resume:
docker service update --resume webapp
This is useful during investigation or staged deployments.
Reconfiguring Update Strategy Mid-Deployment
Update parameters can be modified while an update is in progress.
docker service update \ --update-parallelism 2 \ webapp
This allows:
- Accelerating safe updates
- Slowing risky updates
- Adapting to runtime conditions
Common Rolling Update Patterns
Conservative Production Update
--update-parallelism 1 --update-delay 20s --update-order start-first --update-failure-action rollback
Best for:
- Critical services
- User-facing APIs
- Payment systems
Fast Internal Service Update
--update-parallelism 3 --update-delay 5s --update-order start-first
Best for:
- Internal tools
- Stateless services
- Rapid iteration environments
Avoiding Downtime Pitfalls
Common mistakes that cause downtime:
- Single-replica services
- Stop-first update order
- High parallelism
- Missing rollback configuration
- Slow application startup
Zero-downtime requires deliberate configuration, not assumptions.
Testing Update Behavior
Before production deployment:
- Test updates in staging
- Simulate failures
- Validate rollback paths
docker service update --image invalid:image webapp
Observe failure handling and rollback correctness.
Predictable Deployments Through Configuration
Rolling updates are deterministic when configured correctly. Each parameter directly influences:
- Safety
- Speed
- Availability
- Recovery behavior
Understanding these controls allows repeatable, low-risk deployments.
Summary
Rolling updates provide a structured, reliable way to deploy changes without interrupting service availability. By controlling parallelism, delay, update order, and failure handling, deployments become predictable and safe. Zero-downtime is achieved not by chance, but through intentional configuration and disciplined deployment practices.