Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 38 ยท Swarm Architecture

Node Management

Manage Docker Swarm nodes: list and inspect them, drain for maintenance, pause scheduling, promote and demote, add labels and remove nodes safely.

A swarm is a living thing. Machines need kernel updates, disks fill, and some nodes have GPUs while others do not. The docker node family of commands is how you look after the machines in the cluster. All of them run on a manager.

Listing and inspecting

CONSOLE
$ docker node ls
$ docker node inspect --pretty worker1
$ docker node ps worker1

inspect --pretty shows the role, availability, hostname, platform (architecture and OS), resources (CPUs and memory), the Docker Engine version and labels. node ps shows the tasks assigned to that node. You can filter lists: docker node ls --filter role=manager.

A node's status (Ready, Down) tells whether managers can reach it. Its availability (Active, Pause, Drain) is something you set. Do not mix them up: a node can be Ready yet Drain, meaning it is healthy but receives no tasks.

Availability: active, pause, drain

Availability New tasks? Existing tasks? Use it for
active Yes Stay Normal operation
pause No Stay Stop adding load, investigate
drain No Moved elsewhere Maintenance and reboots
CONSOLE
$ docker node update --availability drain worker2

Swarm shuts down the tasks on worker2 and starts replacements on other nodes. Once the work is done, the node is empty and you can update it, reboot it or take it out of service. Afterwards:

CONSOLE
$ docker node update --availability active worker2

Important: returning a node to active does not move old tasks back. Swarm never rebalances running tasks on its own, because that would cause needless restarts. New tasks (from scaling or updates) will use the node again. To rebalance, force an update: docker service update --force web.

A drained manager still takes part in Raft; draining affects only your workloads.

Promote and demote

CONSOLE
$ docker node promote worker1
$ docker node demote worker1

Promotion makes the node a manager (it joins the Raft group and gets a manager certificate). Demotion reverses it. Swarm refuses to demote a manager if that would break quorum. Combined, these are the safe way to move the manager role from one machine to another: promote the new one, wait until it is Reachable, then demote the old one.

Labels

Labels are key-value tags used in placement constraints and preferences (Placement).

CONSOLE
$ docker node update --label-add zone=a --label-add disk=ssd worker1
$ docker node update --label-rm disk worker1
$ docker node inspect --format '{{.Spec.Labels}}' worker1

There are two kinds of labels:

  • Node labels are set with docker node update and live in the swarm's state. Only managers can change them, which makes them trustworthy for placement. Reference them as node.labels.zone.
  • Engine labels are set in the daemon configuration (daemon.json, key labels) on the node itself. Reference them as engine.labels.region. They need a daemon restart to change, and the node's own admin controls them.

Use node labels for anything that matters for security, such as "this node may hold sensitive data".

Removing a node

CONSOLE
$ docker node demote manager3      # if it was a manager
$ docker swarm leave               # run ON the node
$ docker node rm manager3          # run on a manager

If the node is already dead, skip leave and use docker node rm --force <id>. Drain first when the node is alive, so tasks move cleanly.

A safe maintenance routine

flowchart LR
  A["drain node"] --> B["wait: tasks moved"]
  B --> C["update OS, reboot"]
  C --> D["node Ready again"]
  D --> E["set availability active"]

Drain, work, return. Do one node at a time so capacity and quorum stay healthy.

Stand-in: draining a node

This model moves tasks from a drained node to the others, choosing the least loaded target each time. It reproduces the behaviour, including the fact that re-activating a node does not move anything back.

Python Stand-in: drain and re-activate

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: label matching

Placement uses labels. This helper filters nodes by required labels, a preview of the next chapter's constraints.

Python Stand-in: filter nodes by label

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. What does docker node update --availability drain do?

    A drained node is empty of service tasks, which is what you want before maintenance.
  2. 2. After setting a drained node back to active, what happens to the old tasks?

    Swarm does not rebalance by itself. Use docker service update --force to redistribute.
  3. 3. Why prefer node labels over engine labels for sensitive placement rules?

    Engine labels are set by whoever controls the node's daemon, while node labels are controlled through the managers.

Summary

  • Status is what Swarm observes; availability is what you choose.
  • Drain before maintenance; return with active; nothing moves back by itself.
  • Promote and demote change the role; swap managers one at a time.
  • Node labels (set by managers) drive placement.

Next: Security and PKI