forked from docker/docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocker_node_ls.yaml
More file actions
248 lines (196 loc) · 9.33 KB
/
Copy pathdocker_node_ls.yaml
File metadata and controls
248 lines (196 loc) · 9.33 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
command: docker node ls
aliases: docker node ls, docker node list
short: List nodes in the swarm
long: |-
Lists all the nodes that the Docker Swarm manager knows about. You can filter
using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section
for more information about available filter options.
> **Note**
>
> This is a cluster management command, and must be executed on a swarm
> manager node. To learn about managers and workers, refer to the
> [Swarm mode section](/engine/swarm/) in the
> documentation.
usage: docker node ls [OPTIONS]
pname: docker node
plink: docker_node.yaml
options:
- option: filter
shorthand: f
value_type: filter
description: Filter output based on conditions provided
details_url: '#filter'
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
description: |-
Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates
details_url: '#format'
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Only display IDs
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: help
value_type: bool
default_value: "false"
description: Print usage
deprecated: false
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
```console
$ 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 (--filter) {#filter}
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](#id)
* [label](#label)
* [node.label](#nodelabel)
* [membership](#membership)
* [name](#name)
* [role](#role)
#### id
The `id` filter matches all or part of a node's id.
```console
$ 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. Engine labels are configured in
the [daemon configuration](/reference/cli/dockerd/#daemon-configuration-file). To filter on
Swarm `node` labels, use [`node.label` instead](#nodelabel).
The following filter matches nodes with the `foo` label regardless of its value.
```console
$ docker node ls -f "label=foo"
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
```
#### node.label
The `node.label` filter matches nodes based on node labels and on the presence
of a `node.label` alone or a `node.label` and a value.
The following filter updates nodes to have a `region` node label:
```console
$ docker node update --label-add region=region-a swarm-test-01
$ docker node update --label-add region=region-a swarm-test-02
$ docker node update --label-add region=region-b swarm-test-03
$ docker node update --label-add region=region-b swarm-test-04
```
Show all nodes that have a `region` node label set:
```console
$ docker node ls --filter node.label=region
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 23.0.3
2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 23.0.3
hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 23.0.3
n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 23.0.3
```
Show all nodes that have a `region` node label, with value `region-a`:
```console
$ docker node ls --filter node.label=region=region-a
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 23.0.3
2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 23.0.3
```
#### 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`.
```console
$ 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.
```console
$ 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.
```console
$ docker node ls -f "role=manager"
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
```
### Format the output (--format) {#format}
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) |
| `.EngineVersion` | Engine version |
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:
```console
$ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}"
e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready
35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation
```
To list all nodes in JSON format, use the `json` directive:
```console
$ docker node ls --format json
{"Availability":"Active","EngineVersion":"23.0.3","Hostname":"docker-desktop","ID":"k8f4w7qtzpj5sqzclcqafw35g","ManagerStatus":"Leader","Self":true,"Status":"Ready","TLSStatus":"Ready"}
```
deprecated: false
hidden: false
min_api_version: "1.24"
experimental: false
experimentalcli: false
kubernetes: false
swarm: true