Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท Services and Tasks

Replicated and Global Services

Understand the two Swarm service modes: replicated services with a fixed count and global services with one task per node, plus when to use each.

A service runs in one of two modes, chosen when you create it and impossible to change afterwards. The mode decides how Swarm calculates the number of tasks. Picking the right one is a design decision: a web API and a log shipper have very different needs.

Replicated services

In replicated mode (the default) you say how many tasks you want, and the scheduler places that many anywhere in the cluster.

CONSOLE
$ docker service create --name api --replicas 5 myorg/api:1
$ docker service scale api=8

Properties:

  • Count is independent of the number of nodes: 5 tasks on 3 nodes is fine, some nodes will run two.
  • You change capacity with scale or update --replicas.
  • Good for stateless applications: web servers, APIs, workers.

Multiple tasks may land on the same node. If you need them on different nodes, ask for it with --replicas-max-per-node 1 or a spread preference (placement). With --replicas-max-per-node 1 and more replicas than nodes, the extra tasks stay pending.

Global services

In global mode Swarm runs exactly one task on every eligible node, now and in the future.

CONSOLE
$ docker service create --name agent --mode global myorg/monitoring-agent:3

Properties:

  • You cannot set --replicas; the count equals the number of eligible nodes.
  • When a new node joins, a task is started there automatically. When a node leaves, its task disappears.
  • Draining a node removes its task and does not replace it elsewhere (there is no extra copy to place).
  • Constraints still apply: --mode global --constraint 'node.labels.gpu==true' runs one task on each GPU node only.

Typical uses are node-level agents: log collectors, monitoring exporters (like node-exporter), security scanners, backup agents, or a local cache that every node should have.

Replicated or global?

Replicated You choose how many
Global One per eligible node

The mode cannot be changed after creation.

1 / 2

Replicated jobs (run to completion)

Newer Docker releases also have two job modes for work that finishes: --mode replicated-job and --mode global-job. Their tasks run to completion and are not restarted forever. Options like --replicas (how many must complete) and --max-concurrent apply to replicated-job. They suit migrations and batch tasks. Check docker service create --help on your version to confirm that the flags are available.

Switching mode

You cannot convert a service in place. Create a new service in the other mode and remove the old one (and plan any downtime or overlapping ports):

CONSOLE
$ docker service rm agent
$ docker service create --name agent --mode global ...

What the REPLICAS column shows

For replicated services you see 3/5. For global services you see 3/3 where the denominator is the number of eligible nodes, and the mode column says global.

Choosing the replica count

More replicas give more capacity and resilience but cost resources. A rough rule: at least two replicas for anything user-facing (so one can restart without an outage), and spread across nodes. The number of replicas is also an input to rolling updates: with --update-parallelism 1 and 2 replicas, each update step takes half of your capacity down.

Stand-in: replicated versus global scheduling

The simulator below places tasks both ways on a changing cluster. Notice how global tasks follow nodes while replicated ones stay a fixed count.

Python Stand-in: two modes

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.

Real replicated services do not rebalance when a node joins; the stand-in recomputes from scratch only to keep the code short.

Stand-in: eligible nodes with constraints

Global tasks run on every node that satisfies the constraints. This check mimics --constraint 'node.labels.gpu==true'.

Python Stand-in: global with a constraint

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.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which mode starts one task on every eligible node automatically?

    Global mode follows the node list: new nodes get a task, removed nodes lose it.
  2. 2. You need a log collector on every node of the cluster. What do you create?

    A global service adapts to nodes joining and leaving without manual scaling.
  3. 3. Can you change a replicated service to global with docker service update?

    The service mode is fixed at creation time.

Summary

  • Replicated: you set the count; global: one per eligible node.
  • Use global for node agents, replicated for applications.
  • The mode cannot be changed; recreate the service.
  • Constraints narrow the set of nodes in both modes.

Next: Task Lifecycle