docker
/
cli
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Replace secrets with join tokens 

Implement the proposal from
https://github.com/docker/docker/issues/24430#issuecomment-233100121

Removes acceptance policy and secret in favor of an automatically
generated join token that combines the secret, CA hash, and
manager/worker role into a single opaque string.

Adds a docker swarm join-token subcommand to inspect and rotate the
tokens.

Signed-off-by: Aaron Lehmann <aaron.lehmann@docker.com>
This commit is contained in:
Aaron Lehmann 2016-07-20 11:15:08 -07:00 committed by Tibor Vass
parent d1228a75e1
commit acf0bc4b9a
18 changed files with 158 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
contrib/completion/zsh/_docker
View File

@ -1087,7 +1087,7 @@ __docker_service_subcommand() {
"($help)--name=[Service name]:name: "
"($help)*--network=[Network attachments]:network: "
"($help)*"{-p=,--publish=}"[Publish a port as a node port]:port: "
"($help)--registry-auth[Send registry authentication details to Swarm agents]"
"($help)--registry-auth[Send registry authentication details to swarm agents]"
"($help)--replicas=[Number of tasks]:replicas: "
"($help)--reserve-cpu=[Reserve CPUs]:value: "
"($help)--reserve-memory=[Reserve Memory]:value: "
@ -1185,11 +1185,11 @@ __docker_service_subcommand() {
__docker_swarm_commands() {
local -a _docker_swarm_subcommands
_docker_swarm_subcommands=(
"init:Initialize a Swarm"
"inspect:Inspect the Swarm"
"join:Join a Swarm as a node and/or manager"
"leave:Leave a Swarm"
"update:Update the Swarm"
"init:Initialize a swarm"
"inspect:Inspect the swarm"
"join:Join a swarm as a node and/or manager"
"leave:Leave a swarm"
"update:Update the swarm"
)
_describe -t docker-swarm-commands "docker swarm command" _docker_swarm_subcommands
}

2
docs/reference/commandline/deploy.md
View File

@ -19,7 +19,7 @@ Create and update a stack from a Distributed Application Bundle (DAB)
Options:
--file string Path to a Distributed Application Bundle file (Default: STACK.dab)
--help Print usage
--registry-auth Send registry authentication details to Swarm agents
--registry-auth Send registry authentication details to swarm agents
```
Create and update a stack from a `dab` file. This command has to be

6
docs/reference/commandline/index.md
View File

@ -111,7 +111,6 @@ read the [`dockerd`](dockerd.md) reference page.
| Command | Description |
|:--------|:-------------------------------------------------------------------|
| [node accept](node_accept.md) | Accept a node into the swarm |
| [node promote](node_promote.md) | Promote a node that is pending a promotion to manager |
| [node demote](node_demote.md) | Demotes an existing manager so that it is no longer a manager |
| [node inspect](node_inspect.md) | Inspect a node in the swarm |
@ -124,10 +123,11 @@ read the [`dockerd`](dockerd.md) reference page.
| Command | Description |
|:--------|:-------------------------------------------------------------------|
| [swarm init](swarm_init.md) | Initialize a Swarm |
| [swarm join](swarm_join.md) | Join a Swarm as a manager node or worker node |
| [swarm init](swarm_init.md) | Initialize a swarm |
| [swarm join](swarm_join.md) | Join a swarm as a manager node or worker node |
| [swarm leave](swarm_leave.md) | Remove the current node from the swarm |
| [swarm update](swarm_update.md) | Update attributes of a swarm |
| [swarm join-token](swarm_join_token.md) | Display or rotate join tokens |
### Swarm service commands

2
docs/reference/commandline/info.md
View File

@ -38,7 +38,7 @@ available on the volume where `/var/lib/docker` is mounted.
## Display Docker system information
Here is a sample output for a daemon running on Ubuntu, using the overlay
storage driver and a node that is part of a 2 node Swarm cluster:
storage driver and a node that is part of a 2 node swarm cluster:
$ docker -D info
Containers: 14

32
docs/reference/commandline/node_accept.md
View File

@ -1,32 +0,0 @@
<!--[metadata]>
+++
title = "node accept"
description = "The node accept command description and usage"
keywords = ["node, accept"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# node accept
```markdown
Usage: docker node accept NODE [NODE...]
Accept a node in the swarm
Options:
--help Print usage
```
Accept a node into the swarm. This command targets a docker engine that is a manager in the swarm cluster.
```bash
$ docker node accept <node name>
```
## Related information
* [node promote](node_promote.md)
* [node demote](node_demote.md)

1
docs/reference/commandline/node_demote.md
View File

@ -29,5 +29,4 @@ $ docker node demote <node name>
## Related information
* [node accept](node_accept.md)
* [node promote](node_promote.md)

1
docs/reference/commandline/node_inspect.md
View File

@ -41,7 +41,6 @@ Example output:
"UpdatedAt": "2016-06-16T22:52:45.230878043Z",
"Spec": {
"Role": "manager",
"Membership": "accepted",
"Availability": "active"
},
"Description": {

20
docs/reference/commandline/node_ls.md
View File

@ -30,10 +30,10 @@ Lists all the nodes that the Docker Swarm manager knows about. You can filter us
Example output:
$ docker node ls
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Accepted Ready Active
38ciaotwjuritcdtn9npbnkuz swarm-worker1 Accepted Ready Active
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Accepted Ready Active Reachable Yes
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
## Filtering
@ -54,16 +54,16 @@ The `name` filter matches on all or part of a node name.
The following filter matches the node with a name equal to `swarm-master` string.
$ docker node ls -f name=swarm-manager1
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Accepted Ready Active Reachable Yes
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
### id
The `id` filter matches all or part of a node's id.
$ docker node ls -f id=1
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Accepted Ready Active
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
#### label
@ -75,8 +75,8 @@ The following filter matches nodes with the `usage` label regardless of its valu
```bash
$ docker node ls -f "label=foo"
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Accepted Ready Active
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
```

1
docs/reference/commandline/node_promote.md
View File

@ -28,5 +28,4 @@ $ docker node promote <node name>
## Related information
* [node accept](node_accept.md)
* [node demote](node_demote.md)

5
docs/reference/commandline/node_rm.md
View File

@ -23,14 +23,13 @@ Options:
--help Print usage
```
Removes specified nodes from a swarm. Rejects nodes with `Pending`
membership from the swarm.
Removes specified nodes from a swarm.
Example output:
$ docker node rm swarm-node-02
Node swarm-node-02 removed from Swarm
Node swarm-node-02 removed from swarm
## Related information

1
docs/reference/commandline/node_update.md
View File

@ -21,7 +21,6 @@ Options:
--help Print usage
--label-add value Add or update a node label (key=value) (default [])
--label-rm value Remove a node label if exists (default [])
--membership string Membership of the node (accepted/rejected)
--role string Role of the node (worker/manager)
```

2
docs/reference/commandline/service_create.md
View File

@ -31,7 +31,7 @@ Options:
--name string Service name
--network value Network attachments (default [])
-p, --publish value Publish a port as a node port (default [])
--registry-auth Send registry authentication details to Swarm agents
--registry-auth Send registry authentication details to swarm agents
--replicas value Number of tasks (default none)
--reserve-cpu value Reserve CPUs (default 0.000)
--reserve-memory value Reserve Memory (default 0 B)

2
docs/reference/commandline/service_update.md
View File

@ -38,7 +38,7 @@ Options:
--network-rm value Remove a network by name (default [])
--publish-add value Add or update a published port (default [])
--publish-rm value Remove a published port by its target port (default [])
--registry-auth Send registry authentication details to Swarm agents
--registry-auth Send registry authentication details to swarm agents
--replicas value Number of tasks (default none)
--reserve-cpu value Reserve CPUs (default 0.000)
--reserve-memory value Reserve Memory (default 0 B)

73
docs/reference/commandline/swarm_init.md
View File

@ -14,74 +14,43 @@ parent = "smn_cli"
```markdown
Usage: docker swarm init [OPTIONS]
Initialize a Swarm
Initialize a swarm
Options:
--auto-accept value Auto acceptance policy (default worker)
--cert-expiry duration Validity period for node certificates (default 2160h0m0s)
--dispatcher-heartbeat duration Dispatcher heartbeat period (default 5s)
--external-ca value Specifications of one or more certificate signing endpoints
--force-new-cluster Force create a new cluster from current state.
--help Print usage
--listen-addr value Listen address (default 0.0.0.0:2377)
--secret string Set secret value needed to accept nodes into cluster
--task-history-limit int Task history retention limit (default 10)
```
Initialize a Swarm cluster. The docker engine targeted by this command becomes a manager
in the newly created one node Swarm cluster.
Initialize a swarm cluster. The docker engine targeted by this command becomes a manager
in the newly created one node swarm cluster.
```bash
$ docker swarm init --listen-addr 192.168.99.121:2377
No --secret provided. Generated random secret:
4ao565v9jsuogtq5t8s379ulb
Swarm initialized: current node (1ujecd0j9n3ro9i6628smdmth) is now a manager.
Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join --secret 4ao565v9jsuogtq5t8s379ulb \
--ca-hash sha256:07ce22bd1a7619f2adc0d63bd110479a170e7c4e69df05b67a1aa2705c88ef09 \
192.168.99.121:2377
$ docker node ls
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
1ujecd0j9n3ro9i6628smdmth * manager1 Accepted Ready Active Reachable Yes
docker swarm join \
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \
172.17.0.2:2377
To add a manager to this swarm, run the following command:
docker swarm join \
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 \
172.17.0.2:2377
```
If a secret for joining new nodes is not provided with `--secret`, `docker swarm init` will
generate a random one and print it to the terminal (as seen in the example above). To initialize
a swarm with no secret, use `--secret ""`.
`docker swarm init` generates two random tokens, a worker token and a manager token. When you join
a new node to the swarm, the node joins as a worker or manager node based upon the token you pass
to [swarm join](swarm_join.md).
### `--auto-accept value`
This flag controls node acceptance into the cluster. By default, `worker` nodes are
automatically accepted by the cluster. This can be changed by specifying what kinds of nodes
can be auto-accepted into the cluster. If auto-accept is not turned on, then
[node accept](node_accept.md) can be used to explicitly accept a node into the cluster.
For example, the following initializes a cluster with auto-acceptance of workers, but not managers
```bash
$ docker swarm init --listen-addr 192.168.99.121:2377 --auto-accept worker
```
It is possible to pass a comma-separated list of node types. The following initializes a cluster
with auto-acceptance of both `worker` and `manager` nodes
```bash
$ docker swarm init --listen-addr 192.168.99.121:2377 --auto-accept worker,manager
```
To disable auto acceptance, use the `none` option. Note that this option cannot
be combined with other values. When disabling auto acceptance, nodes must be
manually accepted or rejected using `docker node accept` or `docker node rm`.
The following example enables swarm mode with auto acceptance disabled:
```bash
$ docker swarm init --listen-addr 192.168.99.121:2377 --auto-accept none
```
After you create the swarm, you can display or rotate the token using
[swarm join-token](swarm_join_token.md).
### `--cert-expiry`
@ -105,11 +74,7 @@ This flag forces an existing node that was part of a quorum that was lost to res
### `--listen-addr value`
The node listens for inbound Swarm manager traffic on this IP:PORT
### `--secret string`
Secret value needed to accept nodes into the Swarm
The node listens for inbound swarm manager traffic on this IP:PORT
### `--task-history-limit`
@ -120,5 +85,5 @@ This flag sets up task history retention limit.
* [swarm join](swarm_join.md)
* [swarm leave](swarm_leave.md)
* [swarm update](swarm_update.md)
* [node accept](node_accept.md)
* [swarm join-token](swarm_join_token.md)
* [node rm](node_rm.md)

53
docs/reference/commandline/swarm_join.md
View File

@ -14,55 +14,54 @@ parent = "smn_cli"
```markdown
Usage: docker swarm join [OPTIONS] HOST:PORT
Join a Swarm as a node and/or manager
Join a swarm as a node and/or manager
Options:
--ca-hash string Hash of the Root Certificate Authority certificate used for trusted join
--help Print usage
--listen-addr value Listen address (default 0.0.0.0:2377)
--manager Try joining as a manager.
--secret string Secret for node acceptance
--token string Token for entry into the swarm
```
Join a node to a Swarm cluster. If the `--manager` flag is specified, the docker engine
targeted by this command becomes a `manager`. If it is not specified, it becomes a `worker`.
Join a node to a swarm. The node joins as a manager node or worker node based upon the token you
pass with the `--token` flag. If you pass a manager token, the node joins as a manager. If you
pass a worker token, the node joins as a worker.
### Join a node to swarm as a manager
The example below demonstrates joining a manager node using a manager token.
```bash
$ docker swarm join --secret 4ao565v9jsuogtq5t8s379ulb --manager --listen-addr 192.168.99.122:2377 192.168.99.121:2377
This node joined a Swarm as a manager.
$ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 --listen-addr 192.168.99.122:2377 192.168.99.121:2377
This node joined a swarm as a manager.
$ docker node ls
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
dkp8vy1dq1kxleu9g4u78tlag * manager2 Accepted Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 manager1 Accepted Ready Active Reachable Yes
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
dkp8vy1dq1kxleu9g4u78tlag * manager2 Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 manager1 Ready Active Leader
```
A cluster should only have 3-7 managers at most, because a majority of managers must be available
for the cluster to function. Nodes that aren't meant to participate in this management quorum
should join as workers instead. Managers should be stable hosts that have static IP addresses.
### Join a node to swarm as a worker
The example below demonstrates joining a worker node using a worker token.
```bash
$ docker swarm join --secret 4ao565v9jsuogtq5t8s379ulb --listen-addr 192.168.99.123:2377 192.168.99.121:2377
This node joined a Swarm as a worker.
$ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx --listen-addr 192.168.99.123:2377 192.168.99.121:2377
This node joined a swarm as a worker.
$ docker node ls
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
7ln70fl22uw2dvjn2ft53m3q5 worker2 Accepted Ready Active
dkp8vy1dq1kxleu9g4u78tlag worker1 Accepted Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Accepted Ready Active Reachable Yes
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active
dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader
```
### `--ca-hash`
Hash of the Root Certificate Authority certificate used for trusted join.
### `--listen-addr value`
The node listens for inbound Swarm manager traffic on this IP:PORT
The node listens for inbound swarm manager traffic on this IP:PORT
### `--manager`
Joins the node as a manager
### `--secret string`
### `--token string`
Secret value required for nodes to join the swarm

76
docs/reference/commandline/swarm_join_token.md Normal file
View File

@ -0,0 +1,76 @@
<!--[metadata]>
+++
title = "swarm join-token"
description = "The swarm join-token command description and usage"
keywords = ["swarm, join-token"]
advisory = "rc"
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
# swarm join-token
```markdown
Usage: docker swarm join-token [--rotate] (worker|manager)
Manage join tokens
Options:
--help Print usage
-q, --quiet Only display token
--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`.
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:
```bash
$ docker swarm join-token worker
To add a worker to this swarm, run the following command:
docker swarm join \
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \
172.17.0.2:2377
$ docker swarm join-token manager
To add a manager to this swarm, run the following command:
docker swarm join \
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 \
172.17.0.2:2377
```
Use the `--rotate` flag to generate a new join token for the specified role:
```bash
$ docker swarm join-token --rotate worker
To add a worker to this swarm, run the following command:
docker swarm join \
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t \
172.17.0.2:2377
```
After using `--rotate`, only the new token will be valid for joining with the specified role.
The `-q` (or `--quiet`) flag only prints the token:
```bash
$ docker swarm join-token -q worker
SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t
```
### `--rotate`
Update the join token for a specified role with a new token and print the token.
### `--quiet`
Only print the token. Do not print a complete command for joining.
## Related information
* [swarm join](swarm_join.md)

18
docs/reference/commandline/swarm_leave.md
View File

@ -14,7 +14,7 @@ parent = "smn_cli"
```markdown
Usage: docker swarm leave [OPTIONS]
Leave a Swarm
Leave a swarm
Options:
--force Force leave ignoring warnings.
@ -26,10 +26,10 @@ This command causes the node to leave the swarm.
On a manager node:
```bash
$ docker node ls
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
7ln70fl22uw2dvjn2ft53m3q5 worker2 Accepted Ready Active
dkp8vy1dq1kxleu9g4u78tlag worker1 Accepted Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Accepted Ready Active Reachable Yes
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active
dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader
```
On a worker node:
@ -41,10 +41,10 @@ Node left the default swarm.
On a manager node:
```bash
$ docker node ls
ID HOSTNAME MEMBERSHIP STATUS AVAILABILITY MANAGER STATUS LEADER
7ln70fl22uw2dvjn2ft53m3q5 worker2 Accepted Down Active
dkp8vy1dq1kxleu9g4u78tlag worker1 Accepted Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Accepted Ready Active Reachable Yes
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
7ln70fl22uw2dvjn2ft53m3q5 worker2 Down Active
dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader
```
## Related information

8
docs/reference/commandline/swarm_update.md
View File

@ -14,23 +14,21 @@ parent = "smn_cli"
```markdown
Usage: docker swarm update [OPTIONS]
Update the Swarm
Update the swarm
Options:
--auto-accept value Auto acceptance policy (worker, manager or none)
--cert-expiry duration Validity period for node certificates (default 2160h0m0s)
--dispatcher-heartbeat duration Dispatcher heartbeat period (default 5s)
--external-ca value Specifications of one or more certificate signing endpoints
--help Print usage
--secret string Set secret value needed to accept nodes into cluster
--task-history-limit int Task history retention limit (default 10)
```
Updates a Swarm cluster with new parameter values. This command must target a manager node.
Updates a swarm cluster with new parameter values. This command must target a manager node.
```bash
$ docker swarm update --auto-accept manager
$ docker swarm update --cert-expirty 4000h0m0s
```
## Related information