beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #25076 from sfsmithcha/add_manage_nodes_guide

Browse source 
author merge: add swarm manage nodes guide
This commit is contained in:
Charles Smith 2016-07-26 11:33:46 -07:00 committed by GitHub
commit 08d1995fbf
5 changed files with 230 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/swarm/admin_guide.md
View file

@ -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:

219
docs/swarm/manage-nodes.md Normal file
View file

@ -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)

7
docs/swarm/menu.md
View file

@ -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:

2
docs/swarm/raft.md
View file

@ -7,7 +7,7 @@ advisory = "rc"
[menu.main]
identifier="raft"
parent="engine_swarm"
weight="13"
weight="21"
+++
<![end-metadata]-->

1
docs/swarm/swarm-tutorial/menu.md
View file

@ -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"