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
|
<h1>docker node ls</h1> <p><br></p> <p>List nodes in the swarm</p> <p><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="This command works with the Swarm orchestrator.">Swarm</span> This command works with the Swarm orchestrator.</p> <h2 id="usage">Usage</h2> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls [OPTIONS]
</pre></div> <p>Refer to the <a href="#options">options section</a> for an overview of available <a href="#options"><code class="language-plaintext highlighter-rouge">OPTIONS</code></a> for this command.</p> <h2 id="description">Description</h2> <p name="extended-description">Lists all the nodes that the Docker Swarm manager knows about. You can filter using the <code class="language-plaintext highlighter-rouge">-f</code> or <code class="language-plaintext highlighter-rouge">--filter</code> flag. Refer to the <a href="#filtering">filtering</a> section for more information about available filter options.</p> <blockquote> <p><strong>Note</strong></p> <p>This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the <a href="../../../swarm/index">Swarm mode section</a> in the documentation.</p> </blockquote> <p>For example uses of this command, refer to the <a href="#examples">examples section</a> below.</p> <h2 id="options">Options</h2> <table> <thead> <tr> <td>Name, shorthand</td> <td>Default</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td>
<code class="language-plaintext highlighter-rouge">--filter</code> , <code class="language-plaintext highlighter-rouge">-f</code>
</td> <td></td> <td>Filter output based on conditions provided</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--format</code></td> <td></td> <td>Pretty-print nodes using a Go template</td> </tr> <tr> <td>
<code class="language-plaintext highlighter-rouge">--quiet</code> , <code class="language-plaintext highlighter-rouge">-q</code>
</td> <td></td> <td>Only display IDs</td> </tr> </tbody> </table> <h2 id="examples">Examples</h2> <div class="highlight"><pre class="highlight" data-language="">$ 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
</pre></div> <blockquote> <p><strong>Note</strong></p> <p>In the above example output, there is a hidden column of <code class="language-plaintext highlighter-rouge">.Self</code> that indicates if the node is the same node as the current docker daemon. A <code class="language-plaintext highlighter-rouge">*</code> (e.g., <code class="language-plaintext highlighter-rouge">e216jshn25ckzbvmwlnh5jr3g *</code>) means this node is the current docker daemon.</p> </blockquote> <h3 id="filtering">Filtering</h3> <p>The filtering flag (<code class="language-plaintext highlighter-rouge">-f</code> or <code class="language-plaintext highlighter-rouge">--filter</code>) format is of “key=value”. If there is more than one filter, then pass multiple flags (e.g., <code class="language-plaintext highlighter-rouge">--filter "foo=bar" --filter "bif=baz"</code>)</p> <p>The currently supported filters are:</p> <ul> <li><a href="#id">id</a></li> <li><a href="#label">label</a></li> <li><a href="#nodelabel">node.label</a></li> <li><a href="#membership">membership</a></li> <li><a href="#name">name</a></li> <li><a href="#role">role</a></li> </ul> <h4 id="id">id</h4> <p>The <code class="language-plaintext highlighter-rouge">id</code> filter matches all or part of a node’s id.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls -f id=1
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
</pre></div> <h4 id="label">label</h4> <p>The <code class="language-plaintext highlighter-rouge">label</code> filter matches nodes based on engine labels and on the presence of a <code class="language-plaintext highlighter-rouge">label</code> alone or a <code class="language-plaintext highlighter-rouge">label</code> and a value. Engine labels are configured in the <a href="../dockerd/index#daemon-configuration-file">daemon configuration</a>. To filter on Swarm <code class="language-plaintext highlighter-rouge">node</code> labels, use <a href="#nodelabel"><code class="language-plaintext highlighter-rouge">node.label</code> instead</a>.</p> <p>The following filter matches nodes with the <code class="language-plaintext highlighter-rouge">foo</code> label regardless of its value.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls -f "label=foo"
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
</pre></div> <h4 id="nodelabel">node.label</h4> <p>The <code class="language-plaintext highlighter-rouge">node.label</code> filter matches nodes based on node labels and on the presence of a <code class="language-plaintext highlighter-rouge">node.label</code> alone or a <code class="language-plaintext highlighter-rouge">node.label</code> and a value.</p> <p>The following filter updates nodes to have a <code class="language-plaintext highlighter-rouge">region</code> node label:</p> <div class="highlight"><pre class="highlight" data-language="">$ 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
</pre></div> <p>Show all nodes that have a <code class="language-plaintext highlighter-rouge">region</code> node label set:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls --filter node.label=region
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2
2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2
hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 20.10.2
n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 20.10.2
</pre></div> <p>Show all nodes that have a <code class="language-plaintext highlighter-rouge">region</code> node label, with value <code class="language-plaintext highlighter-rouge">region-a</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls --filter node.label=region=region-a
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2
2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2
</pre></div> <h4 id="membership">membership</h4> <p>The <code class="language-plaintext highlighter-rouge">membership</code> filter matches nodes based on the presence of a <code class="language-plaintext highlighter-rouge">membership</code> and a value <code class="language-plaintext highlighter-rouge">accepted</code> or <code class="language-plaintext highlighter-rouge">pending</code>.</p> <p>The following filter matches nodes with the <code class="language-plaintext highlighter-rouge">membership</code> of <code class="language-plaintext highlighter-rouge">accepted</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls -f "membership=accepted"
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active
38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active
</pre></div> <h4 id="name">name</h4> <p>The <code class="language-plaintext highlighter-rouge">name</code> filter matches on all or part of a node hostname.</p> <p>The following filter matches the nodes with a name equal to <code class="language-plaintext highlighter-rouge">swarm-master</code> string.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls -f name=swarm-manager1
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
</pre></div> <h4 id="role">role</h4> <p>The <code class="language-plaintext highlighter-rouge">role</code> filter matches nodes based on the presence of a <code class="language-plaintext highlighter-rouge">role</code> and a value <code class="language-plaintext highlighter-rouge">worker</code> or <code class="language-plaintext highlighter-rouge">manager</code>.</p> <p>The following filter matches nodes with the <code class="language-plaintext highlighter-rouge">manager</code> role.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls -f "role=manager"
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader
</pre></div> <h3 id="formatting">Formatting</h3> <p>The formatting options (<code class="language-plaintext highlighter-rouge">--format</code>) pretty-prints nodes output using a Go template.</p> <p>Valid placeholders for the Go template are listed below:</p> <table> <thead> <tr> <th>Placeholder</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">.ID</code></td> <td>Node ID</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.Self</code></td> <td>Node of the daemon (<code class="language-plaintext highlighter-rouge">true/false</code>, <code class="language-plaintext highlighter-rouge">true</code>indicates that the node is the same as current docker daemon)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.Hostname</code></td> <td>Node hostname</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.Status</code></td> <td>Node status</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.Availability</code></td> <td>Node availability (“active”, “pause”, or “drain”)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.ManagerStatus</code></td> <td>Manager status of the node</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.TLSStatus</code></td> <td>TLS status of the node (“Ready”, or “Needs Rotation” has TLS certificate signed by an old CA)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">.EngineVersion</code></td> <td>Engine version</td> </tr> </tbody> </table> <p>When using the <code class="language-plaintext highlighter-rouge">--format</code> option, the <code class="language-plaintext highlighter-rouge">node ls</code> command will either output the data exactly as the template declares or, when using the <code class="language-plaintext highlighter-rouge">table</code> directive, includes column headers as well.</p> <p>The following example uses a template without headers and outputs the <code class="language-plaintext highlighter-rouge">ID</code>, <code class="language-plaintext highlighter-rouge">Hostname</code>, and <code class="language-plaintext highlighter-rouge">TLS Status</code> entries separated by a colon (<code class="language-plaintext highlighter-rouge">:</code>) for all nodes:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}"
e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready
35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation
</pre></div> <h2 id="parent-command">Parent command</h2> <table> <thead> <tr> <th style="text-align: left">Command</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><a href="../node/index">docker node</a></td> <td style="text-align: left">Manage Swarm nodes</td> </tr> </tbody> </table> <h2 id="related-commands">Related commands</h2> <table> <thead> <tr> <td>Command</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td><a href="../node_demote/index">docker node demote</a></td> <td>Demote one or more nodes from manager in the swarm</td> </tr> <tr> <td><a href="../node_inspect/index">docker node inspect</a></td> <td>Display detailed information on one or more nodes</td> </tr> <tr> <td><a href="index">docker node ls</a></td> <td>List nodes in the swarm</td> </tr> <tr> <td><a href="../node_promote/index">docker node promote</a></td> <td>Promote one or more nodes to manager in the swarm</td> </tr> <tr> <td><a href="../node_ps/index">docker node ps</a></td> <td>List tasks running on one or more nodes, defaults to current node</td> </tr> <tr> <td><a href="../node_rm/index">docker node rm</a></td> <td>Remove one or more nodes from the swarm</td> </tr> <tr> <td><a href="../node_update/index">docker node update</a></td> <td>Update a node</td> </tr> </tbody> </table> <div class="_attribution">
<p class="_attribution-p">
© 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
<a href="https://docs.docker.com/engine/reference/commandline/node_ls/" class="_attribution-link">https://docs.docker.com/engine/reference/commandline/node_ls/</a>
</p>
</div>
|
