From 088cfc36debd63010dcab249df47e35341152c90 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 --- docs/reference/commandline/node_rm.md | 37 ++++++++++++++--------- docs/reference/commandline/swarm_leave.md | 30 +++++++++--------- 2 files changed, 38 insertions(+), 29 deletions(-) diff --git a/docs/reference/commandline/node_rm.md b/docs/reference/commandline/node_rm.md index f5d5daaf1c..ee6dcf7212 100644 --- a/docs/reference/commandline/node_rm.md +++ b/docs/reference/commandline/node_rm.md @@ -23,36 +23,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 938caae58e..99185dbb50 100644 --- a/docs/reference/commandline/swarm_leave.md +++ b/docs/reference/commandline/swarm_leave.md @@ -13,41 +13,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)