0 0 Share PDF

Using constraints and labels to control the placement of containers

Article ID: KB000666


By default swarm services can run on any node in the cluster. This article explains how to use node labels and constraints to control where services run.


  • Docker swarm mode cluster
  • Docker EE Engine version CS 1.12, CS 1.13, 17.03, 17.06, 18.03


If you choose to constrain where services run, please note the following examples.

To ensure a service runs on worker nodes rather than managers, use a node.role constraint in the service definition. For example:

docker service create \
    --name nginx-workers-only \
    --constraint node.role==worker \

You can also apply one or more labels to one node or a set of nodes and then use those to constrain services. The following example applies the label region=east to a node, then creates a service that can only run on nodes with that label.

Apply label region=east to a node:

docker node update --label-add region=east worker-1

Create a service that will only run on nodes with label region=east:

docker service create \
    --name nginx-east \
    --constraint node.labels.region==east \

Create a service that will only run on nodes with label region=east and not label type=devel:

docker service create \
    --name nginx-east-no-devel \
    --constraint node.labels.region==east \
    --constraint node.labels.type!=devel \

What's Next