18.2.2.2 Swarm Global Services

Swarm global services run exactly one task instance on every eligible node in the cluster automatically, including any node that joins later, making them the natural fit for infrastructure-level workloads that genuinely need a presence everywhere rather than a deliberately chosen, fixed replica count.

The defining behavior: one per node, automatically

Unlike a replicated service with an explicitly set replica count, a global service's effective instance count is determined entirely by how many eligible nodes exist in the cluster at any given moment, with no replica count to configure at all:

docker service create --mode global my-log-collector

docker service ps my-log-collector

NODE      DESIRED STATE
node-1    Running
node-2    Running
node-3    Running

If a fourth node joins the cluster afterward, Swarm automatically schedules a new task instance of this global service onto it without any explicit command needed, which is precisely the behavior that makes global mode the right fit for anything needing guaranteed, automatic presence on every current and future node.

Natural use cases for global mode

Log shippers, metrics collection agents, security scanning daemons, and any other workload whose entire purpose is observing or instrumenting the host it runs on are the clearest fit for global mode, since their value depends specifically on running everywhere, with no meaningful concept of "three replicas" the way an ordinary application service would have:

docker service create --mode global \
  --mount type=bind,src=/var/lib/docker/containers,dst=/var/lib/docker/containers,ro \
  fluent-bit-agent

A log collector running as a global service automatically gains visibility into every node's containers as the cluster grows, with no manual scaling decision ever needed to keep pace with cluster size, since the global mode mechanism inherently keeps the collector's presence aligned with the cluster's actual current node count.

Constraints still apply to limit eligible nodes

While a global service has no explicit replica count, placement constraints still control which nodes are actually eligible to receive an instance, useful when the global presence should be limited to a specific subset of nodes rather than truly every node in the cluster:

services:
  gpu-monitor:
    deploy:
      mode: global
      placement:
        constraints:
          - node.labels.gpu == true

This combination, global mode scoped by a constraint, runs exactly one instance on every node matching the constraint, automatically adjusting as nodes meeting that specific criterion join or leave, which is meaningfully different from an unconstrained global service that runs on literally every node regardless of any particular characteristic.

Global-job mode for finite, per-node work

Paired with replicated-job mode covered for replicated services, global-job mode runs a task to completion exactly once on every eligible node, suited to a finite, per-node operation, a one-time node-level configuration step, a per-node diagnostic check, rather than a continuously running global service:

docker service create --mode global-job my-node-diagnostic

Each node runs the diagnostic exactly once and the task completes, rather than continuing to run indefinitely the way an ordinary global service would, which is the correct mode specifically for a workload with a genuine, natural per-node completion point.

Removing a global service

Removing a global service stops and removes its task instance from every node in the cluster simultaneously, the same straightforward removal behavior as any other service type:

docker service rm my-log-collector

There is no equivalent of scaling a global service down incrementally the way a replicated service can be scaled to a smaller, non-zero replica count, since a global service's instance count is never an independently adjustable value in the first place.

Resource considerations for global services

Because a global service consumes resources on every eligible node simultaneously, its resource limits should be set with this multiplication in mind, a generous limit that seems reasonable for a single replicated service instance becomes a meaningfully larger aggregate resource commitment once multiplied across every node in a large cluster:

services:
  log-collector:
    deploy:
      mode: global
      resources:
        limits:
          memory: 128M
          cpus: "0.25"

Keeping a global service's per-node footprint deliberately modest is generally appropriate, since its value comes from ubiquitous presence rather than from substantial per-instance capacity, and an oversized global service resource allocation can meaningfully reduce the capacity available to ordinary application workloads across the entire cluster.

Common mistakes

• Using replicated mode with a manually maintained replica count for a workload that should instead use global mode to automatically track the cluster's actual current node count.
• Not applying a placement constraint when a global presence should be limited to a specific subset of nodes rather than truly every node in the cluster.
• Using ordinary global mode for a workload with a genuine, finite, per-node completion point, rather than global-job mode designed specifically for that case.
• Setting an unnecessarily generous resource limit on a global service without accounting for how that limit multiplies across every node it actually runs on.
• Attempting to scale a global service to a specific instance count, when its instance count is inherently tied to eligible node count rather than being an independently settable value.

Swarm global services automatically maintain exactly one instance per eligible node, scaling implicitly with the cluster's own growth and shrinkage, which makes them the natural, low-maintenance fit for infrastructure-level workloads needing ubiquitous presence, with placement constraints available to scope that presence and global-job mode available for the distinct case of a finite, per-node operation rather than a continuously running service.