Advisory: See Swarm mode overview for the orchestration features introduced in Docker Engine 1.12. Only refer to the Docker Swarm documents below for information on the standalone Swarm product.
Prerequisite: Before using
join, establish a discovery backend as described in this discovery topic.
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
join command has only one argument:
<discovery>— Discovery backend
When you create the Swarm node, use the
<discovery> argument to specify one of the following discovery backends:
<token> is a discovery token generated by Docker Hub’s hosted discovery service. To generate this discovery token, use the
> Warning: Docker Hub’s hosted discovery backend is not recommended for production use. It’s intended only for testing/development.
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 the cluster.
iprange is an IP address or a range of IP addresses followed by a port number.
* A discovery token:
* A Consul node:
The environment variable for
For more information and examples, see the Docker Swarm Discovery topic.
join command has the following options:
--addr— Advertise the Docker Engine’s IP and port number
--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
--heartbeat— Period between each heartbeat
--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
--ttl "<interval>s" to specify the time-to-live (TTL) interval, in seconds, of an ephemeral node. The default interval is
--delay— Add a random delay in [0s,delay] to avoid synchronized registration
--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
--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