Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

swarm init and join

Create a swarm with docker swarm init, add workers and managers with join tokens, choose the advertise address and leave or reset a cluster safely.

Creating a swarm takes one command on the first machine and one command on every other machine. In this lesson you will initialize a cluster, read what Docker tells you, join workers and managers with tokens, and learn how to undo it all. The commands are shown read-only; run them on the practice machines from the previous lesson.

Initializing the first manager

On manager1:

CONSOLE
$ docker swarm init --advertise-addr 192.168.56.11

Docker prints a message saying that the current node is now a manager, followed by a ready-made docker swarm join --token ... 192.168.56.11:2377 command for workers. Three things happened at once:

  1. The Engine switched into swarm mode and became the first manager (and the leader).
  2. A new certificate authority (CA) was created for the swarm. See Security and PKI.
  3. Two join tokens (one for workers, one for managers) were generated.

Why --advertise-addr?

The advertise address is the IP (and optionally port) that other nodes use to reach this manager. If the machine has several network interfaces, Docker refuses to guess and asks you to choose, with an error that mentions the multiple addresses. Always pass it explicitly on real servers. A related option, --listen-addr, sets where the node listens for management traffic (default 0.0.0.0:2377).

You can also pass an interface name: --advertise-addr eth1. If the node sits behind NAT, advertise the address other nodes can actually reach.

Joining workers

Copy the join command Docker printed and run it on worker1 and worker2:

CONSOLE
$ docker swarm join --token <worker-token> 192.168.56.11:2377

The reply confirms that the node joined as a worker. If you lost the command, ask a manager to print it again:

CONSOLE
$ docker swarm join-token worker
$ docker swarm join-token manager

Note the token prefix: it starts with SWMTKN-1- and contains a fingerprint of the cluster's CA, so a joining node can verify it is talking to the real swarm and not an impostor.

Joining more managers

A swarm with one manager has no fault tolerance. Add two more managers with the manager token:

CONSOLE
$ docker swarm join --token <manager-token> 192.168.56.11:2377

Or promote existing workers later: docker node promote worker1. Why three managers is the right number is the topic of Raft and quorum.

Inspecting the cluster

From a manager:

CONSOLE
$ docker node ls

The listing shows an ID, hostname, status (Ready/Down), availability (Active/Pause/Drain) and a manager status column. The leader is marked Leader; other managers show Reachable; workers show nothing there. A * marks the node you are talking to. Workers cannot run docker node ls: only managers can query cluster state.

CONSOLE
$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'

ControlAvailable is true on managers and false on workers.

Tokens are secrets

Anyone holding a worker token can add a node to your swarm and receive work, including secrets assigned to it. Treat tokens like passwords. If one leaks, rotate it:

CONSOLE
$ docker swarm join-token --rotate worker

Existing nodes are unaffected; only new joins need the new token.

Leaving and resetting

A worker leaves with:

CONSOLE
$ docker swarm leave

The node's status in the cluster becomes Down and a manager must remove the entry:

CONSOLE
$ docker node rm worker2

A manager must usually be demoted first, or you use docker swarm leave --force, which is dangerous because it can destroy quorum. For the very last manager, leave --force dismantles the whole swarm.

If every manager is lost but one machine still has the swarm data, you can build a new single-manager cluster from it:

CONSOLE
$ docker swarm init --force-new-cluster --advertise-addr 192.168.56.11

That keeps services, secrets and configs but discards the old membership.

Understanding the join flow

sequenceDiagram
  participant W as New node
  participant M as Manager
  W->>M: join request with token on port 2377
  M->>M: check token role and CA fingerprint
  M->>W: issue node certificate signed by swarm CA
  W->>M: mutual TLS from now on
  M->>W: start assigning tasks

A token proves the right to join; after that the node authenticates with its own certificate.

Stand-in: parse a join token

Real tokens have a fixed structure: a version, a hash of the CA certificate and a random secret. The next editor is a stand-in with a made-up token (not a real one) that splits the parts, so you can see the shape.

Python Stand-in: anatomy of a join token

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: what happens on init and join

This tiny model keeps a cluster as a dictionary. It shows the rules from this lesson: workers cannot list nodes, the first node is the leader.

Python Stand-in: cluster membership

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. Why should you pass --advertise-addr on a server with several network interfaces?

    Docker cannot guess which interface other nodes should use, and refuses or may choose wrongly.
  2. 2. Which command prints the command a new manager should run?

    docker swarm join-token manager (or worker) prints the join command including the token.
  3. 3. A worker token leaked. What do you do?

    Rotation invalidates the old token for new joins without touching nodes that are already members.

Summary

  • docker swarm init --advertise-addr IP creates the swarm and the first manager.
  • Workers and managers join with different tokens on port 2377.
  • docker node ls works only on managers.
  • Rotate leaked tokens, and use --force-new-cluster only for recovery.

Next: Your First Swarm Service