join — Create a Swarm node

Prerequisite: Before using join, establish a discovery backend as described in this discovery topic.

The join command creates a Swarm node whose purpose is to run containers on behalf of the cluster. A typical cluster has multiple Swarm nodes.

To create a Swarm node, use the following syntax:

$ docker run swarm join [OPTIONS] <discovery>

For example, to create a Swarm node in a high-availability cluster with other managers, enter:

$ docker run -d swarm join --advertise=172.30.0.69:2375 consul://172.30.0.161:8500

Or, for example, to create a Swarm node that uses Transport Layer Security (TLS) to authenticate the Docker Swarm nodes, enter:

$ sudo docker run -d swarm join --addr=node1:2376 token://86222732d62b6868d441d430aee4f055

Arguments

The join command has only one argument:

<discovery> — Discovery backend

Before you create a Swarm node, create a discovery token or set up a discovery backend for your cluster.

When you create the Swarm node, use the <discovery> argument to specify one of the following discovery backends:

• token://<token>
• consul://<ip1>/<path>
• etcd://<ip1>,<ip2>,<ip3>/<path>
• file://<path/to/file>
• zk://<ip1>,<ip2>/<path>
• [nodes://]<iprange>,<iprange>

Where:

• <token> is a discovery token generated by Docker Hub’s hosted discovery service. To generate this discovery token, use the create command.

  Warning: Docker Hub’s hosted discovery backend is not recommended for production use. It’s intended only for testing/development.

• ip1, ip2, ip3 are each the IP address and port numbers of a discovery backend node.
• path (optional) is a path to a key-value store on the discovery backend. When you use a single backend to service multiple clusters, you use paths to maintain separate key-value stores for each cluster.
• path/to/file is the path to a file that contains a static list of the Swarm managers and nodes that are members of the cluster.
• iprange is an IP address or a range of IP addresses followed by a port number.

For example:

• A discovery token: token://0ac50ef75c9739f5bfeeaf00503d4e6e
• A Consul node: consul://172.30.0.165:8500

The environment variable for <discovery> is $SWARM_DISCOVERY.

For more information and examples, see the Docker Swarm Discovery topic.

Options

The join command has the following options:

--advertise or --addr — Advertise the Docker Engine’s IP and port number

Use --advertise <ip>:<port> or --addr <ip>:<port> to advertise the IP address and port number of the Docker Engine. For example, --advertise 172.30.0.161:4000. Swarm managers MUST be able to reach this Swarm node at this address.

The environment variable for --advertise is $SWARM_ADVERTISE.

--heartbeat — Period between each heartbeat

Use --heartbeat "<interval>s" to specify the interval, in seconds, between heartbeats the node sends to the primary manager. These heartbeats indicate that the node is healthy and reachable. By default, the interval is 60 seconds.

--ttl — Sets the expiration of an ephemeral node

Use --ttl "<interval>s" to specify the time-to-live (TTL) interval, in seconds, of an ephemeral node. The default interval is 180s.

--delay — Add a random delay in [0s,delay] to avoid synchronized registration

Use --delay "<interval>s" to specify the maximum interval for a random delay, in seconds, before the node registers with the discovery backend. If you deploy a large number of nodes simultaneously, the random delay spreads registrations out over the interval and avoids saturating the discovery backend.

--discovery-opt — Discovery options

Use --discovery-opt <value> to discovery options, such as paths to the TLS files; the CA’s public key certificate, the certificate, and the private key of the distributed K/V store on a Consul or etcd discovery backend. You can enter multiple discovery options. For example:

--discovery-opt kv.cacertfile=/path/to/mycacert.pem \
--discovery-opt kv.certfile=/path/to/mycert.pem \
--discovery-opt kv.keyfile=/path/to/mykey.pem \

For more information, see Use TLS with distributed key/value discovery.