Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Stacks and Deployment

The deploy Key: Replicas, Placement and Policies

Master the deploy section of a stack file: replicated and global mode, placement constraints and preferences, restart policy, update_config, labels and endpoint_mode.

The deploy: section is the part of a stack file that only Swarm reads. It describes how a service runs on the cluster: how many copies, where they may be scheduled, what to do when they fail, and how updates roll out. Everything else in the service block describes the container itself.

Swarm is not available on this site, so the YAML below is read-only, and the Python blocks are labelled stand-ins that model scheduling decisions.

Mode and replicas

YAML
services:
  api:
    image: myorg/api:1.4
    deploy:
      mode: replicated     # the default
      replicas: 4
  agent:
    image: myorg/log-agent:2.0
    deploy:
      mode: global         # one task on every node

In replicated mode you choose the number of tasks and the scheduler spreads them. In global mode Swarm runs exactly one task on each node (and adds one when a new node joins): ideal for log shippers, monitoring agents and anything that must exist per host. A service cannot change mode after creation.

Placement constraints

A constraint is a hard rule: a task may only run on nodes that match. Constraints use node attributes and labels:

YAML
deploy:
  placement:
    constraints:
      - node.role == worker
      - node.labels.disk == ssd
      - node.hostname != maintenance-01

Common attributes are node.id, node.hostname, node.role (manager or worker), node.platform.os, node.platform.arch and node.labels.<key> (labels you set with docker node update --label-add disk=ssd node-3). If no node satisfies the constraints, tasks stay in pending state with a message such as "no suitable node (scheduling constraints not satisfied)". That message in docker service ps is your first clue when a deploy hangs.

Databases are the classic case: pin them to a labelled node, because a named volume lives on one host.

Placement preferences

A preference is soft. The most useful one spreads tasks evenly over the values of a label, such as availability zones:

YAML
deploy:
  replicas: 6
  placement:
    preferences:
      - spread: node.labels.zone

With nodes labelled zone=a and zone=b, Swarm tries to put three tasks in each. If a zone has no capacity, tasks still run elsewhere, because preferences never block scheduling. You can also set max_replicas_per_node: 1 to forbid two tasks of the service on one node.

flowchart TD
  S["Scheduler"] -->|filter| C["Constraints<br/>(hard)"]
  C -->|then| P["Preferences<br/>(soft: spread)"]
  P -->|then| R["Pick the least loaded eligible node"]

Constraints remove nodes; preferences order the nodes that remain.

Restart policy

YAML
deploy:
  restart_policy:
    condition: on-failure    # none | on-failure | any (default)
    delay: 5s
    max_attempts: 3
    window: 120s

This governs task restarts on the same node; if a node dies, the scheduler creates replacement tasks elsewhere regardless. max_attempts counts failures within window. After the attempts are used up, Swarm stops restarting that task but still replaces it to keep the replica count, so a crash-looping container shows up as a long list of shut-down tasks in docker service ps.

update_config and rollback_config

YAML
deploy:
  update_config:
    parallelism: 2
    delay: 10s
    order: start-first       # or stop-first (default)
    failure_action: rollback # pause | continue | rollback
    monitor: 30s
  rollback_config:
    parallelism: 1
    order: stop-first

These control rolling updates and are explored in Rolling Updates.

Other keys you will meet

  • labels: under deploy label the service (not the container), useful for reverse proxies such as Traefik.
  • endpoint_mode: vip (default) gives the service one virtual IP that load-balances; dnsrr returns the task IPs from DNS instead.
  • resources: sets limits and reservations (Resource Limits).

Stand-in: a tiny scheduler

Python Stand-in: constraints then spread

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: global mode follows the node list

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

  • Pinning a database to a node with a constraint but forgetting that the label does not exist yet (the task stays pending).
  • Using max_attempts: 1 and thinking the service is "stopped" after a crash; Swarm still replaces tasks.
  • Setting replicas on a global service; it is invalid.
  • Treating preferences as guarantees.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which mode runs exactly one task on every node?

    Global services get one task per node, including nodes that join later.
  2. 2. What happens when no node satisfies a service's placement constraints?

    Constraints are hard rules. Check docker service ps for the pending reason.
  3. 3. Which is a soft rule that tries to distribute tasks evenly?

    Preferences guide placement but never block scheduling.

Summary

  • deploy: describes how Swarm schedules and manages a service; the rest of the block describes the container.
  • Replicated services have a replica count; global services run one task per node.
  • Constraints are hard filters on node attributes and labels; preferences such as spread are soft.
  • restart_policy handles task failures; update_config and rollback_config control rollouts.

Next: Stack Commands, Environments and Overrides