Merge pull request #25182 from sfsmithcha/clarify_join_token

Author Merge add advertise address, clarify join token

CI errors expected.

docs/reference/commandline/swarm_join_token.md

@@ -21,13 +21,17 @@ Options:
       --rotate   Rotate join token
 ```
 
-Join tokens are secrets that determine whether or not a node will join the swarm as a manager node
-or a worker node. You pass the token using the `--token flag` when you run
-[swarm join](swarm_join.md). You can access the current tokens or rotate the tokens using
-`swarm join-token`.
+Join tokens are secrets that allow a node to join the swarm. There are two
+different join tokens available, one for the worker role and one for the manager
+role. You pass the token using the `--token` flag when you run
+[swarm join](swarm_join.md). Nodes use the join token only when they join the
+swarm.
 
-Run with only a single `worker` or `manager` argument, it will print a command for joining a new
-node to the swarm, including the necessary token:
+You can view or rotate the join tokens using `swarm join-token`.
+
+As a convenience, you can pass `worker` or `manager` as an argument to
+`join-token` to print the full `docker swarm join` command to join a new node to
+the swarm:
 
 ```bash
 $ docker swarm join-token worker
@@ -64,7 +68,22 @@ SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7
 
 ### `--rotate`
 
-Update the join token for a specified role with a new token and print the token.
+Because tokens allow new nodes to join the swarm, you should keep them secret.
+Be particularly careful with manager tokens since they allow new manager nodes
+to join the swarm. A rogue manager has the potential to disrupt the operation of
+your swarm.
+
+Rotate your swarm's join token if a token gets checked-in to version control,
+stolen, or a node is compromised. You may also want to periodically rotate the
+token to ensure any unknown token leaks do not allow a rogue node to join
+the swarm.
+
+To rotate the join token and print the newly generated token, run
+`docker swarm join-token --rotate` and pass the role: `manager` or `worker`.
+
+Rotating a join-token means that no new nodes will be able to join the swarm
+using the old token. Rotation does not affect existing nodes in the swarm
+because the join token is only used for authorizing new nodes joining the swarm.
 
 ### `--quiet`
 

docs/swarm/join-nodes.md

@@ -29,6 +29,11 @@ also run tasks.
 Before you add nodes to a swarm you must install Docker Engine 1.12 or later on
 the host machine.
 
+The Docker Engine joins the swarm depending on the **join-token** you provide to
+the `docker swarm join` command. The node only uses the token at join time. If
+you subsequently rotate the token, it doesn't affect existing swarm nodes. Refer
+to [Run Docker Engine in swarm mode](swarm-mode.md#view-the-join-command-or-update-a-swarm-join-token).
+
 ## Join as a worker node
 
 To retrieve the join command including the join token for worker nodes, run the
@@ -100,30 +105,6 @@ $ docker swarm join \
 This node joined a swarm as a manager.
 ```
 
-<!--TODO WIP
-Manager nodes use the listen address for cluster management communications. The
-other nodes on the swarm must be able to access the manager node on the
-IP address and port you specify for the listen address.
-
-Especially when there are multiple active network interfaces, you should
-you explicitly define the listen address when you add a manager node to the a
-swarm:
-
-  ```bash
-  docker swarm join \
-  --token <MANAGER-TOKEN> \
-  --listen-addr <NODE-IP>:<PORT> \
-  <MANAGER-IP>:<PORT>
-  ```
-this will change for https://github.com/docker/docker/pull/24237 ->>
-Replace <NODE-IP> with the IP address of the node that is joining the swarm.
-Replace <MANAGER-IP> with the address of the swarm manager.
-
-Only manager nodes use the listen address. If you specify `--listen-addr` for a
-worker node, the node only uses the listen address if it is promoted to a
-manager.
--->
-
 ## Learn More
 
 * `swarm join`[command line reference](../reference/commandline/swarm_join.md)

docs/swarm/swarm-mode.md

@@ -73,10 +73,41 @@ To add a manager to this swarm, run the following command:
     192.168.99.100:2377
 ```
 
+### Configure the advertise address
+
+Manager nodes use an advertise address to allow other nodes in the swarm access
+to the Swarmkit API and overlay networking. The other nodes on the swarm must be
+able to access the manager node on its advertise address IP address.
+
+If you don't specify an advertise address, Docker checks if the system has a
+single IP address. If so, Docker uses the IP address with with the listening
+port `2377` by default. If the system has multiple IP addresses, you must
+specify the correct  `--advertise-addr` to enable inter-manager communication
+and overlay networking:
+
+```bash
+$ docker swarm init --advertise-addr <MANAGER-IP>
+```
+
+You must also specify the `--advertise-addr` if the address where other nodes
+reach the first manager node is not the same address the manager sees as its
+own. For instance, in a cloud setup that spans different regions, hosts have
+both internal addresses for access within the region and external addresses that
+you use for access from outside that region. In this case, specify the external
+address with `--advertise-addr` so that the node can propogate that information
+to other nodes that subsequently connect to it.
+
+Refer to the `docker swarm init` [CLI reference](../reference/commandline/swarm_init.md)
+for more detail on the advertise address.
+
 ### View the join command or update a swarm join token
 
-The manager node requires a secret token for a new node to join the swarm. The
-token for worker nodes is different from the token for manager nodes.
+Nodes require a secret token to join the swarm. The token for worker nodes is
+different from the token for manager nodes. Nodes only use the join-token at the
+moment they join the swarm. Rotating the join token after a node has already
+joined a swarm does not affect the node's swarm membership. Token rotation
+ensures an old token cannot be used by any new nodes attempting to join the
+swarm.
 
 To retrieve the join command including the join token for worker nodes, run:
 
@@ -110,10 +141,29 @@ $ docker swarm join-token --quiet worker
 SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c
 ```
 
-Pass the `--rotate` for `swarm join-token` to the token for a worker or manager
+Be careful with the join tokens because they are the secrets necessary to join
+the swarm. In particular, checking a secret into version control is a bad
+practice because it would allow anyone with access to the the application source
+code to add new nodes to the swarm. Manager tokens are especially sensitive
+because they allow a new manager node to join and gain control over the whole
+swarm.
+
+We recommend that you rotate the join tokens in the following circumstances:
+
+* If a token was checked-in by accident into a version control system, group
+chat or accidentally printed to your logs.
+* If you suspect a node has been compromised.
+* If you wish to guarantee that no new nodes can join the swarm.
+
+Additionally, it is a best practice to implement a regular rotation schedule for
+any secret including swarm join tokens. We recommend that you rotate your tokens
+at least every 6 months.
+
+Run `swarm join-token --rotate` to invalidate the old token and generate a new
+token. Specify whether you want to rotate the token for `worker` or `manager`
 nodes:
 
-```
+```bash
 $docker swarm join-token  --rotate worker
 
 To add a worker to this swarm, run the following command: