The problem starts with a very ordinary question: how do you change something people are actively using?

The naive approach, and why it fails

The simplest possible way to deploy a new version of an application is to stop every running copy of the old version and start every copy of the new version. This is easy to reason about, but it comes with an unavoidable cost: for some window of time, however brief, there is no running application at all to serve requests. For anything users actually depend on continuously, that gap is a real, visible outage — even if it only lasts a few seconds.

What a rolling update does instead

A rolling update replaces a running service’s containers gradually, in small batches, rather than all at once. At every point during the process, some containers are still running the old version and actively serving traffic while a small number are being swapped for the new version, so the service as a whole never fully stops. Docker Swarm — Docker’s built-in orchestration mode for running services across a cluster of machines — implements this as a first-class, built-in feature of how it manages services.

Why rollbacks are the natural companion feature

Deploying gradually creates a valuable side effect: since only a portion of the service changes at first, problems with the new version can often be caught before every container has been replaced. A rollback reverses this process, replacing the new version’s containers back with the previous, known-good version — either triggered manually by an operator, or automatically by Docker itself when it detects the new version isn’t healthy.

A handful of Swarm concepts cooperate to make gradual, controlled rollouts possible.

Where the update’s behavior is actually configured

Rather than being a single fixed process, every service can define its own update behavior — how many tasks to replace at once, how long to wait between batches, in what order the old task is stopped relative to the new one starting, and what to do if a failure is detected. This configuration lives directly on the service itself, so different services in the same cluster can roll out in completely different ways depending on how sensitive each one is to a brief disruption.

