Roll a Swarm Service Onto a New Image

Roll a Swarm Service Onto a New Image

Update a running swarm service to a new image using its current version index.

1. Read the service's current spec and version index. The version index is required by the update call — it is what makes the write conditional on nobody else having changed the service in the meantime.
2. Submit the updated spec pinned to the version index read above, rolling tasks onto the new image start-first so capacity is never dipped below the target during the update.
3. List the service's tasks desired to be running so the caller can watch the new tasks come up and the old ones drain during the rolling update.
4. Read the service back to check the update status the swarm reports. A state of "completed" means the rollout landed; "paused" or "rolling_back" means it tripped the failure action.
5. Tail the aggregated logs across the service's tasks with timestamps, so a failed rollout can be diagnosed without hunting for individual containers.

What you'll need to have ready

• serviceName: ID or name of the service to update.
• newImage: New image to roll out, ideally pinned by digest.
• replicas: Desired replica count after the update.
• parallelism: How many tasks to update simultaneously.
• updateDelay: Nanoseconds to wait between updating task batches.
• registryAuth: Base64url-encoded auth configuration for pulling from a private registry.
• tail: Number of log lines to return from the end of the service logs, or "all".

For your developer

Arazzo workflow docker:rolling-update-service, 5 operations: ServiceInspect → ServiceUpdate → TaskList → ServiceInspect → ServiceLogs. Specs on APIs.io.