new repository

1 files changed, 64 insertions, 0 deletions

diff --git a/devdocs/docker/engine%2Fswarm%2Fmanage-nodes%2Findex.html b/devdocs/docker/engine%2Fswarm%2Fmanage-nodes%2Findex.html
new file mode 100644
index 00000000..41b8ef5a
--- /dev/null
+++ b/devdocs/docker/engine%2Fswarm%2Fmanage-nodes%2Findex.html
@@ -0,0 +1,64 @@
+<h1>Manage nodes in a swarm</h1>
+
+<p>As part of the swarm management lifecycle, you may need to view or update a node as follows:</p> <ul> <li><a href="#list-nodes">list nodes in the swarm</a></li> <li><a href="#inspect-an-individual-node">inspect an individual node</a></li> <li><a href="#update-a-node">update a node</a></li> <li><a href="#leave-the-swarm">leave the swarm</a></li> </ul> <h2 id="list-nodes">List nodes</h2> <p>To view a list of nodes in the swarm run <code class="language-plaintext highlighter-rouge">docker node ls</code> from a manager node:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node ls
+
+ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
+46aqrk4e473hjbt745z53cr3t    node-5    Ready   Active        Reachable
+61pi3d91s0w3b90ijw3deeb2q    node-4    Ready   Active        Reachable
+a5b2m3oghd48m8eu391pefq5u    node-3    Ready   Active
+e7p8btxeu3ioshyuj6lxiv6g0    node-2    Ready   Active
+ehkv3bcimagdese79dn78otj5 *  node-1    Ready   Active        Leader
+</pre></div> <p>The <code class="language-plaintext highlighter-rouge">AVAILABILITY</code> column shows whether or not the scheduler can assign tasks to the node:</p> <ul> <li>
+<code class="language-plaintext highlighter-rouge">Active</code> means that the scheduler can assign tasks to the node.</li> <li>
+<code class="language-plaintext highlighter-rouge">Pause</code> means the scheduler doesn’t assign new tasks to the node, but existing tasks remain running.</li> <li>
+<code class="language-plaintext highlighter-rouge">Drain</code> means the scheduler doesn’t assign new tasks to the node. The scheduler shuts down any existing tasks and schedules them on an available node.</li> </ul> <p>The <code class="language-plaintext highlighter-rouge">MANAGER STATUS</code> column shows node participation in the Raft consensus:</p> <ul> <li>No value indicates a worker node that does not participate in swarm management.</li> <li>
+<code class="language-plaintext highlighter-rouge">Leader</code> means the node is the primary manager node that makes all swarm management and orchestration decisions for the swarm.</li> <li>
+<code class="language-plaintext highlighter-rouge">Reachable</code> means the node is a manager node participating in the Raft consensus quorum. If the leader node becomes unavailable, the node is eligible for election as the new leader.</li> <li>
+<code class="language-plaintext highlighter-rouge">Unavailable</code> means the node is a manager that can’t communicate with other managers. If a manager node becomes unavailable, you should either join a new manager node to the swarm or promote a worker node to be a manager.</li> </ul> <p>For more information on swarm administration refer to the <a href="../admin_guide/index">Swarm administration guide</a>.</p> <h2 id="inspect-an-individual-node">Inspect an individual node</h2> <p>You can run <code class="language-plaintext highlighter-rouge">docker node inspect &lt;NODE-ID&gt;</code> on a manager node to view the details for an individual node. The output defaults to JSON format, but you can pass the <code class="language-plaintext highlighter-rouge">--pretty</code> flag to print the results in human-readable format. For example:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node inspect self --pretty
+
+ID:                     ehkv3bcimagdese79dn78otj5
+Hostname:               node-1
+Joined at:              2016-06-16 22:52:44.9910662 +0000 utc
+Status:
+ State:                 Ready
+ Availability:          Active
+Manager Status:
+ Address:               172.17.0.2:2377
+ Raft Status:           Reachable
+ Leader:                Yes
+Platform:
+ Operating System:      linux
+ Architecture:          x86_64
+Resources:
+ CPUs:                  2
+ Memory:                1.954 GiB
+Plugins:
+  Network:              overlay, host, bridge, overlay, null
+  Volume:               local
+Engine Version:         1.12.0-dev
+</pre></div> <h2 id="update-a-node">Update a node</h2> <p>You can modify node attributes as follows:</p> <ul> <li><a href="#change-node-availability">change node availability</a></li> <li><a href="#add-or-remove-label-metadata">add or remove label metadata</a></li> <li><a href="#promote-or-demote-a-node">change a node role</a></li> </ul> <h3 id="change-node-availability">Change node availability</h3> <p>Changing node availability lets you:</p> <ul> <li>drain a manager node so that only performs swarm management tasks and is unavailable for task assignment.</li> <li>drain a node so you can take it down for maintenance.</li> <li>pause a node so it can’t receive new tasks.</li> <li>restore unavailable or paused nodes available status.</li> </ul> <p>For example, to change a manager node to <code class="language-plaintext highlighter-rouge">Drain</code> availability:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node update --availability drain node-1
+
+node-1
+</pre></div> <p>See <a href="#list-nodes">list nodes</a> for descriptions of the different availability options.</p> <h3 id="add-or-remove-label-metadata">Add or remove label metadata</h3> <p>Node labels provide a flexible method of node organization. You can also use node labels in service constraints. Apply constraints when you create a service to limit the nodes where the scheduler assigns tasks for the service.</p> <p>Run <code class="language-plaintext highlighter-rouge">docker node update --label-add</code> on a manager node to add label metadata to a node. The <code class="language-plaintext highlighter-rouge">--label-add</code> flag supports either a <code class="language-plaintext highlighter-rouge">&lt;key&gt;</code> or a <code class="language-plaintext highlighter-rouge">&lt;key&gt;=&lt;value&gt;</code> pair.</p> <p>Pass the <code class="language-plaintext highlighter-rouge">--label-add</code> flag once for each node label you want to add:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node update --label-add foo --label-add bar=baz node-1
+
+node-1
+</pre></div> <p>The labels you set for nodes using docker node update apply only to the node entity within the swarm. Do not confuse them with the docker daemon labels for <a href="https://docs.docker.com/config/labels-custom-metadata/">dockerd</a>.</p> <p>Therefore, node labels can be used to limit critical tasks to nodes that meet certain requirements. For example, schedule only on machines where special workloads should be run, such as machines that meet <a href="https://www.pcisecuritystandards.org/">PCI-SS compliance</a>.</p> <p>A compromised worker could not compromise these special workloads because it cannot change node labels.</p> <p>Engine labels, however, are still useful because some features that do not affect secure orchestration of containers might be better off set in a decentralized manner. For instance, an engine could have a label to indicate that it has a certain type of disk device, which may not be relevant to security directly. These labels are more easily “trusted” by the swarm orchestrator.</p> <p>Refer to the <code class="language-plaintext highlighter-rouge">docker service create</code> <a href="../../reference/commandline/service_create/index">CLI reference</a> for more information about service constraints.</p> <h3 id="promote-or-demote-a-node">Promote or demote a node</h3> <p>You can promote a worker node to the manager role. This is useful when a manager node becomes unavailable or if you want to take a manager offline for maintenance. Similarly, you can demote a manager node to the worker role.</p> <blockquote> <p><strong>Note</strong>: Regardless of your reason to promote or demote a node, you must always maintain a quorum of manager nodes in the swarm. For more information refer to the <a href="../admin_guide/index">Swarm administration guide</a>.</p> </blockquote> <p>To promote a node or set of nodes, run <code class="language-plaintext highlighter-rouge">docker node promote</code> from a manager node:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node promote node-3 node-2
+
+Node node-3 promoted to a manager in the swarm.
+Node node-2 promoted to a manager in the swarm.
+</pre></div> <p>To demote a node or set of nodes, run <code class="language-plaintext highlighter-rouge">docker node demote</code> from a manager node:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node demote node-3 node-2
+
+Manager node-3 demoted in the swarm.
+Manager node-2 demoted in the swarm.
+</pre></div> <p><code class="language-plaintext highlighter-rouge">docker node promote</code> and <code class="language-plaintext highlighter-rouge">docker node demote</code> are convenience commands for <code class="language-plaintext highlighter-rouge">docker node update --role manager</code> and <code class="language-plaintext highlighter-rouge">docker node update --role worker</code> respectively.</p> <h2 id="install-plugins-on-swarm-nodes">Install plugins on swarm nodes</h2> <p>If your swarm service relies on one or more <a href="../../extend/plugin_api/index">plugins</a>, these plugins need to be available on every node where the service could potentially be deployed. You can manually install the plugin on each node or script the installation. You can also deploy the plugin in a similar way as a global service using the Docker API, by specifying a <code class="language-plaintext highlighter-rouge">PluginSpec</code> instead of a <code class="language-plaintext highlighter-rouge">ContainerSpec</code>.</p> <blockquote> <p><strong>Note</strong></p> <p>There is currently no way to deploy a plugin to a swarm using the Docker CLI or Docker Compose. In addition, it is not possible to install plugins from a private repository.</p> </blockquote> <p>The <a href="../../extend/plugin_api/index#json-specification"><code class="language-plaintext highlighter-rouge">PluginSpec</code></a> is defined by the plugin developer. To add the plugin to all Docker nodes, use the <a href="https://docs.docker.com/engine/api/v1.31/#operation/ServiceCreate"><code class="language-plaintext highlighter-rouge">service/create</code></a> API, passing the <code class="language-plaintext highlighter-rouge">PluginSpec</code> JSON defined in the <code class="language-plaintext highlighter-rouge">TaskTemplate</code>.</p> <h2 id="leave-the-swarm">Leave the swarm</h2> <p>Run the <code class="language-plaintext highlighter-rouge">docker swarm leave</code> command on a node to remove it from the swarm.</p> <p>For example to leave the swarm on a worker node:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm leave
+
+Node left the swarm.
+</pre></div> <p>When a node leaves the swarm, the Docker Engine stops running in swarm mode. The orchestrator no longer schedules tasks to the node.</p> <p>If the node is a manager node, you receive a warning about maintaining the quorum. To override the warning, pass the <code class="language-plaintext highlighter-rouge">--force</code> flag. If the last manager node leaves the swarm, the swarm becomes unavailable requiring you to take disaster recovery measures.</p> <p>For information about maintaining a quorum and disaster recovery, refer to the <a href="../admin_guide/index">Swarm administration guide</a>.</p> <p>After a node leaves the swarm, you can run the <code class="language-plaintext highlighter-rouge">docker node rm</code> command on a manager node to remove the node from the node list.</p> <p>For instance:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node rm node-2
+</pre></div> <h2 id="learn-more">Learn more</h2> <ul> <li><a href="../admin_guide/index">Swarm administration guide</a></li> <li><a href="../../reference/commandline/docker/index">Docker Engine command line reference</a></li> <li><a href="../swarm-tutorial/index">Swarm mode tutorial</a></li> </ul> 
+<p><a href="https://docs.docker.com/search/?q=guide">guide</a>, <a href="https://docs.docker.com/search/?q=swarm%20mode">swarm mode</a>, <a href="https://docs.docker.com/search/?q=node">node</a></p>
+<div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 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/swarm/manage-nodes/" class="_attribution-link">https://docs.docker.com/engine/swarm/manage-nodes/</a>
+  </p>
+</div>