1. docker
  2. Commit ef19b22b856a77ce6c55101216b3b7e1b3ea7886
Browse code

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>

Charles Smith authored on 2016/07/27 00:15:37
Showing 5 changed files
docs/swarm/admin_guide.md
History View file @ ef19b22
... ... 
@@ -3,23 +3,23 @@
3 3 
 aliases = [
4 4 
 "/engine/swarm/manager-administration-guide/"
5 5 
 ]
6 
-title = "Swarm Manager Administration Guide"
6 
+title = "Swarm administration guide"
7 7 
 description = "Manager administration guide"
8 8 
 keywords = ["docker, container, cluster, swarm, manager, raft"]
9 9 
 advisory = "rc"
10 10 
 [menu.main]
11 11 
 identifier="manager_admin_guide"
12 12 
 parent="engine_swarm"
13 
-weight="12"
13 
+weight="20"
14 14 
 +++
15 15 
 <![end-metadata]-->
16 16
17 17 
 # Administer and maintain a swarm of Docker Engines
18 18
19 19 
 When you run a swarm of Docker Engines, **manager nodes** are the key components
20 
-for managing the cluster and storing the cluster state. It is important to understand
21 
-some key features of manager nodes in order to properly deploy and maintain the
22 
-swarm.
20 
+for managing the cluster and storing the cluster state. It is important to
21 
+understand some key features of manager nodes in order to properly deploy and
22 
+maintain the swarm.
23 23
24 24 
 This article covers the following swarm administration tasks:
