1. docker
  2. Commit 3696d1fff5d728f16f7be02ef6823deaabed7b1e
Browse code

Merge pull request #25182 from sfsmithcha/clarify_join_token

Author Merge add advertise address, clarify join token

CI errors expected.
(cherry picked from commit ee355e017d210bef02771a8de4733f820ae6b717)

Charles Smith authored on 2016/07/30 08:10:20
Showing 3 changed files
docs/reference/commandline/swarm_join_token.md
History View file @ 3696d1f
... ... 
@@ -21,13 +21,17 @@ Options:
21 21 
       --rotate   Rotate join token
22 22 
 ```
23 23
24 
-Join tokens are secrets that determine whether or not a node will join the swarm as a manager node
25 
-or a worker node. You pass the token using the `--token flag` when you run
26 
-[swarm join](swarm_join.md). You can access the current tokens or rotate the tokens using
27 
-`swarm join-token`.
24 
+Join tokens are secrets that allow a node to join the swarm. There are two
25 
+different join tokens available, one for the worker role and one for the manager
26 
+role. You pass the token using the `--token` flag when you run
27 
+[swarm join](swarm_join.md). Nodes use the join token only when they join the
28 
+swarm.
28 29
29 
-Run with only a single `worker` or `manager` argument, it will print a command for joining a new
30 
-node to the swarm, including the necessary token:
30 
+You can view or rotate the join tokens using `swarm join-token`.
31 
+
32 
+As a convenience, you can pass `worker` or `manager` as an argument to
33 
+`join-token` to print the full `docker swarm join` command to join a new node to
34 
+the swarm:
31 35
32 36 
 ```bash
33 37 
 $ docker swarm join-token worker
... ... 
@@ -64,7 +68,22 @@ SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7
64 64
65 65 
 ### `--rotate`
66 66
67 
-Update the join token for a specified role with a new token and print the token.
67 
+Because tokens allow new nodes to join the swarm, you should keep them secret.
68 
+Be particularly careful with manager tokens since they allow new manager nodes
69 
+to join the swarm. A rogue manager has the potential to disrupt the operation of
70 
+your swarm.
71 
+
72 
+Rotate your swarm's join token if a token gets checked-in to version control,
73 
+stolen, or a node is compromised. You may also want to periodically rotate the
74 
+token to ensure any unknown token leaks do not allow a rogue node to join
75 
+the swarm.
76 
+
77 
+To rotate the join token and print the newly generated token, run
78 
+`docker swarm join-token --rotate` and pass the role: `manager` or `worker`.
79 
+
80 
+Rotating a join-token means that no new nodes will be able to join the swarm
81 
+using the old token. Rotation does not affect existing nodes in the swarm
82 
+because the join token is only used for authorizing new nodes joining the swarm.
68 83
69 84 
 ### `--quiet`
70 85
docs/swarm/join-nodes.md
History View file @ 3696d1f
... ... 
@@ -29,6 +29,11 @@ also run tasks.
29 29 
 Before you add nodes to a swarm you must install Docker Engine 1.12 or later on
30 30 
 the host machine.
