docker node ls

Estimated reading time: 5 minutes

Edge only: This is the CLI reference for Docker CE Edge versions. Some of these options may not be available to Docker CE stable or Docker EE. You can view the stable version of this CLI reference or learn about Docker CE Edge.

Description

List nodes in the swarm

API 1.24+ The client and daemon API must both be at least 1.24 to use this command. Use the docker version command on the client to check your client and daemon API versions.

Usage

docker node ls [OPTIONS]

Options

Name, shorthand	Default	Description
`--filter , -f`		Filter output based on conditions provided
`--format`		Pretty-print nodes using a Go template
`--quiet , -q`		Only display IDs

Parent command

Command	Description
docker node	Manage Swarm nodes

Command	Description
docker node demote	Demote one or more nodes from manager in the swarm
docker node inspect	Display detailed information on one or more nodes
docker node ls	List nodes in the swarm
docker node promote	Promote one or more nodes to manager in the swarm
docker node ps	List tasks running on one or more nodes, defaults to current node
docker node rm	Remove one or more nodes from the swarm
docker node update	Update a node

Extended description

Lists all the nodes that the Docker Swarm manager knows about. You can filter using the -f or --filter flag. Refer to the filtering section for more information about available filter options.

Examples

$ docker node ls

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0    swarm-worker2   Ready   Active
38ciaotwjuritcdtn9npbnkuz    swarm-worker1   Ready   Active
e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader

Note: In the above example output, there is a hidden column of .Self that indicates if the node is the same node as the current docker daemon. A * (e.g., e216jshn25ckzbvmwlnh5jr3g *) means this node is the current docker daemon.

Filtering

The filtering flag (-f or --filter) format is of “key=value”. If there is more than one filter, then pass multiple flags (e.g., --filter "foo=bar" --filter "bif=baz")

The currently supported filters are:

id

The id filter matches all or part of a node’s id.

$ docker node ls -f id=1

ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active

label

The label filter matches nodes based on engine labels and on the presence of a label alone or a label and a value. Node labels are currently not used for filtering.

The following filter matches nodes with the foo label regardless of its value.

$ docker node ls -f "label=foo"

ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active

membership

The membership filter matches nodes based on the presence of a membership and a value accepted or pending.

The following filter matches nodes with the membership of accepted.

$ docker node ls -f "membership=accepted"

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0    swarm-worker2   Ready   Active
38ciaotwjuritcdtn9npbnkuz    swarm-worker1   Ready   Active

name

The name filter matches on all or part of a node hostname.

The following filter matches the nodes with a name equal to swarm-master string.

$ docker node ls -f name=swarm-manager1

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader

role

The role filter matches nodes based on the presence of a role and a value worker or manager.

The following filter matches nodes with the manager role.

$ docker node ls -f "role=manager"

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader

Formatting

The formatting options (--format) pretty-prints nodes output using a Go template.

Valid placeholders for the Go template are listed below:

Placeholder	Description
`.ID`	Node ID
`.Self`	Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon)
`.Hostname`	Node hostname
`.Status`	Node status
`.Availability`	Node availability (“active”, “pause”, or “drain”)
`.ManagerStatus`	Manager status of the node
`.TLSStatus`	TLS status of the node (“Ready”, or “Needs Rotation” has TLS certificate signed by an old CA)

When using the --format option, the node ls command will either output the data exactly as the template declares or, when using the table directive, includes column headers as well.

The following example uses a template without headers and outputs the ID, Hostname, and TLS Status entries separated by a colon for all nodes:

$ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}"
e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready
35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation