Read Docker Swarm Nodes Without Changing the Cluster

You will use docker node ls to inspect the nodes known to a Docker Swarm manager, narrow the list with filters, and choose output that is suitable for a person or a script. The command is read-only: it does not promote, demote, drain or remove a node. Allow about ten minutes if you already have access to a Swarm manager.

Prerequisite: the Docker CLI must be installed, and the selected Docker context must connect to a Swarm manager. This guide uses Docker CLI 29.8.1, installed from the docker-ce-cli package on this machine. Output columns and formatting features can differ between CLI releases, so check the local help when reproducing an example elsewhere.

1. Check the client and selected context

Start by checking the CLI version and the endpoint that the command will use:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker context show
default

The context name is only a routing choice. It does not prove that the endpoint is a Swarm manager. Do not change contexts or initialise a swarm just to make this listing work. docker swarm init changes cluster state and can create a new single-node swarm, which is outside this inspection task.

2. List every node from a manager

Run the command without options:

$ docker node ls
ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb *   swarm-manager1  Ready     Active           Leader           23.0.3
2lm9w9kbepgvkzkkeyku40e65     swarm-worker1   Ready     Active                            23.0.3

The exact IDs, names and versions will be different. The asterisk marks the node associated with the current Docker daemon. STATUS describes the node's condition, AVAILABILITY is its scheduling state, and MANAGER STATUS is populated for managers. A blank manager-status field normally means the node is a worker, not that the command failed.

This is a manager-only cluster command. On this machine, which is not a Swarm manager, the same command returns: This node is not a swarm manager. That error is an access or endpoint problem, not evidence that the swarm has no nodes.

Use docker node ls --help to confirm the options exposed by the installed client:

$ docker node ls --help
Usage:  docker node ls [OPTIONS]

List nodes in the swarm

3. Filter the list for a question

Filters use key=value. The supported keys documented for this command include id, label, node.label, membership, name and role. Pass --filter more than once when you need more than one filter:

$ docker node ls --filter 'role=manager'
$ docker node ls --filter 'membership=accepted'
$ docker node ls --filter 'name=swarm-manager1'
$ docker node ls --filter 'id=1'

The id value can match all or part of a node ID, and name matches all or part of a node hostname. The role values are manager and worker. Membership values are accepted and pending. If a filter produces no rows, check spelling and the selected context before treating that as a cluster condition.

Engine labels and Swarm node labels are different filters. Use label for an engine label and node.label for a label assigned to the Swarm node:

$ docker node ls --filter 'node.label=region'
$ docker node ls --filter 'node.label=region=region-a'
$ docker node ls --filter 'label=example'

These commands only query labels. Do not substitute docker node update --label-add unless changing scheduling metadata is explicitly approved. That update changes cluster behaviour.

4. Produce compact or machine-readable output

For a list of IDs only, use quiet mode:

$ docker node ls --quiet
yg550ettvsjn6g6t840iaiwgb
2lm9w9kbepgvkzkkeyku40e65

This is useful as input to a reviewed script, but an ID alone does not tell you whether a node is ready or drainable. Keep the normal table output when a person needs operational context.

For a stable, selected set of fields, use a Go template. The available fields include .ID, .Self, .Hostname, .Status, .Availability, .ManagerStatus, .TLSStatus and .EngineVersion:

$ docker node ls --format '{{.Hostname}}: {{.Status}}/{{.Availability}}'
swarm-manager1: Ready/Active
swarm-worker1: Ready/Active

The template above omits headers, so label it yourself if another program or person needs to know what each field means. For one JSON object per node, use the documented JSON directive:

$ docker node ls --format json
{"Availability":"Active","EngineVersion":"23.0.3","Hostname":"swarm-manager1","ID":"yg550ettvsjn6g6t840iaiwgb","ManagerStatus":"Leader","Self":true,"Status":"Ready","TLSStatus":"Ready"}

Do not parse the aligned table with awk or fixed character positions. Columns can be blank, added or adjusted by the CLI. Prefer a template or JSON when another command will consume the result.

5. Diagnose the common failures

Not a Swarm manager: verify the context and endpoint, then repeat the command against an existing manager. A worker can run many Docker commands but cannot use this manager-only listing. Do not run docker swarm init on a production host as a repair step.

Permission or connection errors: check the current context, Docker socket access and the administrator's access method. The listing itself does not normally require sudo. Elevation changes which local Docker socket or credentials are used, so use it only when your host policy specifically requires it, and confirm the resulting context rather than assuming it is the same daemon.

Unexpectedly empty or stale-looking data: repeat the unfiltered command, record the context with docker context show, and compare the manager endpoint with the one that owns the swarm. A filter can hide nodes, and a different context can show a different cluster. Check STATUS, AVAILABILITY and MANAGER STATUS together before taking action elsewhere.

A script breaks after an upgrade: run docker node ls --help on the target machine and confirm the fields it expects. Pin the output contract in the script, handle blank manager fields, and treat command failure as a failure rather than as an empty node list.