Join a Docker Swarm Node Without Guessing the Network

By the end of this guide, a Docker Engine will be attached to an existing Swarm as either a worker or a manager, and you will have checked that the manager sees it as ready. Allow about 10 minutes for a worker on a prepared host, longer if you need to fix firewall or routing rules.

Before you start

You need a Linux host with Docker Engine installed and running, network access to an existing Swarm manager, and a join token for the role you want. The manager address is normally written as HOST:PORT, with port 2377 commonly used for Swarm management traffic. Use the address that the new host can actually reach, not a hostname that only resolves on the manager.

Run the commands as a user allowed to access the Docker daemon. On installations where that is not true, prefix the Docker commands with sudo. The examples below use visibly fake token and address values. Never paste a real token into a ticket, shell transcript, or source repository.

1. Get the role-specific join command

On an existing manager, request the command for the role you need. A worker increases task capacity without joining the manager quorum. A manager participates in cluster management and Raft consensus, so use that role only for a host intended to be a stable manager.

docker swarm join-token worker
docker swarm join-token manager

Run only the command for your chosen role. Its output includes a docker swarm join command containing a secret token and the manager's advertised address. Copy that command to the new host through a protected channel. A manager token is particularly sensitive because it permits a new manager to enter the control plane.

If a token has appeared in logs, chat, version control, or an unknown person's terminal, rotate it on a manager before using it again:

docker swarm join-token --rotate worker

Use manager instead of worker when rotating the manager token. Rotation prevents new joins with the old token, but does not remove nodes that have already joined.

2. Check the joining host

On the host that will join, confirm the installed CLI and whether it is already in a Swarm.

docker --version
docker info --format '{{.Swarm.LocalNodeState}}'

This guide was checked with Docker CLI 29.8.1. The second command should normally report inactive before a new join. If it reports active, stop and check the host's existing membership rather than trying to join it again. If the host belongs to the wrong Swarm, leaving it changes local state and can affect running Swarm workloads:

docker swarm leave

3. Join as a worker or manager

On the joining host, run the command copied from the manager. Replace the example values only with the token and endpoint issued for this Swarm.

docker swarm join   --token SWMTKN-1-EXAMPLE-REPLACE-THIS-TOKEN   192.0.2.10:2377

A successful worker join ends with output similar to:

This node joined a swarm as a worker.

With a manager token, the final line identifies the node as a manager instead. The token determines the role. There is no separate --role option in docker swarm join.

The join switches the local Engine into Swarm mode, obtains its Swarm TLS identity, and uses the host name as the node name. It also creates or extends Swarm networking on the host. The command is not a harmless connectivity test: do not run it on a production host until you have selected the correct cluster and role.

4. Set addresses only when the defaults are wrong

For a host with one suitable network address, the basic command is usually enough. The default listen address is 0.0.0.0:2377. On a host with multiple interfaces, specify the address that other Swarm members must use to reach this node:

docker swarm join   --token SWMTKN-1-EXAMPLE-REPLACE-THIS-TOKEN   --advertise-addr 10.20.0.15   10.20.0.10:2377

--advertise-addr can be an IP address or interface name, with an optional port. It controls the address advertised for Swarm API and inter-node communication. A load balancer address is not normally the right value for this option when the node must advertise its own address.

To separate control traffic from container data traffic, provide a second interface with --data-path-addr:

docker swarm join   --token SWMTKN-1-EXAMPLE-REPLACE-THIS-TOKEN   --advertise-addr eth0   --data-path-addr eth1   10.20.0.10:2377

Use --listen-addr when the node needs a particular local listen interface or port. It is often unnecessary when joining an existing Swarm. The --availability option accepts active, pause, or drain; use drain when a manager should not receive service tasks while it is being prepared.

5. Verify from a manager

Return to a manager and list the nodes:

docker node ls

Find the new host by its hostname. A healthy result has STATUS set to Ready and the intended AVAILABILITY. A worker has an empty manager-status column. A manager normally shows a manager status such as Reachable or Leader.

If the node appears but is not ready, inspect the daemon on the joining host and check that firewalls permit the Swarm ports required by your topology. Port 2377 is for manager control traffic; overlay networking also requires the ports documented for your Swarm network design. Do not open every port as a quick fix. Confirm the interface, route, firewall policy, and advertised address one at a time.

Common failure paths

• Invalid token: obtain a fresh role-specific command with docker swarm join-token worker or manager. Do not swap the role name after copying a token.
• Connection timeout: test name resolution and reachability to the manager endpoint, then inspect firewall rules and routing. An endpoint that is reachable from the manager itself may not be reachable from the new host.
• Wrong interface selected: retry with an explicit --advertise-addr, and use --data-path-addr only if data traffic belongs on another network.
• Already part of a Swarm: stop and identify the existing membership. Leave the old Swarm deliberately, then retry with a command for the intended cluster.
• Unexpected manager count: avoid adding managers casually. Losing a majority can stop Swarm management even when some nodes remain online, so use workers for capacity-only hosts.

Done means

• The join command used a token for the intended role and cluster.
• The joining host reported a successful worker or manager join.
• docker node ls on a manager shows the new node as Ready.
• The advertised and data-path addresses match the routes and interfaces that should carry Swarm traffic.
• Any exposed or copied token was protected, and a leaked token was rotated.