DevOps Peach

Docker & Kubernetes · Docker Swarm – Basic Orchestration · Lesson 2 of 3

Creating and managing a swarm

docker swarm init creates a swarm and prints the join command; join-token prints it again; docker node manages nodes, and drain prepares maintenance.

Practice interactively →

Swarm mode is off by default. Turn it on by creating a new swarm on the first node, or by joining an existing one.

docker swarm init --advertise-addr 192.0.2.10        # manager1 becomes a manager (Leader)
docker swarm join-token worker                       # print the worker join command again
docker swarm join --token SWMTKN-1-... 192.0.2.10:2377   # run on the new node
docker node ls                                       # only works on a manager

sequenceDiagram
  participant M as manager1 (192.0.2.10)
  participant W as worker1
  M->>M: docker swarm init --advertise-addr 192.0.2.10
  M-->>W: join command + worker token
  W->>M: docker swarm join --token ... 192.0.2.10:2377
  M-->>W: TLS certificate, starts receiving tasks

--advertise-addr is the IP other nodes use to reach the manager; it is required when the host has several IPs. The worker and manager tokens differ; anyone with the manager token can add managers, so keep it secret and rotate it with --rotate if it leaks.

Ports to open between nodes

Port Used for
TCP 2377 Cluster management (join, Raft)
TCP/UDP 7946 Node-to-node communication (gossip)
UDP 4789 Overlay network traffic (VXLAN)

Managing nodes

Command Meaning
docker node inspect worker1 --pretty Readable node details
docker node update --availability drain worker1 Stop assigning new tasks and move existing tasks elsewhere, for maintenance
docker node update --availability pause worker1 Stop assigning new tasks, but existing tasks keep running there
docker node update --availability active worker1 Accept tasks again
docker swarm leave The node leaves the swarm; a manager needs --force and may break quorum

When the last manager leaves, the cluster state goes with it; only a backup restore or a fresh init remains.

Building a practice cluster

You need several Docker hosts that can reach each other: three small cloud VMs, local VMs created with a tool such as Multipass or Vagrant, or the browser-based Play with Docker playground. Give each a fixed private IP and open the swarm ports between them. One manager and two workers are enough to try scheduling and failover; three managers let you test quorum.

Checking swarm status

docker info has a Swarm section showing whether the node is active, its role, the cluster ID, and the managers' addresses. docker node ls (managers only) lists every node with status (Ready or Down) and availability (Active, Pause, Drain).

Addresses and certificates

Option Purpose
--advertise-addr Address other nodes use to contact this node
--listen-addr Address the node listens on for cluster traffic, when it differs
--data-path-addr Separate interface for overlay data traffic
docker swarm ca --rotate Issue a new root CA and node certificates
docker swarm update --cert-expiry 720h Change how often node certificates renew

Node certificates renew automatically; rotating the CA is for when a manager may have been compromised.

Recovering from losing quorum

If most managers are gone for good, the remaining manager cannot change anything. On one surviving manager, docker swarm init --force-new-cluster --advertise-addr 192.0.2.10 creates a new single-manager cluster that keeps the services and state, after which you add managers again. Restoring a backup of /var/lib/docker/swarm is the fallback when no manager survives.

Removing a node cleanly

  1. docker node update --availability drain worker2 moves its tasks away.
  2. On the node, docker swarm leave.
  3. On a manager, docker node rm worker2 removes the Down entry.

Demote a manager to worker before removing it, so quorum is calculated on the remaining managers.

Practice interactively →