---
description: Manage existing nodes in a swarm
keywords: guide, swarm mode, node
title: Manage nodes in a swarm
---

As part of the swarm management lifecycle, you may need to:

* [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:

```console
$ 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 the 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 participating in the Raft
  consensus quorum. If the leader node becomes unavailable, the node is eligible for
  election as the new leader.
* `Unavailable` means the node is a manager that can't 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:

```console
$ docker node inspect self --pretty

ID:                     ehkv3bcimagdese79dn78otj5
Hostname:               node-1
Joined at:              2016-06-16 22:52:44.9910662 +0000 utc
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 to:

* [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 it 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 can't receive new tasks.
* Restore unavailable or paused nodes availability status.

For example, to change a manager node to `Drain` availability:

```console
$ 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