docs/ee/ucp/admin/configure/_site/add-labels-to-cluster-nodes.html

<p>With Docker UCP, you can add labels to your nodes. Labels are metadata that
describe the node, like its role (development, QA, production), its region
(US, EU, APAC), or the kind of disk (hdd, ssd). Once you have labeled your
nodes, you can add deployment constraints to your services, to ensure they
are scheduled on a node with a specific label.</p>

<p>For example, you can apply labels based on their role in the development
lifecycle, or the hardware resources they have.</p>

<p><img src="../../images/add-labels-to-cluster-nodes-1.svg" alt="" /></p>

<p>Don’t create labels for authorization and permissions to resources.
Instead, use resource sets, either UCP collections or Kubernetes namespaces,
to organize access to your cluster.
<a href="../../authorization/group-resources.md">Learn about managing access with resource sets</a>.</p>

<h2 id="apply-labels-to-a-node">Apply labels to a node</h2>

<p>In this example we’ll apply the <code class="highlighter-rouge">ssd</code> label to a node. Then we’ll deploy
a service with a deployment constraint to make sure the service is always
scheduled to run on a node that has the <code class="highlighter-rouge">ssd</code> label.</p>

<p>Log in with administrator credentials in the UCP web UI, navigate to the
<strong>Nodes</strong> page, and choose the node you want to apply labels to. In the
details pane, click <strong>Configure</strong>.</p>

<p>In the <strong>Edit Node</strong> page, scroll down to the <strong>Labels</strong> section.</p>

<p>Click <strong>Add Label</strong>, and add a label with the key <code class="highlighter-rouge">disk</code> and a value of <code class="highlighter-rouge">ssd</code>.</p>

<p><img src="../../images/add-labels-to-cluster-nodes-2.png" alt="" class="with-border" /></p>

<p>Click <strong>Save</strong> and dismiss the <strong>Edit Node</strong> page. In the node’s details
pane, click <strong>Labels</strong> to view the labels that are applied to the node.</p>

<p>You can also do this from the CLI by running:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker node update <span class="nt">--label-add</span> &lt;key&gt;<span class="o">=</span>&lt;value&gt; &lt;node-id&gt;
</code></pre></div></div>

<h2 id="deploy-a-service-with-constraints">Deploy a service with constraints</h2>

<p>When deploying a service, you can specify constraints, so that the service gets
scheduled only on a node that has a label that fulfills all of the constraints
you specify.</p>

<p>In this example, when users deploy a service, they can add a constraint for the
service to be scheduled only on nodes that have SSD storage:
<code class="highlighter-rouge">node.labels.disk == ssd</code>.</p>

<p>Navigate to the <strong>Stacks</strong> page. Name the new stack “wordpress”, and in the
<strong>Mode</strong> dropdown, check <strong>Swarm Services</strong>.</p>

<p>In the <strong>docker-compose.yml</strong> editor, paste the following stack file.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>version: "3.1"

services:
  db:
    image: mysql:5.7
    deploy:
      placement:
        constraints:
          - node.labels.disk == ssd
      restart_policy:
        condition: on-failure
    networks:
      - wordpress-net
    environment:
      MYSQL_ROOT_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
  wordpress:
    depends_on:
      - db
    image: wordpress:latest
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.labels.disk == ssd
      restart_policy:
        condition: on-failure
        max_attempts: 3
    networks:
      - wordpress-net
    ports:
      - "8000:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_PASSWORD: wordpress

networks:
  wordpress-net:
</code></pre></div></div>

<p>Click <strong>Create</strong> to deploy the stack, and when the stack deploys,
click <strong>Done</strong>.</p>

<p><img src="../../images/use-constraints-in-stack-deployment.png" alt="" /></p>

<p>Navigate to the <strong>Nodes</strong> page, and click the node that has the
<code class="highlighter-rouge">disk</code> label. In the details pane, click the <strong>Inspect Resource</strong>
dropdown and select <strong>Containers</strong>.</p>

<p><img src="../../images/use-constraints-in-stack-deployment-2.png" alt="" /></p>

<p>Dismiss the filter and navigate to the <strong>Nodes</strong> page. Click a node that
doesn’t have the <code class="highlighter-rouge">disk</code> label. In the details pane, click the
<strong>Inspect Resource</strong> dropdown and select <strong>Containers</strong>. There are no 
WordPress containers scheduled on the node. Dismiss the filter.</p>

<h2 id="add-a-constraint-to-a-service-by-using-the-ucp-web-ui">Add a constraint to a service by using the UCP web UI</h2>

<p>You can declare the deployment constraints in your docker-compose.yml file or
when you’re creating a stack. Also, you can apply them when you’re creating
a service.</p>

<p>To check if a service has deployment constraints, navigate to the 
<strong>Services</strong> page and choose the service that you want to check.
In the details pane, click <strong>Constraints</strong> to list the constraint labels.</p>

<p>To edit the constraints on the service, click <strong>Configure</strong> and select
<strong>Details</strong> to open the <strong>Update Service</strong> page. Click <strong>Scheduling</strong> to
view the constraints.</p>

<p><img src="../../images/add-constraint-to-service.png" alt="" /></p>

<p>You can add or remove deployment constraints on this page.</p>

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

<ul>
  <li><a href="store-logs-in-an-external-system.md">Store logs in an external system</a></li>
</ul>