add swarm manage nodes guide

Signed-off-by: Charles Smith <charles.smith@docker.com>
(cherry picked from commit 704facbbab0af520e0429eb75a6f875b6015a77c)
Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>

5 files changed, 230 insertions, 9 deletions

diff --git a/docs/swarm/admin_guide.md b/docs/swarm/admin_guide.md
index b62f882e0c..e47510e134 100644
--- a/docs/swarm/admin_guide.md
+++ b/docs/swarm/admin_guide.md
@@ -3,23 +3,23 @@
 aliases = [
 "/engine/swarm/manager-administration-guide/"
 ]
-title = "Swarm Manager Administration Guide"
+title = "Swarm administration guide"
 description = "Manager administration guide"
 keywords = ["docker, container, cluster, swarm, manager, raft"]
 advisory = "rc"
 [menu.main]
 identifier="manager_admin_guide"
 parent="engine_swarm"
-weight="12"
+weight="20"
 +++
 <![end-metadata]-->
 
 # Administer and maintain a swarm of Docker Engines
 
 When you run a swarm of Docker Engines, **manager nodes** are the key components
-for managing the cluster and storing the cluster state. It is important to understand
-some key features of manager nodes in order to properly deploy and maintain the
-swarm.
+for managing the cluster and storing the cluster state. It is important to
+understand some key features of manager nodes in order to properly deploy and
+maintain the swarm.
 
 This article covers the following swarm administration tasks:
 
