docs: service create: document os/arch constraints and more examples
@@ -673,10 +673,12 @@ 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.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`
@@ -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