flowchart TB
    A["Update Requested
(new image / config)"] --> B["Swarm Manager"]
    B --> C["Update Controller"]
    C --> D["Read Service's
Update Configuration"]
    D --> E["Select Next Batch
of Tasks to Replace"]
    E --> F["Stop/Start Tasks
per configured order"]
    F --> G{"Health Check
Passed?"}
    G -->|"Yes"| H["Wait configured delay,
proceed to next batch"]
    G -->|"No"| I["Apply configured
failure action"]
    H --> E
        

Underneath the concept, it’s a repeating loop over small batches of tasks.

When an update is requested, the Swarm manager doesn’t touch every task at once. It divides the full set of tasks into batches, sized according to the service’s configured parallelism, and processes one batch fully before ever starting the next. This batch-by-batch looping is the actual mechanism that turns “replace everything” into “replace gradually.”

Three configuration choices control almost everything about how disruptive an update feels.

Stop-first vs start-first, in practice

With a stop-first order, the old task is removed before its replacement starts — this briefly reduces total capacity for that batch, but guarantees the old and new versions are never running side by side on the same batch slot. With a start-first order, the new task is started and given a chance to become healthy before the old task is stopped — preserving full capacity throughout, at the cost of a short window where both versions are simultaneously live and potentially receiving traffic.

Without a way to detect failure, none of the automated safety behavior would be possible.

“Running” is not the same as “working”

A container can be fully running — its process started successfully, no crash occurred — while the application inside it is completely unable to serve real requests, for example because it can’t reach a required database. Swarm’s rollout logic needs a more meaningful signal than “the process started” to safely decide whether a batch actually succeeded, which is exactly what a configured health check provides.

How health checks influence the rollout

When a service defines a health check, Swarm waits for newly started tasks to report as healthy — not merely running — before considering that batch of the update complete and moving on to the next one. If a task fails its health check within the configured grace period, the controller treats that as a failed update for this batch and applies whatever failure action the service is configured to take.

Reverting a bad update follows the same gradual philosophy as rolling it out.

Manual rollback

An operator who notices a problem — even one health checks didn’t catch, such as a subtle business-logic bug — can explicitly instruct Swarm to roll a service back to its previous specification. Swarm treats this the same way it treats a forward update: as a gradual, batch-by-batch replacement, just moving in the opposite direction, back to the prior known-good version.

Automatic rollback

A service can also be configured so that Swarm rolls back on its own, without any human intervention, the moment its configured failure action determines that an update batch has failed — typically due to health check failures beyond an allowed threshold. This turns a bad deployment into a self-correcting event rather than an incident that requires someone to notice and react.

sequenceDiagram
    participant Op as Operator
    participant Mgr as Swarm Manager
    participant New as New Version Tasks
    participant Old as Previous Version

    Op->>Mgr: Request update to new image
    Mgr->>New: Roll out batch 1
    New-->>Mgr: Health check failing
    Mgr->>Mgr: Evaluate configured failure action
    alt Automatic rollback configured
        Mgr->>Old: Revert affected tasks to previous spec
        Old-->>Mgr: Healthy
        Mgr-->>Op: Update rolled back automatically
    else Manual rollback required
        Mgr-->>Op: Update paused, awaiting operator decision
        Op->>Mgr: Trigger rollback
        Mgr->>Old: Revert to previous spec
    end
        

Gradual, automated rollouts remove a lot of manual risk — but they add their own complexity.

Deployment mechanics and security posture intersect more than they might first appear to.

Who is allowed to trigger an update

The ability to update a running service is effectively the ability to change what code is running in production — a highly privileged action. Controlling exactly who and what (which pipeline identities, which individuals) can request a service update deserves the same scrutiny as any other high-impact production access.

Rollbacks and previously patched vulnerabilities

An automatic or manual rollback reverts to a prior image, which may itself have contained a security vulnerability that the very update being rolled back was meant to fix. Teams relying on rollback as a safety net need a process for quickly re-addressing any security-relevant fix that a rollback has temporarily undone, rather than assuming the rollback is a fully safe, permanent resting state.

Watching an update in progress is what actually makes the automated safety net trustworthy.

Tracking convergence

Swarm continuously tracks how close a service is to its fully updated desired state, making it possible to observe an update’s real-time progress — how many tasks have been updated, how many remain, and whether any are currently failing — rather than only finding out the final outcome after the fact.

The gap between a smooth rollout culture and a nerve-wracking one is mostly about deliberate configuration.

Pattern: cautious parallelism for critical services

Configuring a low parallelism value and a meaningful delay for user-facing, critical services trades rollout speed for the ability to catch a bad release while only a small fraction of the service has been touched — a trade most teams gladly accept for anything customers directly depend on.

Pattern: meaningful, application-aware health checks

Building a health check that genuinely reflects whether the application can do its job — checking real dependencies like database connectivity, not just returning a static success response — gives the update controller an honest signal to act on, rather than a check that technically passes while the application is actually broken.

A short list of habits that make rolling updates something teams trust rather than fear.

Rolling updates are one of the most consistently relied-upon patterns across modern container orchestration.

The rolling update mechanism described here is a feature of Docker’s Swarm orchestration mode. Running individual containers directly, outside of Swarm, has no equivalent built-in gradual rollout behavior.

With appropriate parallelism, delay, and start-first ordering, the goal is that users experience no visible disruption at all, since the service as a whole continues serving requests throughout the entire process.

No. A rollback reverts which application code is running, not any external data changes that code already made while it was live. Data-level changes need to be handled with their own, separate compatibility and recovery planning.

It’s driven by the service’s configured failure action combined with health check results — when enough tasks in an update fail their health checks within the configured tolerance, Swarm applies whatever failure action the service was configured with, which can include an automatic rollback.

A standard rollback reverts to the immediately previous service specification. Reaching further back typically means explicitly redeploying that earlier version’s specification directly, rather than repeatedly issuing rollback commands.

Technically no — updates will still proceed using process state alone if no health check is configured. But without one, Swarm loses most of its ability to actually detect a bad release, which defeats much of the safety value rolling updates are meant to provide.

Rolling updates turn deploying a new version of a service from a risky, all-at-once event into a controlled, incremental process — replacing a small batch of tasks, pausing to verify health, and repeating until the whole service has moved to the new version, all while continuing to serve traffic throughout. Rollbacks are the natural safety net that makes this gradual approach trustworthy: whether triggered manually by an operator or automatically by a failed health check, they let a bad release be undone with the same careful, batch-by-batch discipline used to roll it out in the first place. Understanding the specific levers — parallelism, delay, start order, and the failure action — is what turns this from an abstract safety feature into a deployment strategy actually tuned to what each individual service can and can’t tolerate.