github.com/khulnasoft/cli@v0.0.0-20240402070845-01bcad7beefa/docs/reference/commandline/node_ls.md (about) 1 # node ls 2 3 <!---MARKER_GEN_START--> 4 List 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 23 Lists all the nodes that the Docker Swarm manager knows about. You can filter 24 using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section 25 for 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 39 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 40 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active 41 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active 42 e216jshn25ckzbvmwlnh5jr3g * 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 54 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more 55 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) 56 57 The 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 68 The `id` filter matches all or part of a node's id. 69 70 ```console 71 $ docker node ls -f id=1 72 73 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 74 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active 75 ``` 76 77 #### label 78 79 The `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 81 the [daemon configuration](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file). To filter on 82 Swarm `node` labels, use [`node.label` instead](#nodelabel). 83 84 The following filter matches nodes with the `foo` label regardless of its value. 85 86 ```console 87 $ docker node ls -f "label=foo" 88 89 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 90 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active 91 ``` 92 93 #### node.label 94 95 The `node.label` filter matches nodes based on node labels and on the presence 96 of a `node.label` alone or a `node.label` and a value. 97 98 The 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 107 Show all nodes that have a `region` node label set: 108 109 ```console 110 $ docker node ls --filter node.label=region 111 112 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION 113 yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 23.0.3 114 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 23.0.3 115 hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 23.0.3 116 n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 23.0.3 117 ``` 118 119 Show 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 124 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION 125 yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 23.0.3 126 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 23.0.3 127 ``` 128 129 #### membership 130 131 The `membership` filter matches nodes based on the presence of a `membership` and a value 132 `accepted` or `pending`. 133 134 The following filter matches nodes with the `membership` of `accepted`. 135 136 ```console 137 $ docker node ls -f "membership=accepted" 138 139 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 140 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active 141 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active 142 ``` 143 144 #### name 145 146 The `name` filter matches on all or part of a node hostname. 147 148 The 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 153 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 154 e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader 155 ``` 156 157 #### role 158 159 The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`. 160 161 The following filter matches nodes with the `manager` role. 162 163 ```console 164 $ docker node ls -f "role=manager" 165 166 ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 167 e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader 168 ``` 169 170 ### <a name="format"></a> Format the output (--format) 171 172 The formatting options (`--format`) pretty-prints nodes output 173 using a Go template. 174 175 Valid 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 188 When using the `--format` option, the `node ls` command will either 189 output the data exactly as the template declares or, when using the 190 `table` directive, includes column headers as well. 191 192 The following example uses a template without headers and outputs the 193 `ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all 194 nodes: 195 196 ```console 197 $ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}" 198 199 e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready 200 35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation 201 ``` 202 203 To 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)