Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 38 ยท Services and Tasks

Placement Constraints and Preferences

Control where Swarm runs tasks with placement constraints, spread preferences and max replicas per node, using node attributes and labels.

By default the scheduler places tasks wherever there is room, favouring the least loaded nodes. Often you want more control: run the database only on nodes with SSD disks, keep the web tier off managers, spread replicas over availability zones. Swarm offers three tools: constraints (hard rules), preferences (soft spreading) and max replicas per node.

Constraints: hard filters

A constraint removes nodes that do not match. If no node matches, tasks stay pending.

CONSOLE
$ docker service create --name db \
    --constraint 'node.labels.disk==ssd' \
    --constraint 'node.role==worker' \
    postgres:17

Multiple constraints are combined with AND. The operators are == and != (there is no OR and no regex; use labels cleverly instead).

Available attributes:

Attribute Example Meaning
node.id node.id==abc123 Node ID.
node.hostname node.hostname!=manager1 Hostname.
node.role node.role==manager manager or worker.
node.platform.os node.platform.os==linux Operating system.
node.platform.arch node.platform.arch==arm64 CPU architecture.
node.labels.<key> node.labels.zone==a Label set with docker node update.
engine.labels.<key> engine.labels.region==eu Label from the node's daemon.json.

Quote constraints in the shell so != and == are not mangled. Add or remove them on a running service with --constraint-add and --constraint-rm, which triggers a rolling replacement of tasks that no longer fit.

Common patterns:

  • Keep application workloads off managers: node.role==worker.
  • Pin a stateful service to the node that holds its data: node.hostname==db1, or better a label like node.labels.db==true.
  • Run on specific hardware: node.labels.gpu==true.
  • Mixed architectures: node.platform.arch==amd64 so an image without an arm64 variant does not get scheduled on ARM nodes.

Preferences: spreading

A preference is a soft rule that affects how eligible nodes are chosen. The only strategy is spread:

CONSOLE
$ docker service create --name web --replicas 6 \
    --placement-pref 'spread=node.labels.zone' \
    nginx:1.27

Swarm divides the tasks as evenly as possible among the distinct values of the label (zone a, b, c), and inside each group it spreads further by load. With six replicas and three zones you get two per zone. If a zone has no capacity, the others take more: preferences never block scheduling.

You can chain preferences (the first is applied first):

CONSOLE
--placement-pref 'spread=node.labels.zone' --placement-pref 'spread=node.labels.rack'

Nodes without the label are grouped together as one more "value".

Max replicas per node

CONSOLE
$ docker service create --name api --replicas 3 --replicas-max-per-node 1 myorg/api:1

This caps the number of tasks of the service on one node. It turns "spread if possible" into "spread, or wait". With four replicas and three nodes the fourth stays pending. It is the practical way to say "never put two replicas on the same machine".

Combining the tools

flowchart LR
  A["All nodes"] --> B["Constraints filter"]
  B --> C["Resources filter"]
  C --> D["Max per node filter"]
  D --> E["Preferences order the rest"]
  E --> F["Task assigned"]

Constraints, resources and caps decide who is eligible; preferences decide who is picked among them.

Inspect what a service uses:

CONSOLE
$ docker service inspect --format '{{json .Spec.TaskTemplate.Placement}}' api

Common mistakes

  • Constraint typos. node.label instead of node.labels matches nothing, and tasks stay pending with "no suitable node".
  • Labels missing on new nodes. A node that joins without the label is silently excluded. Script your node setup.
  • Pinning a stateful service to one node and calling it highly available. It is not: it is pinned.
  • Forgetting the architecture in mixed clusters.
  • Expecting rebalancing. Changing labels or constraints affects new and replaced tasks; use docker service update --force to redistribute.

Stand-in: a placement engine

The editor below implements constraints (equality and inequality on labels), a max-per-node cap and a spread preference. Change the inputs to see how tasks are distributed. It illustrates the algorithm; Swarm's real scheduler has more filters (resources, platform) and tie-breaking rules.

Python Stand-in: placement engine

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.

Stand-in: constraint syntax checker

A quick validator for the constraint strings, to practise the syntax rules above.

Python Stand-in: validate 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 is a valid constraint to keep a service off manager nodes?

    node.role accepts manager or worker, and != is a valid operator.
  2. 2. What happens when a constraint matches no node?

    Constraints are hard rules; unplaceable tasks wait in the pending state.
  3. 3. How does --placement-pref spread=node.labels.zone differ from a constraint?

    Preferences influence the choice among eligible nodes; they never make a node ineligible.

Summary

  • Constraints (==, !=, AND only) are hard filters on node attributes and labels.
  • --placement-pref spread=... evenly distributes tasks across label values.
  • --replicas-max-per-node caps tasks per machine.
  • Placement applies to new tasks; use update --force to redistribute.

Next: Resource Limits and Reservations