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