github.com/kardianos/nomad@v0.1.3-0.20151022182107-b13df73ee850/website/source/docs/jobspec/index.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Job Specification" 4 sidebar_current: "docs-jobspec" 5 description: |- 6 Learn about the Job specification used to submit jobs to Nomad. 7 --- 8 9 # Job Specification 10 11 Jobs can be specified either in [HCL](https://github.com/hashicorp/hcl) or JSON. 12 HCL is meant to strike a balance between human readable and editable, and machine-friendly. 13 14 For machine-friendliness, Nomad can also read JSON configurations. In general, we recommend 15 using the HCL syntax. 16 17 ## HCL Syntax 18 19 For a detailed description of HCL general syntax, [see this guide](https://github.com/hashicorp/hcl#syntax). 20 Here we cover the details of the Job specification for Nomad: 21 22 ``` 23 # Define a job called my-service 24 job "my-service" { 25 # Job should run in the US region 26 region = "us" 27 28 # Spread tasks between us-west-1 and us-east-1 29 datacenters = ["us-west-1", "us-east-1"] 30 31 # run this job globally 32 type = "system" 33 34 # Rolling updates should be sequential 35 update { 36 stagger = "30s" 37 max_parallel = 1 38 } 39 40 group "webs" { 41 # We want 5 web servers 42 count = 5 43 44 # Create a web front end using a docker image 45 task "frontend" { 46 driver = "docker" 47 config { 48 image = "hashicorp/web-frontend" 49 } 50 env { 51 DB_HOST = "db01.example.com" 52 DB_USER = "web" 53 DB_PASSWORD = "loremipsum" 54 } 55 resources { 56 cpu = 500 57 memory = 128 58 network { 59 mbits = 100 60 dynamic_ports = [ 61 "http", 62 "https", 63 ] 64 } 65 } 66 } 67 } 68 } 69 ``` 70 71 This is a fairly simple example job, but demonstrates many of the features and syntax 72 of the job specification. The primary "objects" are the job, task group, and task. 73 Each job file has only a single job, however a job may have multiple task groups, 74 and each task group may have multiple tasks. Task groups are a set of tasks that 75 must be co-located on a machine. Groups with a single task and count of one 76 can be declared outside of a group which is created implicitly. 77 78 Constraints can be specified at the job, task group, or task level to restrict 79 where a task is eligible for running. An example constraint looks like: 80 81 ``` 82 # Restrict to only nodes running linux 83 constraint { 84 attribute = "$attr.kernel.os" 85 value = "linux" 86 } 87 ``` 88 89 Jobs can also specify additional metadata at the job, task group, or task level. 90 This metadata is opaque to Nomad and can be used for any purpose, including 91 defining constraints on the metadata. Metadata can be specified by: 92 93 ``` 94 # Setup ELB via metadata and setup foo 95 meta { 96 foo = "bar" 97 elb_mode = "tcp" 98 elb_check_interval = "10s" 99 } 100 ``` 101 102 ## Syntax Reference 103 104 Following is a syntax reference for the possible keys that are supported 105 and their default values if any for each type of object. 106 107 ### Job 108 109 The `job` object supports the following keys: 110 111 * `all_at_once` - Controls if the entire set of tasks in the job must 112 be placed atomically or if they can be scheduled incrementally. 113 This should only be used for special circumstances. Defaults to `false`. 114 115 * `constraint` - This can be provided multiple times to define additional 116 constraints. See the constraint reference for more details. 117 118 * `datacenters` - A list of datacenters in the region which are eligible 119 for task placement. This must be provided, and does not have a default. 120 121 * `group` - This can be provided multiple times to define additional 122 task groups. See the task group reference for more details. 123 124 * `meta` - Annotates the job with opaque metadata. 125 126 * `priority` - Specifies the job priority which is used to prioritize 127 scheduling and access to resources. Must be between 1 and 100 inclusively, 128 and defaults to 50. 129 130 * `region` - The region to run the job in, defaults to "global". 131 132 * `task` - This can be specified multiple times to add a task as 133 part of the job. Tasks defined directly in a job are wrapped in 134 a task group of the same name. 135 136 * `type` - Specifies the job type and switches which scheduler 137 is used. Nomad provides the `service`, `system` and `batch` schedulers, 138 and defaults to `service`. 139 140 * `update` - Specifies the task update strategy. This requires providing 141 `max_parallel` as an integer and `stagger` as a time duration. If stagger 142 is provided as an integer, seconds are assumed. Otherwise the "s", "m", 143 and "h" suffix can be used, such as "30s". Both values default to zero, 144 which disables rolling updates. 145 146 ### Task Group 147 148 The `group` object supports the following keys: 149 150 * `count` - Specifies the number of the task groups that should 151 be running. Must be positive, defaults to one. 152 153 * `constraint` - This can be provided multiple times to define additional 154 constraints. See the constraint reference for more details. 155 156 * `task` - This can be specified multiple times, to add a task as 157 part of the group. 158 159 * `meta` - Annotates the task group with opaque metadata. 160 161 ### Task 162 163 The `task` object supports the following keys: 164 165 * `driver` - Specifies the task driver that should be used to run the 166 task. See the [driver documentation](/docs/drivers/index.html) for what 167 is available. Examples include "docker", "qemu", "java", and "exec". 168 169 * `constraint` - This can be provided multiple times to define additional 170 constraints. See the constraint reference for more details. 171 172 * `config` - A map of key/value configuration passed into the driver 173 to start the task. The details of configurations are specific to 174 each driver. 175 176 * `env` - A map of key/value representing environment variables that 177 will be passed along to the running process. 178 179 * `resources` - Provides the resource requirements of the task. 180 See the resources reference for more details. 181 182 * `meta` - Annotates the task group with opaque metadata. 183 184 ### Resources 185 186 The `resources` object supports the following keys: 187 188 * `cpu` - The CPU required in MHz. 189 190 * `disk` - The disk required in MB. 191 192 * `iops` - The number of IOPS required given as a weight between 10-1000. 193 194 * `memory` - The memory required in MB. 195 196 * `network` - The network required. Details below. 197 198 The `network` object supports the following keys: 199 200 * `dynamic_ports` - List of port labels which may contain letters, 201 numbers and underscores (`^[a-zA-Z0-9_]+$`). Each label will be assigned a 202 dynamic port when the task starts. Ports are passed to the task environment as 203 `NOMAD_PORT_{LABEL}`. Drivers may infer additional semantics from the label. 204 See the relevant driver docs for details. 205 206 * `mbits` - The number of MBits in bandwidth required. 207 208 * `reserved_ports` - This is a list of specific ports required. 209 For applications that cannot use a dynamic port, they can 210 request a specific port. 211 212 ### Constraint 213 214 The `constraint` object supports the following keys: 215 216 * `attribute` - Specifies the attribute to examine for the 217 constraint. See the table of attributes below. 218 219 * `hard` - Specifies if this is a hard or soft constraint. Defaults 220 to true. Soft constraints are not currently supported. 221 222 * `operator` - Specifies the comparison operator. Defaults to equality, 223 and can be `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The 224 ordering is compared lexically. 225 226 * `value` - Specifies the value to compare the attribute against. 227 This can be a literal value or another attribute. 228 229 * `version` - Specifies a version constraint against the attribute. 230 This sets the operator to "version" and the `value` to what is 231 specified. This supports a comma seperated list of constraints, 232 including the pessimistic operator. See the 233 [go-version](https://github.com/hashicorp/go-version) repository 234 for examples. 235 236 * `regexp` - Specifies a regular expression constraint against 237 the attribute. This sets the operator to "regexp" and the `value` 238 to the regular expression. 239 240 Below is a table documenting the variables that can be interpreted: 241 242 <table class="table table-bordered table-striped"> 243 <tr> 244 <th>Variable</th> 245 <th>Description</th> 246 </tr> 247 <tr> 248 <td>$node.id</td> 249 <td>The client node identifier</td> 250 </tr> 251 <tr> 252 <td>$node.datacenter</td> 253 <td>The client node datacenter</td> 254 </tr> 255 <tr> 256 <td>$node.name</td> 257 <td>The client node name</td> 258 </tr> 259 <tr> 260 <td>$attr.\<key\></td> 261 <td>The attribute given by `key` on the client node.</td> 262 </tr> 263 <tr> 264 <td>$meta.\<key\></td> 265 <td>The metadata value given by `key` on the client node.</td> 266 </tr> 267 </table> 268 269 Below is a table documenting common node attributes: 270 271 <table class="table table-bordered table-striped"> 272 <tr> 273 <th>Attribute</th> 274 <th>Description</th> 275 </tr> 276 <tr> 277 <td>arch</td> 278 <td>CPU architecture of the client. Examples: "amd64", "386"</td> 279 </tr> 280 <tr> 281 <td>consul.datacenter</td> 282 <td>The Consul datacenter of the client node if Consul found</td> 283 </tr> 284 <tr> 285 <td>cpu.numcores</td> 286 <td>Number of CPU cores on the client</td> 287 </tr> 288 <tr> 289 <td>driver.\<key\></td> 290 <td>See the [task drivers](/docs/drivers/index.html) for attribute documentation</td> 291 </tr> 292 <tr> 293 <td>hostname</td> 294 <td>Hostname of the client</td> 295 </tr> 296 <tr> 297 <td>platform.aws.ami-id</td> 298 <td>On EC2, the AMI ID of the client node</td> 299 </tr> 300 <tr> 301 <td>platform.aws.instance-type</td> 302 <td>On EC2, the instance type of the client node</td> 303 </tr> 304 <tr> 305 <td>os.name</td> 306 <td>Operating system of the client. Examples: "linux", "windows", "darwin"</td> 307 </tr> 308 <tr> 309 <td>os.version</td> 310 <td>Version of the client OS</td> 311 </tr> 312 </table> 313 314 ## JSON Syntax 315 316 Job files can also be specified in JSON. The conversion is straightforward 317 and self-documented. The downsides of JSON are less human readability and 318 the lack of comments. Otherwise, the two are completely interoperable. 319 320 See the API documentation for more details on the JSON structure. 321 322