From 1e7219d40fcd3b9e3ef6d224e2926d5562fb7b74 Mon Sep 17 00:00:00 2001 From: Charles Smith Date: Wed, 27 Jul 2016 21:24:38 -0700 Subject: [PATCH] add advertise address, clarify join token Signed-off-by: Charles Smith --- .../reference/commandline/swarm_join_token.md | 33 ++++++++--- docs/swarm/join-nodes.md | 29 ++-------- docs/swarm/swarm-mode.md | 58 +++++++++++++++++-- 3 files changed, 85 insertions(+), 35 deletions(-) diff --git a/docs/reference/commandline/swarm_join_token.md b/docs/reference/commandline/swarm_join_token.md index 07943266a1..996ca01fee 100644 --- a/docs/reference/commandline/swarm_join_token.md +++ b/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` diff --git a/docs/swarm/join-nodes.md b/docs/swarm/join-nodes.md index 9f64a0d499..bb0ca3feda 100644 --- a/docs/swarm/join-nodes.md +++ b/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. ``` - - ## Learn More * `swarm join`[command line reference](../reference/commandline/swarm_join.md) diff --git a/docs/swarm/swarm-mode.md b/docs/swarm/swarm-mode.md index 61d6143282..387ce904ab 100644 --- a/docs/swarm/swarm-mode.md +++ b/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 +``` + +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: