1# node ls
2
3<!---MARKER_GEN_START-->
4List nodes in the swarm
5
6### Aliases
7
8`docker node ls`, `docker node list`
9
10### Options
11
12| Name | Type | Default | Description |
13|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
14| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
15| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
16| `-q`, `--quiet` | | | Only display IDs |
17
18
19<!---MARKER_GEN_END-->
20
21## Description
22
23Lists all the nodes that the Docker Swarm manager knows about. You can filter
24using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section
25for more information about available filter options.
26
27> **Note**
28>
29> This is a cluster management command, and must be executed on a swarm
30> manager node. To learn about managers and workers, refer to the
31> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
32> documentation.
33
34## Examples
35
36```console
37$ docker node ls
38
39ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
401bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
4138ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active
42e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
43```
44
45> **Note**
46>
47> In the above example output, there is a hidden column of `.Self` that indicates
48> if the node is the same node as the current docker daemon. A `*` (e.g.,
49> `e216jshn25ckzbvmwlnh5jr3g *`) means this node is the current docker daemon.
50
51
52### <a name="filter"></a> Filtering (--filter)
53
54The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
55than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
56
57The currently supported filters are:
58
59* [id](#id)
60* [label](#label)
61* [node.label](#nodelabel)
62* [membership](#membership)
63* [name](#name)
64* [role](#role)
65
66#### id
67
68The `id` filter matches all or part of a node's id.
69
70```console
71$ docker node ls -f id=1
72
73ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
741bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
75```
76
77#### label
78
79The `label` filter matches nodes based on engine labels and on the presence of a
80`label` alone or a `label` and a value. Engine labels are configured in
81the [daemon configuration](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file). To filter on
82Swarm `node` labels, use [`node.label` instead](#nodelabel).
83
84The following filter matches nodes with the `foo` label regardless of its value.
85
86```console
87$ docker node ls -f "label=foo"
88
89ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
901bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
91```
92
93#### node.label
94
95The `node.label` filter matches nodes based on node labels and on the presence
96of a `node.label` alone or a `node.label` and a value.
97
98The following filter updates nodes to have a `region` node label:
99
100```console
101$ docker node update --label-add region=region-a swarm-test-01
102$ docker node update --label-add region=region-a swarm-test-02
103$ docker node update --label-add region=region-b swarm-test-03
104$ docker node update --label-add region=region-b swarm-test-04
105```
106
107Show all nodes that have a `region` node label set:
108
109```console
110$ docker node ls --filter node.label=region
111
112ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
113yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 23.0.3
1142lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 23.0.3
115hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 23.0.3
116n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 23.0.3
117```
118
119Show all nodes that have a `region` node label, with value `region-a`:
120
121```console
122$ docker node ls --filter node.label=region=region-a
123
124ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
125yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 23.0.3
1262lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 23.0.3
127```
128
129#### membership
130
131The `membership` filter matches nodes based on the presence of a `membership` and a value
132`accepted` or `pending`.
133
134The following filter matches nodes with the `membership` of `accepted`.
135
136```console
137$ docker node ls -f "membership=accepted"
138
139ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1401bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
14138ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active
142```
143
144#### name
145
146The `name` filter matches on all or part of a node hostname.
147
148The following filter matches the nodes with a name equal to `swarm-master` string.
149
150```console
151$ docker node ls -f name=swarm-manager1
152
153ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
154e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
155```
156
157#### role
158
159The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`.
160
161The following filter matches nodes with the `manager` role.
162
163```console
164$ docker node ls -f "role=manager"
165
166ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
167e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
168```
169
170### <a name="format"></a> Format the output (--format)
171
172The formatting options (`--format`) pretty-prints nodes output
173using a Go template.
174
175Valid placeholders for the Go template are listed below:
176
177| Placeholder | Description |
178|------------------|-------------------------------------------------------------------------------------------------------|
179| `.ID` | Node ID |
180| `.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) |
181| `.Hostname` | Node hostname |
182| `.Status` | Node status |
183| `.Availability` | Node availability ("active", "pause", or "drain") |
184| `.ManagerStatus` | Manager status of the node |
185| `.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) |
186| `.EngineVersion` | Engine version |
187
188When using the `--format` option, the `node ls` command will either
189output the data exactly as the template declares or, when using the
190`table` directive, includes column headers as well.
191
192The following example uses a template without headers and outputs the
193`ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all
194nodes:
195
196```console
197$ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}"
198
199e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready
20035o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation
201```
202
203To list all nodes in JSON format, use the `json` directive:
204```console
205$ docker node ls --format json
206{"Availability":"Active","EngineVersion":"23.0.3","Hostname":"docker-desktop","ID":"k8f4w7qtzpj5sqzclcqafw35g","ManagerStatus":"Leader","Self":true,"Status":"Ready","TLSStatus":"Ready"}
207```
208
209## Related commands
210
211* [node demote](node_demote.md)
212* [node inspect](node_inspect.md)
213* [node promote](node_promote.md)
214* [node ps](node_ps.md)
215* [node rm](node_rm.md)
216* [node update](node_update.md)
View as plain text