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

Fixes #26125

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
(cherry picked from commit 7b5c3d935a7a99b282f0f859101c887894a0b00e)
Signed-off-by: Victor Vieux <vieux@docker.com>

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
 }
 

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:
+Node swarm-node-02 removed from swarm
+```
+
+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
+
+Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not
+down and can't be removed
 ```
 
-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.
+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.
 
-```bash
+```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)

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)