From 24df98212863a8a59de6e5d4e7759a75f706c3da Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Thu, 1 Sep 2016 15:38:25 -0700 Subject: [PATCH] Clarify usage of --force when used on a swarm manager Fixes #26125 Signed-off-by: Misty Stanley-Jones (cherry picked from commit 7b5c3d935a7a99b282f0f859101c887894a0b00e) Signed-off-by: Victor Vieux --- api/client/swarm/leave.go | 4 +-- docs/reference/commandline/node_rm.md | 37 ++++++++++++++--------- docs/reference/commandline/swarm_leave.md | 30 +++++++++--------- 3 files changed, 40 insertions(+), 31 deletions(-) diff --git a/api/client/swarm/leave.go b/api/client/swarm/leave.go index acaa7c82c1..52d83dcee6 100644 --- a/api/client/swarm/leave.go +++ b/api/client/swarm/leave.go @@ -19,7 +19,7 @@ func newLeaveCommand(dockerCli *client.DockerCli) *cobra.Command { cmd := &cobra.Command{ Use: "leave [OPTIONS]", - Short: "Leave a swarm", + Short: "Leave the swarm (workers only)", Args: cli.NoArgs, RunE: func(cmd *cobra.Command, args []string) error { return runLeave(dockerCli, opts) @@ -27,7 +27,7 @@ func newLeaveCommand(dockerCli *client.DockerCli) *cobra.Command { } flags := cmd.Flags() - flags.BoolVar(&opts.force, "force", false, "Force leave ignoring warnings.") + flags.BoolVar(&opts.force, "force", false, "Force this node to leave the swarm, ignoring warnings") return cmd } diff --git a/docs/reference/commandline/node_rm.md b/docs/reference/commandline/node_rm.md index 6f1d13cd2b..36ff355ab9 100644 --- a/docs/reference/commandline/node_rm.md +++ b/docs/reference/commandline/node_rm.md @@ -25,36 +25,45 @@ Options: --help Print usage ``` -Removes specified nodes from a swarm. +When run from a manager node, removes the specified nodes from a swarm. Example output: - $ docker node rm swarm-node-02 - Node swarm-node-02 removed from swarm +```nohighlight +$ docker node rm swarm-node-02 -Removes nodes from the swarm that are in the down state. Attempting to remove -an active node will result in an error: - -```bash -$ docker node rm swarm-node-03 -Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not down and can't be removed +Node swarm-node-02 removed from swarm ``` -If a worker node becomes compromised, exhibits unexpected or unwanted behavior, or if you lose access to it so -that a clean shutdown is impossible, you can use the force option. +Removes the specified nodes from the swarm, but only if the nodes are in the +down state. If you attempt to remove an active node you will receive an error: -```bash +```nohighlight +$ docker node rm swarm-node-03 + +Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not +down and can't be removed +``` + +If you lose access to a worker node or need to shut it down because it has been +compromised or is not behaving as expected, you can use the `--force` option. +This may cause transient errors or interruptions, depending on the type of task +being run on the node. + +```nohighlight $ docker node rm --force swarm-node-03 + Node swarm-node-03 removed from swarm ``` -Note that manager nodes have to be demoted to worker nodes before they can be removed -from the cluster. +A manager node must be demoted to a worker node (using `docker node demote`) +before you can remove it from the swarm. ## Related information * [node inspect](node_inspect.md) * [node update](node_update.md) +* [node demote](node_demote.md) * [node ps](node_ps.md) * [node ls](node_ls.md) diff --git a/docs/reference/commandline/swarm_leave.md b/docs/reference/commandline/swarm_leave.md index d1de2306b8..ecdfc321f8 100644 --- a/docs/reference/commandline/swarm_leave.md +++ b/docs/reference/commandline/swarm_leave.md @@ -15,41 +15,41 @@ parent = "smn_cli" ```markdown Usage: docker swarm leave [OPTIONS] -Leave a swarm +Leave the swarm (workers only). Options: - --force Force leave ignoring warnings. + --force Force this node to leave the swarm, ignoring warnings --help Print usage ``` -This command causes the node to leave the swarm. +When you run this command on a worker, that worker leaves the swarm. -On a manager node: +You can use the `--force` option to on a manager to remove it from the swarm. +However, this does not reconfigure the swarm to ensure that there are enough +managers to maintain a quorum in the swarm. The safe way to remove a manager +from a swarm is to demote it to a worker and then direct it to leave the quorum +without using `--force`. Only use `--force` in situations where the swarm will +no longer be used after the manager leaves, such as in a single-node swarm. + +Consider the following swarm, as seen from the manager: ```bash $ docker node ls ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 7ln70fl22uw2dvjn2ft53m3q5 worker2 Ready Active -dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable +dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader ``` -On a worker node, worker2 in the following example: +To remove `worker2`, issue the following command from `worker2` itself: ```bash $ docker swarm leave Node left the default swarm. ``` - -On a manager node: -```bash -$ docker node ls -ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS -7ln70fl22uw2dvjn2ft53m3q5 worker2 Down Active -dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable -dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader -``` +To remove an inactive node, use the [`node rm`](swarm_rm.md) command instead. ## Related information +* [node rm](node_rm.md) * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) * [swarm update](swarm_update.md)