Scale Docker Swarm Services with docker service scale

Traffic spikes, or a maintenance window calls for fewer replicas, and docker service scale changes a service's desired count on the fly. Allow about ten minutes if you already have manager access and know the service name. The examples use the Docker Community CLI 29.8.1 installed with docker-ce-cli on this machine.

This command changes live service state. Scaling up schedules more tasks and can consume CPU, memory, storage and network capacity. Scaling down stops tasks; scaling to zero stops all replicas while leaving the service definition in the swarm. Record the current count before changing it so you have a clear recovery value.

1. Confirm the command and your access

docker service scale is a Swarm manager command. Run it from a manager node, using the Docker context that points at the intended swarm. You normally do not need sudo; use it only if your local Docker access policy requires it.

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker service scale --help
Usage:  docker service scale SERVICE=REPLICAS [SERVICE=REPLICAS...]

Scale one or multiple replicated services

Options:
  -d, --detach   Exit immediately instead of waiting for the service to converge

The installed manual documents one option, -d or --detach. Without it, the command waits for the service update to converge. With it, the command returns before the tasks have necessarily reached their target.

Checkpoint: if the help command fails, stop here. A missing Docker daemon, the wrong context, or a non-manager node needs fixing before you change a service.

2. Inspect the current replica count

List the service before changing it. The REPLICAS column shows current tasks against the desired count, such as 3/3. Save the desired number as your rollback value.

$ docker service ls --filter name=SERVICE_NAME
ID             NAME          MODE         REPLICAS  IMAGE
SERVICE_ID     SERVICE_NAME  replicated   3/3       IMAGE_NAME

Replace every uppercase placeholder with a value from your swarm. A name filter can match more than one service, so check the full output before proceeding. If the service is already below its desired count, scaling it again may add tasks without fixing the underlying scheduling or image problem.

3. Scale one replicated service

Pass the service name and target count as one argument separated by =. This example changes web to five replicas:

$ docker service scale web=5
web scaled to 5

The output confirms that Docker accepted the desired count. It does not guarantee five tasks are running at that instant: the manager still has to schedule tasks, and nodes must have the image, capacity and placement conditions the service requires.

Wait for the command to return, then inspect the actual state:

$ docker service ls --filter name=web
ID             NAME  MODE        REPLICAS  IMAGE
SERVICE_ID     web   replicated  5/5       IMAGE_NAME

Your IDs and image text will differ. The useful check is the 5/5 relationship, not the exact formatting. To see individual task states and errors, run:

$ docker service ps web

Look at DESIRED STATE, CURRENT STATE and ERROR. A task in Pending, Rejected or Failed needs diagnosis, not repeated scaling.

4. Scale several services together

Give one SERVICE=REPLICAS argument for each replicated service. Useful when a small application needs its front end and worker pool changed in the same operator action:

$ docker service scale frontend=4 worker=8
frontend scaled to 4
worker scaled to 8
$ docker service ls
ID             NAME      MODE        REPLICAS  IMAGE
FRONTEND_ID    frontend  replicated  4/4       FRONTEND_IMAGE
WORKER_ID      worker    replicated  8/8       WORKER_IMAGE

Check both services after the command. A successful line for one service does not make the other healthy. If a multi-service command reports an error, inspect each service separately before deciding whether to retry.

5. Use detached mode only when you will monitor it

--detach returns immediately instead of waiting for convergence, useful for automation or a large change where a separate monitoring step is already part of the runbook:

$ docker service scale --detach web=10
web scaled to 10
$ docker service ls --filter name=web
$ docker service ps web

Do not treat the immediate return as proof that ten tasks are running. Poll docker service ls, then inspect docker service ps if the numerator stays below the target or a task reports an error. In an unattended script, add an explicit timeout and failure path rather than waiting forever.

6. Handle the boundaries

The command applies to replicated services, including replicated jobs, not global services. A global service runs one task per eligible node, so a numeric replica target does not describe its mode, and Docker rejects an attempt to scale one:

$ docker service scale global-agent=10
global-agent: scale can only be used with replicated or replicated-job mode

Check the MODE column before changing a service. If it says global, change the relevant node availability or placement configuration instead of forcing a replica count.

Warning: scaling to zero is a deliberate service interruption:

$ docker service scale web=0
web scaled to 0
$ docker service ls --filter name=web
ID             NAME  MODE        REPLICAS  IMAGE
SERVICE_ID     web   replicated  0/0       IMAGE_NAME

Use it only when stopping all tasks is acceptable. To restore the saved count, run the same command with that count, for example docker service scale web=3, then verify the result. Scaling back does not undo requests already lost, temporary capacity pressure, or other side effects from the interruption.

7. Diagnose a service that will not converge

If the desired count is higher than the running count, inspect task errors first:

$ docker service ps --no-trunc web
$ docker service inspect web

Common causes include unavailable nodes, placement constraints, insufficient reserved resources, an image workers cannot pull, and a task that exits or fails its health check. The scheduler maintains the desired state, so repeating the same scale command does not repair any of those conditions.

If you changed the count by accident, restore the number recorded in step 2 and wait for convergence. If the service is unhealthy because of its image, command, environment or placement configuration, use the appropriate docker service update or deployment rollback procedure. Do not delete the service merely to make a scale error disappear: removal destroys the service definition and is a separate, more disruptive action.

Done means