Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 38 ยท Scaling and Updates

Scaling Services Up and Down in Docker Swarm

Scale replicated services with docker service scale and update --replicas, understand how Swarm rebalances, what limits scaling, and how to plan node capacity.

Scaling is the reason many teams adopt an orchestrator. When traffic grows you add replicas; when it falls you remove them. In Swarm this is a one-line command, but the effect depends on the scheduler, on your nodes' capacity and on whether the application can actually run more than one copy.

Swarm is not available on this site, so the commands are read-only text and the Python blocks are labelled stand-ins that model replica counts and capacity.

Changing the replica count

Terminal
docker service scale web=10
docker service scale web=10 api=4
docker service update --replicas 6 web
docker stack deploy -c stack.yml shop      # replicas from the file

All of these set the desired state; the orchestrator then closes the gap. Scaling up creates new tasks that the scheduler places on eligible nodes. Scaling down shuts down the surplus tasks, choosing the ones on the busiest nodes first. Each running task keeps going: Swarm does not move healthy tasks around just to balance the cluster.

Check the result:

Terminal
docker service ls
docker service ps web
docker service ls --filter name=web

The REPLICAS column looks like 7/10 while tasks are starting. A task goes through the states new, pending, assigned, accepted, preparing, starting, running. If the service sits at 7/10 for long, docker service ps web shows why: a pending task lists the unmet constraint or the missing resources.

A tip about stacks and scale

If you scale a stack's service by hand and later redeploy the stack, the file wins: replicas return to the number written in stack.yml. Decide where the truth lives. For production, keep the number in the file (or in a variable such as ${WEB_REPLICAS}) and scale by redeploying, so Git history shows every capacity change.

What limits scaling

  • Capacity. Each task needs CPU and memory. Without reservations Swarm only spreads by task count; with reservations the scheduler refuses nodes that cannot satisfy them (see Resource Limits).
  • Placement rules. A constraint such as node.labels.disk == ssd caps replicas at what those nodes can host. max_replicas_per_node does the same on purpose.
  • Published ports. With the routing mesh the published port is shared by all replicas, so scaling needs no port changes. With mode: host, only one task per node can bind the port.
  • State. Services that keep local data cannot be copied blindly. A database with a node-local volume must stay at one replica unless it has its own replication.
  • Downstream limits. Ten API replicas with a pool of 50 connections each need 500 database connections.

Stateless web and API services scale easily. Anything with local files, in-memory sessions or leader-only jobs needs design work first.

flowchart LR
  D["Desired: 10"] --> O["Orchestrator"]
  O -->|"running 7"| G{"gap = 3"}
  G -->|"create tasks"| S["Scheduler"]
  S --> N["Eligible nodes"]

The orchestrator compares desired and actual state; the scheduler places the missing tasks.

Scaling down safely

Docker sends SIGTERM to the container and waits for stop_grace_period (default 10 seconds) before SIGKILL. A web server that handles SIGTERM by finishing in-flight requests loses nothing; one that ignores it drops connections. Set the period to cover your longest normal request:

YAML
services:
  api:
    stop_grace_period: 30s

Also make sure the process receives the signal (use the exec form CMD ["node", "server.js"], not a shell wrapper).

Autoscaling

Swarm has no built-in autoscaler. Teams either script it (a small program that reads metrics and calls the Docker API) or choose capacity in advance. If automatic scaling on CPU or queue length is a core requirement, that is one reason to consider Kubernetes (see Swarm vs Kubernetes).

Stand-in: reconcile desired and actual state

Python Stand-in: a reconciliation loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: how many replicas fit?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Scaling a service that uses a node-local volume.
  • Forgetting database connection limits.
  • Scaling by hand and then redeploying a stack file that says something else.
  • Ignoring stop_grace_period, which causes dropped requests on every scale-down.
  • Assuming Swarm will rebalance tasks when you add a node: new nodes receive only new tasks. To spread existing ones, use docker service update --force service.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does docker service scale web=10 change?

    Scaling sets desired state. The orchestrator and scheduler do the rest.
  2. 2. You add a new worker. What happens to existing running tasks?

    Swarm does not migrate healthy tasks. docker service update --force redistributes them.
  3. 3. Does Swarm autoscale services by CPU load?

    There is no built-in autoscaler in Swarm.
  4. 4. What does stop_grace_period control?

    It gives the application time to finish in-flight work on shutdown.

Summary

  • docker service scale and update --replicas set desired state; the orchestrator closes the gap.
  • Capacity, placement rules, state and downstream limits bound how far you can scale.
  • Set stop_grace_period and handle SIGTERM for clean scale-downs.
  • Swarm has no autoscaler, and new nodes only receive new tasks.

Next: Rolling Updates in Docker Swarm