Safely Update a Docker Swarm Service and Roll It Back

docker service update changes a running Swarm service in place, replacing tasks as it goes. The examples use Docker Engine CLI 29.8.1 from docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, installed on the reference machine.

Allow 15 to 30 minutes, plus however long your service normally takes to become healthy. You need access to a Swarm manager and an existing service you are authorised to change. A worker cannot perform this operation. Docker commands may need membership of the local Docker group or an authorised sudo setup; use the access method already approved for your host.

Warning: service updates replace running tasks when their configuration requires it. That can interrupt traffic, consume registry credentials, or change a production workload. Confirm the service name, image and rollback plan before pressing enter.

1. Confirm the command available on this host

Start with a read-only check. It does not contact a Swarm manager or change a service:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker service update --help
Usage:  docker service update [OPTIONS] SERVICE

The installed manpage describes the same command as docker service update [OPTIONS] SERVICE. This is a Swarm command, so a standalone container is not a suitable test target. If the command is missing, stop and install the Docker CLI through your normal package process rather than copying flags from another host.

Checkpoint: you have confirmed the client version and are working against a Swarm manager context.

2. Inspect the service before changing it

Set the service name once, then inspect its current tasks and specification. Replace the placeholder with an exact name from your own Swarm:

$ SERVICE='web'
$ docker service inspect "$SERVICE" --pretty
$ docker service ps "$SERVICE" --no-trunc

Record the current image, replica count, published ports, update policy and task errors. The --pretty view is convenient for a human, while docker service inspect "$SERVICE" gives machine-readable JSON if you need to archive the full specification before a change.

Do not use a guessed service name or an image tag copied from a different deployment. If the service is not found, check docker context show and docker service ls. A correct command against the wrong manager can still change the wrong workload.

3. Apply one small, observable update

Change one meaningful property first. Updating an image is a representative example:

$ docker service update \
    --image 'registry.example.invalid/acme/web:2026.09.23' \
    "$SERVICE"
web

The returned line is normally the service name. With --image, the manager resolves the tag when it can, then creates replacement tasks using the resulting specification. A tag such as latest is movable, so a versioned tag or digest is easier to audit later.

Other common changes use the same command shape, such as adding an environment variable or changing the replica count:

$ docker service update --env-add 'APP_MODE=maintenance' "$SERVICE"
$ docker service update --replicas 4 "$SERVICE"

Each invocation creates another service update. Keep related changes together where that is safe, but avoid mixing an image change, a network removal and a resource limit change when you will need to identify a failure quickly.

4. Control the rollout when service disruption matters

Swarm updates can replace tasks gradually. Set the policy explicitly when the service needs a predictable pace:

$ docker service update \
    --image 'registry.example.invalid/acme/web:2026.09.23' \
    --update-parallelism 1 \
    --update-delay 30s \
    --update-monitor 30s \
    --update-failure-action pause \
    "$SERVICE"

Here, at most one task updates at a time, with a 30-second delay between batches. The monitor period gives Swarm time to observe an updated task, and pause stops the rollout once the configured failure threshold is reached. The safe values depend on replica count, startup time and traffic: a one-replica service cannot gain redundancy simply because the update is gradual.

Use docker service update --detach only when you deliberately want the client to return before convergence. The default waits for the update to proceed, which is usually easier to notice during a maintenance operation. For a command that produces a lot of progress output, --quiet suppresses that output but does not make the update any safer.

5. Verify the new tasks and service state

Immediately check both the service summary and the individual tasks:

$ docker service ls --filter "name=$SERVICE"
$ docker service ps "$SERVICE" --no-trunc
$ docker service inspect "$SERVICE" --format '{{.Spec.TaskTemplate.ContainerSpec.Image}}'

You want the desired and running replica counts to converge, new tasks to reach Running, and no recent task showing a rejection or repeated restart. The image output should match what you intended. A service can report the desired replica count while a task is still failing, so do not treat the first line of docker service ls as the only health check.

Test the application through its normal health endpoint or client path too. Docker task state proves the container process is running; it does not prove the application serves correct responses, can reach its dependencies, or has compatible data.

Checkpoint: the service specification, task state and application-level check all agree the update is healthy. Save the command output if you need an audit trail.

6. Roll back a bad update

If the new tasks fail or the application check is bad, stop sending more changes and use the service's previous specification:

$ docker service update --rollback "$SERVICE"
web
$ docker service ps "$SERVICE" --no-trunc

--rollback restores the configuration that was in place before the most recent update. It is a service-side operation, so keep watching the replacement tasks rather than assuming the returned service name means recovery is complete.

Do not combine a rollback with unrelated update flags. If the rollback itself needs a different delay or parallelism, set those policies in a planned maintenance procedure and verify the CLI version's rules first. If the service is still changing, wait for it to settle before issuing another command.

After recovery, inspect the task error and application logs before retrying. If the failure came from the image, use a known-good immutable reference. If it came from a configuration change, restore that setting deliberately and record why: rollback is recovery, not a substitute for finding the cause.

7. Force a restart only when that is the actual goal

A change to an update setting alone does not normally recreate tasks. Use --force when you explicitly need a rolling restart without changing the service parameters:

$ docker service update \
    --force \
    --update-parallelism 1 \
    --update-delay 30s \
    "$SERVICE"

This still disrupts tasks as they are replaced, and it can expose a bad image or failing dependency that had been hidden by long-running containers. Verify capacity and rollback history first. Do not use --force as a general-purpose way to make an uncertain update look active.

Done means