25 25
docs/swarm/manage-nodes.md
History View file @ ef19b22
26 26 
new file mode 100644
... ... 
@@ -0,0 +1,219 @@
0 
+<!--[metadata]>
1 
+title = "Manage nodes in a swarm"
2 
+description = "Manage existing nodes in a swarm"
3 
+keywords = ["guide, swarm mode, node"]
4 
+[menu.main]
5 
+identifier="manage-nodes-guide"
6 
+parent="engine_swarm"
7 
+weight=14
8 
+<![end-metadata]-->
9 
+
10 
+# Manage nodes in a swarm
11 
+
12 
+As part of the swarm management lifecycle, you may need to view or update a node as follows:
13 
+
14 
+* [list nodes in the swarm](#list-nodes)
15 
+* [inspect an individual node](#inspect-an-individual-node)
16 
+* [update a node](#update-a-node)
17 
+* [leave the swarm](#leave-the-swarm)
18 
+
19 
+## List nodes
20 
+
21 
+To view a list of nodes in the swarm run `docker node ls` from a manager node:
22 
+
23 
+```bash
24 
+$ docker node ls
25 
+
26 
+ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
27 
+46aqrk4e473hjbt745z53cr3t    node-5    Ready   Active        Reachable
28 
+61pi3d91s0w3b90ijw3deeb2q    node-4    Ready   Active        Reachable
29 
+a5b2m3oghd48m8eu391pefq5u    node-3    Ready   Active
30 
+e7p8btxeu3ioshyuj6lxiv6g0    node-2    Ready   Active
31 
+ehkv3bcimagdese79dn78otj5 *  node-1    Ready   Active        Leader
32 
+```
33 
+
34 
+The `AVAILABILITY` column shows whether or not the scheduler can assign tasks to
35 
+the node:
36 
+
37 
+* `Active` means that the scheduler can assign tasks to a node.
38 
+* `Pause` means the scheduler doesn't assign new tasks to the node, but existing
39 
+tasks remain running.
40 
+* `Drain` means the scheduler doesn't assign new tasks to the node. The
41 
+scheduler shuts down any existing tasks and schedules them on an available
42 
+node.
43 
+
44 
+The `MANAGER STATUS` column shows node participation in the Raft consensus:
45 
+
46 
+* No value indicates a worker node that does not participate in swarm
47 
+management.
48 
+* `Leader` means the node is the primary manager node that makes all swarm
49 
+management and orchestration decisions for the swarm.
50 
+* `Reachable` means the node is a manager node is participating in the Raft
51 
+consensus. If the leader node becomes unavailable, the node is eligible for
52 
+election as the new leader.
53 
+* `Unavailable` means the node is a manager that is not able to communicate with
54 
+other managers. If a manager node becomes unavailable, you should either join a
55 
+new manager node to the swarm or promote a worker node to be a
56 
+manager.
57 
+
58 
+For more information on swarm administration refer to the [Swarm administration guide](admin_guide.md).
59 
+
60 
+## Inspect an individual node
61 
+
62 
+You can run `docker node inspect <NODE-ID>` on a manager node to view the
63 
+details for an individual node. The output defaults to JSON format, but you can
64 
+pass the `--pretty` flag to print the results in human-readable format. For example:
65 
+
66 
+```bash
67 
+docker node inspect self --pretty
68 
+
69 
+ID:			ehkv3bcimagdese79dn78otj5
70 
+Hostname:		node-1
71 
+Status:
72 
+ State:			Ready
73 
+ Availability:		Active
74 
+Manager Status:
75 
+ Address:		172.17.0.2:2377
76 
+ Raft Status:		Reachable
77 
+ Leader:		Yes
78 
+Platform:
79 
+ Operating System:	linux
80 
+ Architecture:		x86_64
81 
+Resources:
82 
+ CPUs:			2
83 
+ Memory:		1.954 GiB
84 
+Plugins:
85 
+  Network:		overlay, host, bridge, overlay, null
86 
+  Volume:		local
87 
+Engine Version:		1.12.0-dev
88 
+```
89 
+
90 
+## Update a node
91 
+
92 
+You can modify node attributes as follows:
93 
+
94 
+* [change node availability](#change-node-availability)
95 
+* [add or remove label metadata](#add-or-remove-label-metadata)
96 
+* [change a node role](#promote-or-demote-a-node)
97 
+
98 
+### Change node availability
99 
+
100 
+Changing node availability lets you:
101 
+
102 
+* drain a manager node so that only performs swarm management tasks and is
103 
+unavailable for task assignment.
104 
+* drain a node so you can take it down for maintenance.
105 
+* pause a node so it is unavailable to receive new tasks.
106 
+* restore unavailable or paused nodes available status.
107 
+
108 
+For example, to change a manager node to `Drain` availability:
109 
+
110 
+```bash
111 
+$ docker node update --availability drain node-1
112 
+
113 
+node-1
114 
+```
115 
+
116 
+See [list nodes](#list-nodes) for descriptions of the different availability
117 
+options.
118 
+
119 
+### Add or remove label metadata
120 
+
121 
+Node labels provide a flexible method of node organization. You can also use
122 
+node labels in service constraints. Apply constraints when you create a service
123 
+to limit the nodes where the scheduler assigns tasks for the service.
124 
+
125 
+Run `docker node update --label-add` on a manager node to add label metadata to
126 
+a node. The `--label-add` flag supports either a `<key>` or a `<key>=<value>`
127 
+pair.
128 
+
129 
+Pass the `--label-add` flag once for each node label you want to add:
130 
+
131 
+```bash
132 
+$ docker node update --label-add foo --label-add bar=baz node-1
133 
+
134 
+node-1
135 
+```
136 
+
137 
+The labels you set for nodes using docker node update apply only to the node
138 
+entity within the swarm. Do not confuse them with the docker daemon labels for
139 
+[dockerd](../userguide/labels-custom-metadata.md#daemon-labels).
140 
+
141 
+Refer to the `docker service create` [CLI reference](../reference/commandline/service_create.md)
142 
+for more information about service constraints.
143 
+
144 
+### Promote or demote a node
145 
+
146 
+You can promote a worker node to the manager role. This is useful when a
147 
+manager node becomes unavailable or if you want to take a manager offline for
148 
+maintenance. Similarly, you can demote a manager node to the worker role.
149 
+
150 
+Regardless of your reason to promote or demote a node, you should always
151 
+maintain an odd number of manager nodes in the swarm. For more information refer
152 
+to the [Swarm administration guide](admin_guide.md).
153 
+
154 
+To promote a node or set of nodes, run `docker node promote` from a manager
155 
+node:
156 
+
157 
+```bash
158 
+$ docker node promote node-3 node-2
159 
+
160 
+Node node-3 promoted to a manager in the swarm.
161 
+Node node-2 promoted to a manager in the swarm.
162 
+```
163 
+
164 
+To demote a node or set of nodes, run `docker node demote` from a manager node:
165 
+
166 
+```bash
167 
+$ docker node demote node-3 node-2
168 
+
169 
+Manager node-3 demoted in the swarm.
170 
+Manager node-2 demoted in the swarm.
171 
+```
172 
+
173 
+`docker node promote` and `docker node demote` are convenience commands for
174 
+`docker node update --role manager` and `docker node update --role worker`
175 
+respectively.
176 
+
177 
+
178 
+## Leave the swarm
179 
+
180 
+Run the `docker swarm leave` command on a node to remove it from the swarm.
181 
+
182 
+For example to leave the swarm on a worker node:
183 
+
184 
+```bash
185 
+$ docker swarm leave
186 
+
187 
+Node left the swarm.
188 
+```
189 
+
190 
+When a node leaves the swarm, the Docker Engine stops running in swarm
191 
+mode. The orchestrator no longer schedules tasks to the node.
192 
+
193 
+If the node is a manager node, you will receive a warning about maintaining the
194 
+quorum. To override the warning, pass the `--force` flag. If the last manager
195 
+node leaves the swarm, the swarm becomes unavailable requiring you to take
196 
+disaster recovery measures.
197 
+
198 
+For information about maintaining a quorum and disaster recovery, refer to the
199 
+[Swarm administration guide](admin_guide.md).
200 
+
201 
+After a node leaves the swarm, you can run the `docker node rm` command on a
202 
+manager node to remove the node from the node list.
203 
+
204 
+For instance:
205 
+
206 
+```bash
207 
+docker node rm node-2
208 
+
209 
+node-2
210 
+```
211 
+
212 
+## Learn More
213 
+
214 
+* [Swarm administration guide](admin_guide.md)
215 
+* [Docker Engine command line reference](../reference/commandline/index.md)
216 
+* [Swarm mode tutorial](swarm-tutorial/index.md)
docs/swarm/menu.md
History View file @ ef19b22
... ... 
@@ -1,9 +1,10 @@
1 1 
 <!--[metadata]>
2 2 
 +++
3 
-title = "Manage a Swarm (1.12 RC)"
4 
-description = "How to use Docker Swarm to create and manage Docker Engine clusters"
3 
+title = "Manage a swarm (1.12 RC)"
4 
+description = "How to use Docker Engine swarm mode"
5 5 
 keywords = [" docker, documentation, developer, "]
6 6 
 advisory = "rc"
7 
+type = "menu"
7 8 
 [menu.main]
8 9 
 identifier = "engine_swarm"
9 10 
 parent = "engine_use"
... ... 
@@ -12,7 +13,7 @@ weight = 0
12 12 
 <![end-metadata]-->
13 13
14 14
15 
-## Use Docker Swarm to create and manage clusters of Docker Engine called Swarms
15 
+## Use Docker Engine to create and manage a swarm
16 16
17 17 
 This section contains the following topics:
18 18
docs/swarm/raft.md
History View file @ ef19b22
... ... 
@@ -7,7 +7,7 @@ advisory = "rc"
7 7 
 [menu.main]
8 8 
 identifier="raft"
9 9 
 parent="engine_swarm"
10 
-weight="13"
10 
+weight="21"
11 11 
 +++
12 12 
 <![end-metadata]-->
13 13
docs/swarm/swarm-tutorial/menu.md
History View file @ ef19b22
... ... 
@@ -4,6 +4,7 @@ title = "Get started with swarm mode"
4 4 
 description = "Getting started tutorial for Docker swarm mode"
5 5 
 keywords = ["cluster, swarm, tutorial"]
6 6 
 advisory = "rc"
7 
+type="menu"
7 8 
 [menu.main]
8 9 
 identifier="swarm-tutorial"
9 10 
 parent="engine_swarm"