1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
moby--moby/docs/swarm/manage-nodes.md
Charles Smith 704facbbab add swarm manage nodes guide
Signed-off-by: Charles Smith <charles.smith@docker.com>
2016-07-26 10:25:05 -07:00

219 lines
6.7 KiB
Markdown

<!--[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)