From abeb7babdfb6e05760b22b931bcce84dfdcced39 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 10 Feb 2020 11:13:26 +0100 Subject: [PATCH 1/3] docs: service create: use markdown table for constraints Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/service_create.md | 50 +++++--------------- 1 file changed, 12 insertions(+), 38 deletions(-) diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index ce462632eb..fe0202c3c9 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -671,44 +671,18 @@ constraint expressions. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
node attributematchesexample
node.idNode IDnode.id==2ivku8v2gvtg4
node.hostnameNode hostnamenode.hostname!=node-2
node.roleNode rolenode.role==manager
node.labelsuser defined node labelsnode.labels.security==high
engine.labelsDocker Engine's labelsengine.labels.operatingsystem==ubuntu 14.04
+node attribute | matches | example +-------------------|--------------------------|----------------------------------------------- +`node.id` | Node ID | `node.id==2ivku8v2gvtg4` +`node.hostname` | Node hostname | `node.hostname!=node-2` +`node.role` | Node role | `node.role==manager` +`node.labels` | User-defined node labels | `node.labels.security==high` +`engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` -`engine.labels` apply to Docker Engine labels like operating system, -drivers, etc. Swarm administrators add `node.labels` for operational purposes by -using the [`docker node update`](node_update.md) command. +`engine.labels` apply to Docker Engine labels like operating system, drivers, +etc. Swarm administrators add `node.labels` for operational purposes by using +the [`docker node update`](node_update.md) command. For example, the following limits tasks for the redis service to nodes where the node type label equals queue: @@ -716,7 +690,7 @@ node type label equals queue: ```bash $ docker service create \ --name redis_2 \ - --constraint 'node.labels.type == queue' \ + --constraint node.labels.type==queue \ redis:3.0.6 ``` @@ -730,7 +704,7 @@ of datacenters or availability zones. The example below illustrates this: $ docker service create \ --replicas 9 \ --name redis_2 \ - --placement-pref 'spread=node.labels.datacenter' \ + --placement-pref spread=node.labels.datacenter \ redis:3.0.6 ``` From b059c93c9211a0bcc8aea0ffdea1f591aa0d853a Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 10 Feb 2020 11:16:22 +0100 Subject: [PATCH 2/3] docs: service create: document non-matching/exclude constraints Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/service_create.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index fe0202c3c9..cb43334a8a 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -667,7 +667,8 @@ $ docker service create \ ### Specify service constraints (--constraint) You can limit the set of nodes where a task can be scheduled by defining -constraint expressions. Multiple constraints find nodes that satisfy every +constraint expressions. Constraint expressions can either use a _match_ (`==`) +or _exclude_ (`!=`) rule. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows: From f26e9a3a61dc2f4e6b78627fb96ec31e3ccc914f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 10 Feb 2020 11:37:38 +0100 Subject: [PATCH 3/3] docs: service create: document os/arch constraints and more examples Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/service_create.md | 51 +++++++++++++++++--- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index cb43334a8a..61704397f2 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -672,13 +672,15 @@ or _exclude_ (`!=`) rule. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows: -node attribute | matches | example --------------------|--------------------------|----------------------------------------------- -`node.id` | Node ID | `node.id==2ivku8v2gvtg4` -`node.hostname` | Node hostname | `node.hostname!=node-2` -`node.role` | Node role | `node.role==manager` -`node.labels` | User-defined node labels | `node.labels.security==high` -`engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` +node attribute | matches | example +---------------------|--------------------------------|----------------------------------------------- +`node.id` | Node ID | `node.id==2ivku8v2gvtg4` +`node.hostname` | Node hostname | `node.hostname!=node-2` +`node.role` | Node role (`manager`/`worker`) | `node.role==manager` +`node.platform.os` | Node operating system | `node.platform.os==windows` +`node.platform.arch` | Node architecture | `node.platform.arch==x86_64` +`node.labels` | User-defined node labels | `node.labels.security==high` +`engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` `engine.labels` apply to Docker Engine labels like operating system, drivers, @@ -691,10 +693,45 @@ node type label equals queue: ```bash $ docker service create \ --name redis_2 \ + --constraint node.platform.os==linux \ --constraint node.labels.type==queue \ redis:3.0.6 ``` +If the service constraints exclude all nodes in the cluster, a message is printed +that no suitable node is found, but the scheduler will start a reconciliation +loop and deploy the service once a suitable node becomes available. + +In the example below, no node satisfying the constraint was found, causing the +service to not reconcile with the desired state: + +```bash +$ docker service create \ + --name web \ + --constraint node.labels.region==east \ + nginx:alpine + +lx1wrhhpmbbu0wuk0ybws30bc +overall progress: 0 out of 1 tasks +1/1: no suitable node (scheduling constraints not satisfied on 5 nodes) + +$ docker service ls +ID NAME MODE REPLICAS IMAGE PORTS +b6lww17hrr4e web replicated 0/1 nginx:alpine +``` + +After adding the `region=east` label to a node in the cluster, the service +reconciles, and the desired number of replicas are deployed: + +```bash +$ docker node update --label-add region=east yswe2dm4c5fdgtsrli1e8ya5l +yswe2dm4c5fdgtsrli1e8ya5l + +$ docker service ls +ID NAME MODE REPLICAS IMAGE PORTS +b6lww17hrr4e web replicated 1/1 nginx:alpine +``` + ### Specify service placement preferences (--placement-pref) You can set up the service to divide tasks evenly over different categories of