github.com/portworx/docker@v1.12.1/docs/swarm/swarm-mode.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Run Docker Engine in swarm mode" 4 description = "Run Docker Engine in swarm mode" 5 keywords = ["guide, swarm mode, node"] 6 [menu.main] 7 identifier="initialize-swarm-guide" 8 parent="engine_swarm" 9 weight=12 10 +++ 11 <![end-metadata]--> 12 13 # Run Docker Engine in swarm mode 14 15 When you first install and start working with Docker Engine, swarm mode is 16 disabled by default. When you enable swarm mode, you work with the concept of 17 services managed through the `docker service` command. 18 19 There are two ways to run the Engine in swarm mode: 20 21 * Create a new swarm, covered in this article. 22 * [Join an existing swarm](join-nodes.md). 23 24 When you run the Engine in swarm mode on your local machine, you can create and 25 test services based upon images you've created or other available images. In 26 your production environment, swarm mode provides a fault-tolerant platform with 27 cluster management features to keep your services running and available. 28 29 These instructions assume you have installed the Docker Engine 1.12 or later on 30 a machine to serve as a manager node in your swarm. 31 32 If you haven't already, read through the [swarm mode key concepts](key-concepts.md) 33 and try the [swarm mode tutorial](swarm-tutorial/index.md). 34 35 ## Create a swarm 36 37 When you run the command to create a swarm, the Docker Engine starts running in swarm mode. 38 39 Run [`docker swarm init`](../reference/commandline/swarm_init.md) 40 to create a single-node swarm on the current node. The Engine sets up the swarm 41 as follows: 42 43 * switches the current node into swarm mode. 44 * creates a swarm named `default`. 45 * designates the current node as a leader manager node for the swarm. 46 * names the node with the machine hostname. 47 * configures the manager to listen on an active network interface on port 2377. 48 * sets the current node to `Active` availability, meanining it can receive tasks 49 from the scheduler. 50 * starts an internal distributed data store for Engines participating in the 51 swarm to maintain a consistent view of the swarm and all services running on it. 52 * by default, generates a self-signed root CA for the swarm. 53 * by default, generates tokens for worker and manager nodes to join the 54 swarm. 55 * creates an overlay network named `ingress` for publishing service ports 56 external to the swarm. 57 58 The output for `docker swarm init` provides the connection command to use when 59 you join new worker nodes to the swarm: 60 61 ```bash 62 $ docker swarm init 63 Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager. 64 65 To add a worker to this swarm, run the following command: 66 67 docker swarm join \ 68 --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ 69 192.168.99.100:2377 70 71 To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. 72 ``` 73 74 ### Configure the advertise address 75 76 Manager nodes use an advertise address to allow other nodes in the swarm access 77 to the Swarmkit API and overlay networking. The other nodes on the swarm must be 78 able to access the manager node on its advertise address IP address. 79 80 If you don't specify an advertise address, Docker checks if the system has a 81 single IP address. If so, Docker uses the IP address with with the listening 82 port `2377` by default. If the system has multiple IP addresses, you must 83 specify the correct `--advertise-addr` to enable inter-manager communication 84 and overlay networking: 85 86 ```bash 87 $ docker swarm init --advertise-addr <MANAGER-IP> 88 ``` 89 90 You must also specify the `--advertise-addr` if the address where other nodes 91 reach the first manager node is not the same address the manager sees as its 92 own. For instance, in a cloud setup that spans different regions, hosts have 93 both internal addresses for access within the region and external addresses that 94 you use for access from outside that region. In this case, specify the external 95 address with `--advertise-addr` so that the node can propogate that information 96 to other nodes that subsequently connect to it. 97 98 Refer to the `docker swarm init` [CLI reference](../reference/commandline/swarm_init.md) 99 for more detail on the advertise address. 100 101 ### View the join command or update a swarm join token 102 103 Nodes require a secret token to join the swarm. The token for worker nodes is 104 different from the token for manager nodes. Nodes only use the join-token at the 105 moment they join the swarm. Rotating the join token after a node has already 106 joined a swarm does not affect the node's swarm membership. Token rotation 107 ensures an old token cannot be used by any new nodes attempting to join the 108 swarm. 109 110 To retrieve the join command including the join token for worker nodes, run: 111 112 ```bash 113 $ docker swarm join-token worker 114 115 To add a worker to this swarm, run the following command: 116 117 docker swarm join \ 118 --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ 119 192.168.99.100:2377 120 121 This node joined a swarm as a worker. 122 ``` 123 124 To view the join command and token for manager nodes, run: 125 126 ```bash 127 $ docker swarm join-token manager 128 129 To add a worker to this swarm, run the following command: 130 131 docker swarm join \ 132 --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ 133 192.168.99.100:2377 134 ``` 135 136 Pass the `--quiet` flag to print only the token: 137 138 ```bash 139 $ docker swarm join-token --quiet worker 140 141 SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c 142 ``` 143 144 Be careful with the join tokens because they are the secrets necessary to join 145 the swarm. In particular, checking a secret into version control is a bad 146 practice because it would allow anyone with access to the the application source 147 code to add new nodes to the swarm. Manager tokens are especially sensitive 148 because they allow a new manager node to join and gain control over the whole 149 swarm. 150 151 We recommend that you rotate the join tokens in the following circumstances: 152 153 * If a token was checked-in by accident into a version control system, group 154 chat or accidentally printed to your logs. 155 * If you suspect a node has been compromised. 156 * If you wish to guarantee that no new nodes can join the swarm. 157 158 Additionally, it is a best practice to implement a regular rotation schedule for 159 any secret including swarm join tokens. We recommend that you rotate your tokens 160 at least every 6 months. 161 162 Run `swarm join-token --rotate` to invalidate the old token and generate a new 163 token. Specify whether you want to rotate the token for `worker` or `manager` 164 nodes: 165 166 ```bash 167 $docker swarm join-token --rotate worker 168 169 To add a worker to this swarm, run the following command: 170 171 docker swarm join \ 172 --token SWMTKN-1-2kscvs0zuymrsc9t0ocyy1rdns9dhaodvpl639j2bqx55uptag-ebmn5u927reawo27s3azntd44 \ 173 172.17.0.2:2377 174 ``` 175 176 ## Learn More 177 178 * [Join nodes to a swarm](join-nodes.md) 179 * `swarm init`[command line reference](../reference/commandline/swarm_init.md) 180 * [Swarm mode tutorial](swarm-tutorial/index.md)