31 31
32 
+The Docker Engine joins the swarm depending on the **join-token** you provide to
33 
+the `docker swarm join` command. The node only uses the token at join time. If
34 
+you subsequently rotate the token, it doesn't affect existing swarm nodes. Refer
35 
+to [Run Docker Engine in swarm mode](swarm-mode.md#view-the-join-command-or-update-a-swarm-join-token).
36 
+
32 37 
 ## Join as a worker node
33 38
34 39 
 To retrieve the join command including the join token for worker nodes, run the
... ... 
@@ -100,30 +105,6 @@ $ docker swarm join \
100 100 
 This node joined a swarm as a manager.
101 101 
 ```
102 102
103 
-<!--TODO WIP
104 
-Manager nodes use the listen address for cluster management communications. The
105 
-other nodes on the swarm must be able to access the manager node on the
106 
-IP address and port you specify for the listen address.
107 
-
108 
-Especially when there are multiple active network interfaces, you should
109 
-you explicitly define the listen address when you add a manager node to the a
110 
-swarm:
111 
-
112 
-  ```bash
113 
-  docker swarm join \
114 
-  --token <MANAGER-TOKEN> \
115 
-  --listen-addr <NODE-IP>:<PORT> \
116 
-  <MANAGER-IP>:<PORT>
117 
-  ```
118 
-this will change for https://github.com/docker/docker/pull/24237 ->>
119 
-Replace <NODE-IP> with the IP address of the node that is joining the swarm.
120 
-Replace <MANAGER-IP> with the address of the swarm manager.
121 
-
122 
-Only manager nodes use the listen address. If you specify `--listen-addr` for a
123 
-worker node, the node only uses the listen address if it is promoted to a
124 
-manager.
125 
-
126 103 
 ## Learn More
127 104
128 105 
 * `swarm join`[command line reference](../reference/commandline/swarm_join.md)
docs/swarm/swarm-mode.md
History View file @ 3696d1f
... ... 
@@ -73,10 +73,41 @@ To add a manager to this swarm, run the following command:
73 73 
     192.168.99.100:2377
74 74 
 ```
75 75
76 
+### Configure the advertise address
77 
+
78 
+Manager nodes use an advertise address to allow other nodes in the swarm access
79 
+to the Swarmkit API and overlay networking. The other nodes on the swarm must be
80 
+able to access the manager node on its advertise address IP address.
81 
+
82 
+If you don't specify an advertise address, Docker checks if the system has a
83 
+single IP address. If so, Docker uses the IP address with with the listening
84 
+port `2377` by default. If the system has multiple IP addresses, you must
85 
+specify the correct  `--advertise-addr` to enable inter-manager communication
86 
+and overlay networking:
87 
+
88 
+```bash
89 
+$ docker swarm init --advertise-addr <MANAGER-IP>
90 
+```
91 
+
92 
+You must also specify the `--advertise-addr` if the address where other nodes
93 
+reach the first manager node is not the same address the manager sees as its
94 
+own. For instance, in a cloud setup that spans different regions, hosts have
95 
+both internal addresses for access within the region and external addresses that
96 
+you use for access from outside that region. In this case, specify the external
97 
+address with `--advertise-addr` so that the node can propogate that information
98 
+to other nodes that subsequently connect to it.
99 
+
100 
+Refer to the `docker swarm init` [CLI reference](../reference/commandline/swarm_init.md)
101 
+for more detail on the advertise address.
102 
+
76 103 
 ### View the join command or update a swarm join token
77 104
78 
-The manager node requires a secret token for a new node to join the swarm. The
79 
-token for worker nodes is different from the token for manager nodes.
105 
+Nodes require a secret token to join the swarm. The token for worker nodes is
106 
+different from the token for manager nodes. Nodes only use the join-token at the
107 
+moment they join the swarm. Rotating the join token after a node has already
108 
+joined a swarm does not affect the node's swarm membership. Token rotation
109 
+ensures an old token cannot be used by any new nodes attempting to join the
110 
+swarm.
80 111
81 112 
 To retrieve the join command including the join token for worker nodes, run:
82 113
... ... 
@@ -110,10 +141,29 @@ $ docker swarm join-token --quiet worker
110 110 
 SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c
111 111 
 ```
112 112
113 
-Pass the `--rotate` for `swarm join-token` to the token for a worker or manager
113 
+Be careful with the join tokens because they are the secrets necessary to join
114 
+the swarm. In particular, checking a secret into version control is a bad
115 
+practice because it would allow anyone with access to the the application source
116 
+code to add new nodes to the swarm. Manager tokens are especially sensitive
117 
+because they allow a new manager node to join and gain control over the whole
118 
+swarm.
119 
+
120 
+We recommend that you rotate the join tokens in the following circumstances:
121 
+
122 
+* If a token was checked-in by accident into a version control system, group
123 
+chat or accidentally printed to your logs.
124 
+* If you suspect a node has been compromised.
125 
+* If you wish to guarantee that no new nodes can join the swarm.
126 
+
127 
+Additionally, it is a best practice to implement a regular rotation schedule for
128 
+any secret including swarm join tokens. We recommend that you rotate your tokens
129 
+at least every 6 months.
130 
+
131 
+Run `swarm join-token --rotate` to invalidate the old token and generate a new
132 
+token. Specify whether you want to rotate the token for `worker` or `manager`
114 133 
 nodes:
115 134
116 
-```
135 
+```bash
117 136 
 $docker swarm join-token  --rotate worker
118 137
119 138 
 To add a worker to this swarm, run the following command: