github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/constraint.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "constraint Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-constraint" 5 description: |- 6 The "constraint" stanza allows restricting the set of eligible nodes. 7 Constraints may filter on attributes or metadata. Additionally constraints may 8 be specified at the job, group, or task levels for ultimate flexibility. 9 --- 10 11 # `constraint` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>job -> **constraint**</code> 18 <br> 19 <code>job -> group -> **constraint**</code> 20 <br> 21 <code>job -> group -> task -> **constraint**</code> 22 </td> 23 </tr> 24 </table> 25 26 The `constraint` allows restricting the set of eligible nodes. Constraints may 27 filter on [attributes][interpolation] or [client metadata][client-meta]. 28 Additionally constraints may be specified at the [job][job], [group][group], or 29 [task][task] levels for ultimate flexibility. 30 31 ```hcl 32 job "docs" { 33 # All tasks in this job must run on linux. 34 constraint { 35 attribute = "${attr.kernel.name}" 36 value = "linux" 37 } 38 39 group "example" { 40 # All groups in this job should be scheduled on different hosts. 41 constraint { 42 operator = "distinct_hosts" 43 value = "true" 44 } 45 46 task "server" { 47 # All tasks must run where "my_custom_value" is greater than 3. 48 constraint { 49 attribute = "${meta.my_custom_value}" 50 operator = ">" 51 value = "3" 52 } 53 } 54 } 55 } 56 ``` 57 58 Placing constraints at both the job level and at the group level is redundant 59 since constraints are applied hierarchically. The job constraints will affect 60 all groups (and tasks) in the job. 61 62 ## `constraint` Parameters 63 64 - `attribute` `(string: "")` - Specifies the name or reference of the attribute 65 to examine for the constraint. This can be any of the [Nomad interpolated 66 values](/docs/runtime/interpolation.html#interpreted_node_vars). 67 68 - `operator` `(string: "=")` - Specifies the comparison operator. The ordering is 69 compared lexically. Possible values include: 70 71 ```text 72 = 73 != 74 > 75 >= 76 < 77 <= 78 distinct_hosts 79 distinct_property 80 regexp 81 set_contains 82 version 83 ``` 84 85 For a detailed explanation of these values and their behavior, please see 86 the [operator values section](#operator-values). 87 88 - `value` `(string: "")` - Specifies the value to compare the attribute against 89 using the specified operation. This can be a literal value, another attribute, 90 or any [Nomad interpolated 91 values](/docs/runtime/interpolation.html#interpreted_node_vars). 92 93 ### `operator` Values 94 95 This section details the specific values for the "operator" parameter in the 96 Nomad job specification for constraints. The operator is always specified as a 97 string, but the string can take on different values which change the behavior of 98 the overall constraint evaluation. 99 100 ```hcl 101 constraint { 102 operator = "..." 103 } 104 ``` 105 106 - `"distinct_hosts"` - Instructs the scheduler to not co-locate any groups on 107 the same machine. When specified as a job constraint, it applies to all groups 108 in the job. When specified as a group constraint, the effect is constrained to 109 that group. This constraint can not be specified at the task level. Note that 110 the `attribute` parameter should be omitted when using this constraint. 111 112 ```hcl 113 constraint { 114 operator = "distinct_hosts" 115 value = "true" 116 } 117 ``` 118 119 The constraint may also be specified as follows for a more compact 120 representation: 121 122 ```hcl 123 constraint { 124 distinct_hosts = true 125 } 126 ``` 127 128 - `"distinct_property"` - Instructs the scheduler to select nodes that have a 129 distinct value of the specified property. The `value` parameter specifies how 130 many allocations are allowed to share the value of a property. The `value` 131 must be 1 or greater and if omitted, defaults to 1. When specified as a job 132 constraint, it applies to all groups in the job. When specified as a group 133 constraint, the effect is constrained to that group. This constraint can not 134 be specified at the task level. 135 136 ```hcl 137 constraint { 138 operator = "distinct_property" 139 attribute = "${meta.rack}" 140 value = "3" 141 } 142 ``` 143 144 The constraint may also be specified as follows for a more compact 145 representation: 146 147 ```hcl 148 constraint { 149 distinct_property = "${meta.rack}" 150 value = "3" 151 } 152 ``` 153 154 - `"regexp"` - Specifies a regular expression constraint against the attribute. 155 The syntax of the regular expressions accepted is the same general syntax used 156 by Perl, Python, and many other languages. More precisely, it is the syntax 157 accepted by RE2 and described at in the [Google RE2 158 syntax](https://golang.org/s/re2syntax). 159 160 ```hcl 161 constraint { 162 attribute = "..." 163 operator = "regexp" 164 value = "[a-z0-9]" 165 } 166 ``` 167 168 - `"set_contains"` - Specifies a contains constraint against the attribute. The 169 attribute and the list being checked are split using commas. This will check 170 that the given attribute contains **all** of the specified elements. 171 172 ```hcl 173 constraint { 174 attribute = "..." 175 operator = "set_contains" 176 value = "a,b,c" 177 } 178 ``` 179 180 - `"version"` - Specifies a version constraint against the attribute. This 181 supports a comma-separated list of constraints, including the pessimistic 182 operator. For more examples please see the [go-version 183 repository](https://github.com/hashicorp/go-version) for more specific 184 examples. 185 186 ```hcl 187 constraint { 188 attribute = "..." 189 operator = "version" 190 value = ">= 0.1.0, < 0.2" 191 } 192 ``` 193 194 ## `constraint` Examples 195 196 The following examples only show the `constraint` stanzas. Remember that the 197 `constraint` stanza is only valid in the placements listed above. 198 199 ### Kernel Data 200 201 This example restricts the task to running on nodes which have a kernel version 202 higher than "3.19". 203 204 ```hcl 205 constraint { 206 attribute = "${attr.kernel.version}" 207 operator = "version" 208 value = "> 3.19" 209 } 210 ``` 211 212 ### Distinct Property 213 214 A potential use case of the `distinct_property` constraint is to spread a 215 service with `count > 1` across racks to minimize correlated failure. Nodes can 216 be annotated with which rack they are on using [client 217 metadata][client-metadata] with values such as "rack-12-1", "rack-12-2", etc. 218 The following constraint would assure that an individual rack is not running 219 more than 2 instances of the task group. 220 221 ```hcl 222 constraint { 223 distinct_property = "${meta.rack}" 224 value = "2" 225 } 226 ``` 227 228 ### Operating Systems 229 230 This example restricts the task to running on nodes that are running Ubuntu 231 14.04 232 233 ```hcl 234 constraint { 235 attribute = "${attr.os.name}" 236 value = "ubuntu" 237 } 238 239 constraint { 240 attribute = "${attr.os.version}" 241 value = "14.04" 242 } 243 ``` 244 245 ### Cloud Metadata 246 247 When possible, Nomad populates node attributes from the cloud environment. These 248 values are accessible as filters in constraints. This example constrains this 249 task to only run on nodes that are memory-optimized on AWS. 250 251 ```hcl 252 constraint { 253 attribute = "${attr.platform.aws.instance-type}" 254 value = "m4.xlarge" 255 } 256 ``` 257 258 ### User-Specified Metadata 259 260 This example restricts the task to running on nodes where the binaries for 261 redis, cypress, and nginx are all cached locally. This particular example is 262 utilizing node [metadata][meta]. 263 264 ```hcl 265 constraint { 266 attribute = "${meta.cached_binaries}" 267 set_contains = "redis,cypress,nginx" 268 } 269 ``` 270 271 [job]: /docs/job-specification/job.html "Nomad job Job Specification" 272 [group]: /docs/job-specification/group.html "Nomad group Job Specification" 273 [client-meta]: /docs/agent/configuration/client.html#meta "Nomad meta Job Specification" 274 [task]: /docs/job-specification/task.html "Nomad task Job Specification" 275 [interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"