docs/ee/ucp/admin/configure/_site/scale-your-cluster.html

<p>Docker UCP is designed for scaling horizontally as your applications grow in
size and usage. You can add or remove nodes from the UCP cluster to make it
scale to your needs.</p>

<p><img src="../../images/scale-your-cluster-0.svg" alt="" /></p>

<p>Since UCP leverages the clustering functionality provided by Docker Engine,
you use the <a href="/engine/swarm/swarm-tutorial/add-nodes.md">docker swarm join</a>
command to add more nodes to your cluster. When joining new nodes, the UCP
services automatically start running in that node.</p>

<p>When joining a node to a cluster you can specify its role: manager or worker.</p>

<ul>
  <li>
    <p><strong>Manager nodes</strong></p>

    <p>Manager nodes are responsible for cluster management functionality and
  dispatching tasks to worker nodes. Having multiple manager nodes allows
  your cluster to be highly-available and tolerate node failures.</p>

    <p>Manager nodes also run all UCP components in a replicated way, so by adding
  additional manager nodes, you’re also making UCP highly available.
  <a href="../../ucp-architecture.md">Learn more about the UCP architecture.</a></p>
  </li>
  <li>
    <p><strong>Worker nodes</strong></p>

    <p>Worker nodes receive and execute your services and applications. Having
  multiple worker nodes allows you to scale the computing capacity of your
  cluster.</p>

    <p>When deploying Docker Trusted Registry in your cluster, you deploy it to a
  worker node.</p>
  </li>
</ul>

<h2 id="join-nodes-to-the-cluster">Join nodes to the cluster</h2>

<p>To join nodes to the cluster, go to the UCP web UI and navigate to the <strong>Nodes</strong>
page.</p>

<p><img src="../../images/scale-your-cluster-1.png" alt="" class="with-border" /></p>

<p>Click <strong>Add Node</strong> to add a new node.</p>

<p><img src="../../../images/try-ddc-3.png" alt="" class="with-border" /></p>

<ul>
  <li>Click <strong>Manager</strong> if you want to add the node as a manager.</li>
  <li>Check the <strong>Use a custom listen address</strong> option to specify the
IP address of the host that you’ll be joining to the cluster.</li>
  <li>Check the <strong>Use a custom listen address</strong> option to specify the
IP address that’s advertised to all members of the cluster for API access.</li>
</ul>

<p>Copy the displayed command, use ssh to log into the host that you want to
join to the cluster, and run the <code class="highlighter-rouge">docker swarm join</code> command on the host.</p>

<p>To add a Windows node, click <strong>Windows</strong> and follow the instructions in
<a href="join-nodes/join-windows-nodes-to-cluster.md">Join Windows worker nodes to a cluster</a>.</p>

<p>After you run the join command in the node, you can view the node in the
UCP web UI.</p>

<h2 id="remove-nodes-from-the-cluster">Remove nodes from the cluster</h2>

<ol>
  <li>If the target node is a manager, you will need to first demote the node into
a worker before proceeding with the removal:
    <ul>
      <li>From the UCP web UI, navigate to the <strong>Nodes</strong> page. Select the node you
wish to remove and switch its role to <strong>Worker</strong>, wait until the operation
completes, and confirm that the node is no longer a manager.</li>
      <li>From the CLI, perform <code class="highlighter-rouge">docker node ls</code> and identify the nodeID or hostname
of the target node. Then, run <code class="highlighter-rouge">docker node demote &lt;nodeID or hostname&gt;</code>.</li>
    </ul>
  </li>
  <li>
    <p>If the status of the worker node is <code class="highlighter-rouge">Ready</code>, you’ll need to manually force
the node to leave the cluster. To do this, connect to the target node through
SSH and run <code class="highlighter-rouge">docker swarm leave --force</code> directly against the local docker
engine.</p>

    <blockquote>
      <p>Loss of quorum</p>

      <p>Do not perform this step if the node is still a manager, as
this may cause loss of quorum.</p>
    </blockquote>
  </li>
  <li>Now that the status of the node is reported as <code class="highlighter-rouge">Down</code>, you may remove the
node:
    <ul>
      <li>From the UCP web UI, browse to the <strong>Nodes</strong> page and select the node.
 In the details pane, click <strong>Actions</strong> and select <strong>Remove</strong>.
 Click <strong>Confirm</strong> when you’re prompted.</li>
      <li>From the CLI, perform <code class="highlighter-rouge">docker node rm &lt;nodeID or hostname&gt;</code>.</li>
    </ul>
  </li>
</ol>

<h2 id="pause-and-drain-nodes">Pause and drain nodes</h2>

<p>Once a node is part of the cluster you can change its role making a manager
node into a worker and vice versa. You can also configure the node availability
so that it is:</p>

<ul>
  <li>Active: the node can receive and execute tasks.</li>
  <li>Paused: the node continues running existing tasks, but doesn’t receive new ones.</li>
  <li>Drained: the node won’t receive new tasks. Existing tasks are stopped and
replica tasks are launched in active nodes.</li>
</ul>

<p>In the UCP web UI, browse to the <strong>Nodes</strong> page and select the node. In the details pane, click the <strong>Configure</strong> to open the <strong>Edit Node</strong> page.</p>

<p><img src="../../images/scale-your-cluster-3.png" alt="" class="with-border" /></p>

<p>If you’re load-balancing user requests to UCP across multiple manager nodes,
when demoting those nodes into workers, don’t forget to remove them from your
load-balancing pool.</p>

<h2 id="use-the-cli-to-scale-your-cluster">Use the CLI to scale your cluster</h2>

<p>You can also use the command line to do all of the above operations. To get the
join token, run the following command on a manager node:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker swarm join-token worker
</code></pre></div></div>

<p>If you want to add a new manager node instead of a worker node, use
<code class="highlighter-rouge">docker swarm join-token manager</code> instead. If you want to use a custom listen
address, add the <code class="highlighter-rouge">--listen-addr</code> arg:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker swarm join <span class="se">\</span>
    <span class="nt">--token</span> SWMTKN-1-2o5ra9t7022neymg4u15f3jjfh0qh3yof817nunoioxa9i7lsp-dkmt01ebwp2m0wce1u31h6lmj <span class="se">\</span>
    <span class="nt">--listen-addr</span> 234.234.234.234 <span class="se">\</span>
    192.168.99.100:2377
</code></pre></div></div>

<p>Once your node is added, you can see it by running <code class="highlighter-rouge">docker node ls</code> on a manager:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker node <span class="nb">ls</span>
</code></pre></div></div>

<p>To change the node’s availability, use:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker node update <span class="nt">--availability</span> drain node2
</code></pre></div></div>

<p>You can set the availability to <code class="highlighter-rouge">active</code>, <code class="highlighter-rouge">pause</code>, or <code class="highlighter-rouge">drain</code>.</p>

<p>To remove the node, use:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker node rm &lt;node-hostname&gt;
</code></pre></div></div>

<h2 id="where-to-go-next">Where to go next</h2>

<ul>
  <li><a href="use-your-own-tls-certificates.md">Use your own TLS certificates</a></li>
  <li><a href="join-nodes/index.md">Set up high availability</a></li>
</ul>