18.2.1.1 Swarm Cluster Init

Swarm cluster init covers the practical mechanics of actually bootstrapping a new cluster correctly the first time, choosing the right network interface to advertise, understanding and securing the join tokens that control who can add new nodes, and ensuring the specific network ports Swarm depends on are actually open between every intended cluster member before initialization is even attempted.

Choosing the correct advertise address

On a host with multiple network interfaces, explicitly specifying which address other nodes should use to reach this manager is essential; allowing Docker to guess can result in an address that is only reachable from the host itself, not from other nodes that need to actually join the cluster over the network:

ip addr show

docker swarm init --advertise-addr 10.0.1.5

Choosing the interface address actually reachable by every other intended cluster node, typically a private, internal network address rather than a public-facing one, avoids a cluster that initializes successfully but that no other node can actually join because the advertised address is not genuinely reachable from where they are.

Required network ports

Swarm mode depends on several specific ports being open between every node intended to join the cluster, and a firewall blocking any of them produces a confusing, hard-to-diagnose join failure rather than an obviously port-related error:

2377/tcp  - cluster management communication
7946/tcp,udp - node-to-node communication (gossip protocol)
4789/udp  - overlay network data traffic (VXLAN)

nc -zv 10.0.1.5 2377

Verifying connectivity on each of these specific ports between every intended node before attempting initialization or join, rather than discovering a blocked port only after a confusing join failure, saves considerable troubleshooting time during initial cluster setup.

Generating and securing join tokens

Initialization produces two distinct join tokens, one for worker nodes and one for manager nodes, and treating these tokens with appropriate care matters since possessing the manager token grants the ability to join the cluster with full manager privileges:

docker swarm join-token worker

docker swarm join-token manager

docker swarm join-token --rotate worker

Rotating a token, particularly if it may have been exposed inappropriately, invalidates the previous token entirely, requiring any future joins to use the newly generated one, which is a reasonable, available response if a token's confidentiality is ever in question.

Distributing tokens securely

The actual join token should be distributed to new nodes through a secure channel, a secrets manager, an encrypted configuration management tool, rather than through plaintext means like an unencrypted chat message or a committed configuration file, since the token itself is effectively a credential granting cluster access:

vault kv put secret/swarm/worker-token value="$(docker swarm join-token -q worker)"

Treating this token with the same handling discipline applied to any other genuine credential, rather than as merely a convenient setup detail, reflects its actual security significance correctly.

A pre-initialization checklist

Before running the actual initialization command, confirming a short list of prerequisites directly avoids the most common causes of a confusing, partially successful cluster bootstrap:

docker --version
ip addr show
nc -zv <other-node-ip> 2377
nc -zv <other-node-ip> 7946
date

Confirming Docker is running a sufficiently current, consistent version across every intended node, that the chosen advertise address is genuinely reachable, that required ports are open, and that system clocks are reasonably synchronized (since clock drift can affect TLS certificate validation between nodes) catches the most common initialization problems before they actually occur.

Joining additional nodes

Once the cluster is initialized, joining additional nodes is a matter of running the join command with the appropriate token against the manager's advertised address:

docker swarm join --token SWMTKN-1-xxxxx 10.0.1.5:2377

docker node ls

Confirming the new node actually appears in the manager's node list with a Ready status immediately after joining verifies the join genuinely succeeded, rather than assuming success purely based on the join command completing without an immediately visible error.

Common mistakes

• Allowing Docker to auto-select an advertise address without explicitly confirming it is genuinely reachable by every other intended cluster node.
• Not verifying the required ports, 2377, 7946, and 4789, are actually open between nodes before attempting initialization, leading to a confusing join failure with no obvious port-related explanation.
• Distributing a join token through an insecure channel, treating it as a convenient setup detail rather than the genuine cluster-access credential it actually represents.
• Skipping a pre-initialization checklist and discovering version mismatches, connectivity gaps, or clock drift only after an initialization or join attempt has already failed confusingly.
• Assuming a join succeeded based solely on the command completing without an obvious error, rather than confirming the new node's actual status directly through docker node ls.

Swarm cluster init goes smoothly when the advertise address is chosen deliberately based on genuine network reachability, the required ports are confirmed open beforehand rather than discovered closed after a confusing failure, and join tokens are distributed and secured with the same discipline applied to any other genuine cluster-access credential.