1. docker
  2. Commit 7b5c3d935a7a99b282f0f859101c887894a0b00e
Browse code

Clarify usage of --force when used on a swarm manager

Fixes #26125

Signed-off-by: Misty Stanley-Jones <misty@docker.com>

Misty Stanley-Jones authored on 2016/09/02 07:38:25
Showing 3 changed files
cli/command/swarm/leave.go
History View file @ 7b5c3d9
... ... 
@@ -19,7 +19,7 @@ func newLeaveCommand(dockerCli *command.DockerCli) *cobra.Command {
19 19
20 20 
 	cmd := &cobra.Command{
21 21 
 		Use:   "leave [OPTIONS]",
22 
-		Short: "Leave a swarm",
22 
+		Short: "Leave the swarm (workers only)",
23 23 
 		Args:  cli.NoArgs,
24 24 
 		RunE: func(cmd *cobra.Command, args []string) error {
25 25 
 			return runLeave(dockerCli, opts)
... ... 
@@ -27,7 +27,7 @@ func newLeaveCommand(dockerCli *command.DockerCli) *cobra.Command {
27 27 
 	}
28 28
29 29 
 	flags := cmd.Flags()
30 
-	flags.BoolVar(&opts.force, "force", false, "Force leave ignoring warnings.")
30 
+	flags.BoolVar(&opts.force, "force", false, "Force this node to leave the swarm, ignoring warnings")
31 31 
 	return cmd
32 32 
 }
33 33
docs/reference/commandline/node_rm.md
History View file @ 7b5c3d9
... ... 
@@ -23,36 +23,45 @@ Options:
23 23 
       --help   Print usage
24 24 
 ```
25 25
26 
-Removes specified nodes from a swarm.
26 
+When run from a manager node, removes the specified nodes from a swarm.
27 27
28 28
29 29 
 Example output:
30 30
31 
-    $ docker node rm swarm-node-02
32 
-    Node swarm-node-02 removed from swarm
31 
+```nohighlight
32 
+$ docker node rm swarm-node-02
33 33
34 
-Removes nodes from the swarm that are in the down state. Attempting to remove
35 
-an active node will result in an error:
34 
+Node swarm-node-02 removed from swarm
35 
+```
36 
+
37 
+Removes the specified nodes from the swarm, but only if the nodes are in the
38 
+down state. If you attempt to remove an active node you will receive an error:
36 39
37 
-```bash
40 
+```nohighlight
38 41 
 $ docker node rm swarm-node-03
39 
-Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not down and can't be removed
42 
+
43 
+Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not
44 
+down and can't be removed
40 45 
 ```
41 46
42 
-If a worker node becomes compromised, exhibits unexpected or unwanted behavior, or if you lose access to it so
43 
-that a clean shutdown is impossible, you can use the force option.
47 
+If you lose access to a worker node or need to shut it down because it has been
48 
+compromised or is not behaving as expected, you can use the `--force` option.
49 
+This may cause transient errors or interruptions, depending on the type of task
50 
+being run on the node.
44 51
45 
-```bash
52 
+```nohighlight
46 53 
 $ docker node rm --force swarm-node-03
54 
+
47 55 
 Node swarm-node-03 removed from swarm
48 56 
 ```
49 57
50 
-Note that manager nodes have to be demoted to worker nodes before they can be removed
51 
-from the cluster.
58 
+A manager node must be demoted to a worker node (using `docker node demote`)
59 
+before you can remove it from the swarm.
52 60
53 61 
 ## Related information
54 62
55 63 
 * [node inspect](node_inspect.md)
56 64 
 * [node update](node_update.md)
65 
+* [node demote](node_demote.md)
57 66 
 * [node ps](node_ps.md)
58 67 
 * [node ls](node_ls.md)
docs/reference/commandline/swarm_leave.md
History View file @ 7b5c3d9
... ... 
@@ -13,41 +13,41 @@ parent = "smn_cli"
13 13 
 ```markdown
14 14 
 Usage:  docker swarm leave [OPTIONS]
15 15
16 
-Leave a swarm
16 
+Leave the swarm (workers only).
17 17
18 18 
 Options:
19 
-      --force   Force leave ignoring warnings.
19 
+      --force   Force this node to leave the swarm, ignoring warnings
20 20 
       --help    Print usage
21 21 
 ```
22 22
23 
-This command causes the node to leave the swarm.
23 
+When you run this command on a worker, that worker leaves the swarm.
24 24
25 
-On a manager node:
25 
+You can use the `--force` option to on a manager to remove it from the swarm.
26 
+However, this does not reconfigure the swarm to ensure that there are enough
27 
+managers to maintain a quorum in the swarm. The safe way to remove a manager
28 
+from a swarm is to demote it to a worker and then direct it to leave the quorum
29 
+without using `--force`. Only use `--force` in situations where the swarm will
30 
+no longer be used after the manager leaves, such as in a single-node swarm.
31 
+
32 
+Consider the following swarm, as seen from the manager:
26 33 
 ```bash
27 34 
 $ docker node ls
28 35 
 ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
29 36 
 7ln70fl22uw2dvjn2ft53m3q5    worker2   Ready   Active
30 
-dkp8vy1dq1kxleu9g4u78tlag    worker1   Ready   Active        Reachable
37 
+dkp8vy1dq1kxleu9g4u78tlag    worker1   Ready   Active
31 38 
 dvfxp4zseq4s0rih1selh0d20 *  manager1  Ready   Active        Leader
32 39 
 ```
33 40
34 
-On a worker node, worker2 in the following example:
41 
+To remove `worker2`, issue the following command from `worker2` itself:
35 42 
 ```bash
36 43 
 $ docker swarm leave
37 44 
 Node left the default swarm.
38 45 
 ```
39 
-
40 
-On a manager node:
41 
-```bash
42 
-$ docker node ls
43 
-ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
44 
-7ln70fl22uw2dvjn2ft53m3q5    worker2   Down    Active
45 
-dkp8vy1dq1kxleu9g4u78tlag    worker1   Ready   Active        Reachable
46 
-dvfxp4zseq4s0rih1selh0d20 *  manager1  Ready   Active        Leader
47 
-```
46 
+To remove an inactive node, use the [`node rm`](swarm_rm.md) command instead.
48 47
49 48 
 ## Related information
50 49
50 
+* [node rm](node_rm.md)
51 51 
 * [swarm init](swarm_init.md)
52 52 
 * [swarm join](swarm_join.md)
53 53 
 * [swarm update](swarm_update.md)