diff --git a/docs/swarm/manage-nodes.md b/docs/swarm/manage-nodes.md
new file mode 100644
index 0000000000..673b7587a4
--- /dev/null
+++ b/docs/swarm/manage-nodes.md
@@ -0,0 +1,219 @@
+<!--[metadata]>
++++
+title = "Manage nodes in a swarm"
+description = "Manage existing nodes in a swarm"
+keywords = ["guide, swarm mode, node"]
+[menu.main]
+identifier="manage-nodes-guide"
+parent="engine_swarm"
+weight=14
++++
+<![end-metadata]-->
+
+# Manage nodes in a swarm
+
+As part of the swarm management lifecycle, you may need to view or update a node as follows:
+
+* [list nodes in the swarm](#list-nodes)
+* [inspect an individual node](#inspect-an-individual-node)
+* [update a node](#update-a-node)
+* [leave the swarm](#leave-the-swarm)
+
+## List nodes
+
+To view a list of nodes in the swarm run `docker node ls` from a manager node:
+
+```bash
+$ docker node ls
+
+ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
+46aqrk4e473hjbt745z53cr3t    node-5    Ready   Active        Reachable
+61pi3d91s0w3b90ijw3deeb2q    node-4    Ready   Active        Reachable
+a5b2m3oghd48m8eu391pefq5u    node-3    Ready   Active
+e7p8btxeu3ioshyuj6lxiv6g0    node-2    Ready   Active
+ehkv3bcimagdese79dn78otj5 *  node-1    Ready   Active        Leader
+```
+
+The `AVAILABILITY` column shows whether or not the scheduler can assign tasks to
+the node:
+
+* `Active` means that the scheduler can assign tasks to a node.
+* `Pause` means the scheduler doesn't assign new tasks to the node, but existing
+tasks remain running.
+* `Drain` means the scheduler doesn't assign new tasks to the node. The
+scheduler shuts down any existing tasks and schedules them on an available
+node.
+
+The `MANAGER STATUS` column shows node participation in the Raft consensus:
+
+* No value indicates a worker node that does not participate in swarm
+management.
+* `Leader` means the node is the primary manager node that makes all swarm
+management and orchestration decisions for the swarm.
+* `Reachable` means the node is a manager node is participating in the Raft
+consensus. If the leader node becomes unavailable, the node is eligible for
+election as the new leader.
+* `Unavailable` means the node is a manager that is not able to communicate with
+other managers. If a manager node becomes unavailable, you should either join a
+new manager node to the swarm or promote a worker node to be a
+manager.
+
+For more information on swarm administration refer to the [Swarm administration guide](admin_guide.md).
+
+## Inspect an individual node
+
+You can run `docker node inspect <NODE-ID>` on a manager node to view the
+details for an individual node. The output defaults to JSON format, but you can
+pass the `--pretty` flag to print the results in human-readable format. For example:
+
+```bash
+docker node inspect self --pretty
+
+ID:			ehkv3bcimagdese79dn78otj5
+Hostname:		node-1
+Status:
+ State:			Ready
+ Availability:		Active
+Manager Status:
+ Address:		172.17.0.2:2377
+ Raft Status:		Reachable
+ Leader:		Yes
+Platform:
+ Operating System:	linux
+ Architecture:		x86_64
+Resources:
+ CPUs:			2
+ Memory:		1.954 GiB
+Plugins:
+  Network:		overlay, host, bridge, overlay, null
+  Volume:		local
+Engine Version:		1.12.0-dev
+```
+
+## Update a node
+
+You can modify node attributes as follows:
+
+* [change node availability](#change-node-availability)
+* [add or remove label metadata](#add-or-remove-label-metadata)
+* [change a node role](#promote-or-demote-a-node)
+
+### Change node availability
+
+Changing node availability lets you:
+
+* drain a manager node so that only performs swarm management tasks and is
+unavailable for task assignment.
+* drain a node so you can take it down for maintenance.
+* pause a node so it is unavailable to receive new tasks.
+* restore unavailable or paused nodes available status.
+
+For example, to change a manager node to `Drain` availability:
+
+```bash
+$ docker node update --availability drain node-1
+
+node-1
+```
+
+See [list nodes](#list-nodes) for descriptions of the different availability
+options.
+
+### Add or remove label metadata
+
+Node labels provide a flexible method of node organization. You can also use
+node labels in service constraints. Apply constraints when you create a service
+to limit the nodes where the scheduler assigns tasks for the service.
+
+Run `docker node update --label-add` on a manager node to add label metadata to
+a node. The `--label-add` flag supports either a `<key>` or a `<key>=<value>`
+pair.
+
+Pass the `--label-add` flag once for each node label you want to add:
+
+```bash
+$ docker node update --label-add foo --label-add bar=baz node-1
+
+node-1
+```
+
+The labels you set for nodes using docker node update apply only to the node
+entity within the swarm. Do not confuse them with the docker daemon labels for
+[dockerd](../userguide/labels-custom-metadata.md#daemon-labels).
+
+Refer to the `docker service create` [CLI reference](../reference/commandline/service_create.md)
+for more information about service constraints.
+
+### Promote or demote a node
+
+You can promote a worker node to the manager role. This is useful when a
+manager node becomes unavailable or if you want to take a manager offline for
+maintenance. Similarly, you can demote a manager node to the worker role.
+
+Regardless of your reason to promote or demote a node, you should always
+maintain an odd number of manager nodes in the swarm. For more information refer
+to the [Swarm administration guide](admin_guide.md).
+
+To promote a node or set of nodes, run `docker node promote` from a manager
+node:
+
+```bash
+$ docker node promote node-3 node-2
+
+Node node-3 promoted to a manager in the swarm.
+Node node-2 promoted to a manager in the swarm.
+```
+
+To demote a node or set of nodes, run `docker node demote` from a manager node:
+
+```bash
+$ docker node demote node-3 node-2
+
+Manager node-3 demoted in the swarm.
+Manager node-2 demoted in the swarm.
+```
+
+`docker node promote` and `docker node demote` are convenience commands for
+`docker node update --role manager` and `docker node update --role worker`
+respectively.
+
+
+## Leave the swarm
+
+Run the `docker swarm leave` command on a node to remove it from the swarm.
+
+For example to leave the swarm on a worker node:
+
+```bash
+$ docker swarm leave
+
+Node left the swarm.
+```
+
+When a node leaves the swarm, the Docker Engine stops running in swarm
+mode. The orchestrator no longer schedules tasks to the node.
+
+If the node is a manager node, you will receive a warning about maintaining the
+quorum. To override the warning, pass the `--force` flag. If the last manager
+node leaves the swarm, the swarm becomes unavailable requiring you to take
+disaster recovery measures.
+
+For information about maintaining a quorum and disaster recovery, refer to the
+[Swarm administration guide](admin_guide.md).
+
+After a node leaves the swarm, you can run the `docker node rm` command on a
+manager node to remove the node from the node list.
+
+For instance:
+
+```bash
+docker node rm node-2
+
+node-2
+```
+
+## Learn More
+
+* [Swarm administration guide](admin_guide.md)
+* [Docker Engine command line reference](../reference/commandline/index.md)
+* [Swarm mode tutorial](swarm-tutorial/index.md)
diff --git a/docs/swarm/menu.md b/docs/swarm/menu.md
index e74c724f7b..d07edd97b9 100644
--- a/docs/swarm/menu.md
+++ b/docs/swarm/menu.md
@@ -1,9 +1,10 @@
 <!--[metadata]>
 +++
-title = "Manage a Swarm (1.12 RC)"
-description = "How to use Docker Swarm to create and manage Docker Engine clusters"
+title = "Manage a swarm (1.12 RC)"
+description = "How to use Docker Engine swarm mode"
 keywords = [" docker, documentation, developer, "]
 advisory = "rc"
+type = "menu"
 [menu.main]
 identifier = "engine_swarm"
 parent = "engine_use"
@@ -12,7 +13,7 @@ weight = 0
 <![end-metadata]-->
 
 
-## Use Docker Swarm to create and manage clusters of Docker Engine called Swarms
+## Use Docker Engine to create and manage a swarm
 
 This section contains the following topics:
 
diff --git a/docs/swarm/raft.md b/docs/swarm/raft.md
index 12db78672c..1fd398000f 100644
--- a/docs/swarm/raft.md
+++ b/docs/swarm/raft.md
@@ -7,7 +7,7 @@ advisory = "rc"
 [menu.main]
 identifier="raft"
 parent="engine_swarm"
-weight="13"
+weight="21"
 +++
 <![end-metadata]-->
 
diff --git a/docs/swarm/swarm-tutorial/menu.md b/docs/swarm/swarm-tutorial/menu.md
index 4b2476eee6..cb4273e36f 100644
--- a/docs/swarm/swarm-tutorial/menu.md
+++ b/docs/swarm/swarm-tutorial/menu.md
@@ -4,6 +4,7 @@ title = "Get started with swarm mode"
 description = "Getting started tutorial for Docker swarm mode"
 keywords = ["cluster, swarm, tutorial"]
 advisory = "rc"
+type="menu"
 [menu.main]
 identifier="swarm-tutorial"
 parent="engine_swarm"