kotovalexarian-likes-github
/
moby--moby
mirror of https://github.com/moby/moby.git
1
0
Fork 0
Code Releases Activity

Merge pull request #25182 from sfsmithcha/clarify_join_token 

Author Merge add advertise address, clarify join token

CI errors expected.
This commit is contained in:
Charles Smith 2016-07-29 16:10:20 -07:00 committed by GitHub
parent 8b69d50c79 1e7219d40f
commit ee355e017d
3 changed files with 85 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/reference/commandline/swarm_join_token.md
View File

@ -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`

29
docs/swarm/join-nodes.md
View File

@ -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)

58
docs/swarm/swarm-mode.md
View File

@ -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: