github.com/dkerwin/nomad@v0.3.3-0.20160525181927-74554135514b/website/source/docs/jobspec/index.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Job Specification" 4 sidebar_current: "docs-jobspec-syntax" 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 service { 51 port = "http" 52 check { 53 type = "http" 54 path = "/health" 55 interval = "10s" 56 timeout = "2s" 57 } 58 } 59 env { 60 DB_HOST = "db01.example.com" 61 DB_USER = "web" 62 DB_PASSWORD = "loremipsum" 63 } 64 resources { 65 cpu = 500 66 memory = 128 67 network { 68 mbits = 100 69 # Request for a dynamic port 70 port "http" { 71 } 72 # Request for a static port 73 port "https" { 74 static = 443 75 } 76 } 77 } 78 } 79 } 80 } 81 ``` 82 83 This is a fairly simple example job, but demonstrates many of the features and syntax 84 of the job specification. The primary "objects" are the job, task group, and task. 85 Each job file has only a single job, however a job may have multiple task groups, 86 and each task group may have multiple tasks. Task groups are a set of tasks that 87 must be co-located on a machine. Groups with a single task and count of one 88 can be declared outside of a group which is created implicitly. 89 90 Constraints can be specified at the job, task group, or task level to restrict 91 where a task is eligible for running. An example constraint looks like: 92 93 ``` 94 # Restrict to only nodes running linux 95 constraint { 96 attribute = "${attr.kernel.name}" 97 value = "linux" 98 } 99 ``` 100 101 Jobs can also specify additional metadata at the job, task group, or task level. 102 This metadata is opaque to Nomad and can be used for any purpose, including 103 defining constraints on the metadata. Metadata can be specified by: 104 105 ``` 106 # Setup ELB via metadata and setup foo 107 meta { 108 foo = "bar" 109 elb_mode = "tcp" 110 elb_check_interval = "10s" 111 } 112 ``` 113 114 ## Syntax Reference 115 116 Following is a syntax reference for the possible keys that are supported 117 and their default values if any for each type of object. 118 119 ### Job 120 121 The `job` object supports the following keys: 122 123 * `all_at_once` - Controls if the entire set of tasks in the job must 124 be placed atomically or if they can be scheduled incrementally. 125 This should only be used for special circumstances. Defaults to `false`. 126 127 * `constraint` - This can be provided multiple times to define additional 128 constraints. See the constraint reference for more details. 129 130 * `datacenters` - A list of datacenters in the region which are eligible 131 for task placement. This must be provided, and does not have a default. 132 133 * `group` - This can be provided multiple times to define additional 134 task groups. See the task group reference for more details. 135 136 * `meta` - Annotates the job with opaque metadata. 137 138 * `priority` - Specifies the job priority which is used to prioritize 139 scheduling and access to resources. Must be between 1 and 100 inclusively, 140 with a larger value corresponding to a higher priority. Defaults to 50. 141 142 * `region` - The region to run the job in, defaults to "global". 143 144 * `task` - This can be specified multiple times to add a task as 145 part of the job. Tasks defined directly in a job are wrapped in 146 a task group of the same name. 147 148 * `type` - Specifies the job type and switches which scheduler 149 is used. Nomad provides the `service`, `system` and `batch` schedulers, 150 and defaults to `service`. To learn more about each scheduler type visit 151 [here](/docs/jobspec/schedulers.html) 152 153 * `update` - Specifies the task's update strategy. When omitted, rolling 154 updates are disabled. The `update` block supports the following keys: 155 156 * `max_parallel` - `max_parallel` is given as an integer value and specifies 157 the number of tasks that can be updated at the same time. 158 159 * `stagger` - `stagger` introduces a delay between sets of task updates and 160 is given as an as a time duration. If stagger is provided as an integer, 161 seconds are assumed. Otherwise the "s", "m", and "h" suffix can be used, 162 such as "30s". 163 164 An example `update` block: 165 166 ``` 167 update { 168 // Update 3 tasks at a time. 169 max_parallel = 3 170 171 // Wait 30 seconds between updates. 172 stagger = "30s" 173 } 174 ``` 175 176 * `periodic` - `periodic` allows the job to be scheduled at fixed times, dates 177 or intervals. The periodic expression is always evaluated in the UTC 178 timezone to ensure consistent evaluation when Nomad Servers span multiple 179 time zones. The `periodic` block supports the following keys: 180 181 * `enabled` - `enabled` determines whether the periodic job will spawn child 182 jobs. `enabled` is defaulted to true if the block is included. 183 184 * `cron` - A cron expression configuring the interval the job is launched 185 at. Supports predefined expressions such as "@daily" and "@weekly" See 186 [here](https://github.com/gorhill/cronexpr#implementation) for full 187 documentation of supported cron specs and the predefined expressions. 188 189 * <a id="prohibit_overlap">`prohibit_overlap`</a> - `prohibit_overlap` can 190 be set to true to enforce that the periodic job doesn't spawn a new 191 instance of the job if any of the previous jobs are still running. It is 192 defaulted to false. 193 194 An example `periodic` block: 195 196 ``` 197 periodic { 198 // Launch every 15 minutes 199 cron = "*/15 * * * * *" 200 201 // Do not allow overlapping runs. 202 prohibit_overlap = true 203 } 204 ``` 205 206 ### Task Group 207 208 The `group` object supports the following keys: 209 210 * `count` - Specifies the number of the task groups that should 211 be running. Must be non-negative, defaults to one. 212 213 * `constraint` - This can be provided multiple times to define additional 214 constraints. See the constraint reference for more details. 215 216 * `restart` - Specifies the restart policy to be applied to tasks in this group. 217 If omitted, a default policy for batch and non-batch jobs is used based on the 218 job type. See the restart policy reference for more details. 219 220 * `task` - This can be specified multiple times, to add a task as 221 part of the group. 222 223 * `meta` - A key/value map that annotates the task group with opaque metadata. 224 225 ### Task 226 227 The `task` object supports the following keys: 228 229 * `driver` - Specifies the task driver that should be used to run the 230 task. See the [driver documentation](/docs/drivers/index.html) for what 231 is available. Examples include `docker`, `qemu`, `java`, and `exec`. 232 233 * `user` - Set the user that will run the task. It defaults to the same user 234 the Nomad client is being run as. 235 236 * `constraint` - This can be provided multiple times to define additional 237 constraints. See the constraint reference for more details. 238 239 * `config` - A map of key/value configuration passed into the driver 240 to start the task. The details of configurations are specific to 241 each driver. 242 243 * `service` - Nomad integrates with Consul for service discovery. A service 244 block represents a routable and discoverable service on the network. Nomad 245 automatically registers when a task is started and de-registers it when the 246 task transitions to the dead state. [Click 247 here](/docs/jobspec/servicediscovery.html) to learn more about services. 248 249 * `env` - A map of key/value representing environment variables that 250 will be passed along to the running process. Nomad variables are 251 interpreted when set in the environment variable values. See the table of 252 interpreted variables [here](/docs/jobspec/interpreted.html). 253 254 For example the below environment map will be reinterpreted: 255 256 ``` 257 env { 258 // The value will be interpreted by the client and set to the 259 // correct value. 260 NODE_CLASS = "${nomad.class}" 261 } 262 ``` 263 264 * `resources` - Provides the resource requirements of the task. 265 See the [resources reference](#resources) for more details. 266 267 * `meta` - Annotates the task group with opaque metadata. 268 269 * `kill_timeout` - `kill_timeout` is a time duration that can be specified using 270 the `s`, `m`, and `h` suffixes, such as `30s`. It can be used to configure the 271 time between signaling a task it will be killed and actually killing it. 272 273 * `logs` - Logs allows configuring log rotation for the `stdout` and `stderr` 274 buffers of a Task. See the log rotation reference below for more details. 275 276 * `artifact` - Defines an artifact to be downloaded before the task is run. This 277 can be provided multiple times to define additional artifacts to download. See 278 the artifacts reference for more details. 279 280 ### Resources 281 282 The `resources` object supports the following keys: 283 284 * `cpu` - The CPU required in MHz. Defaults to `100`. 285 286 * `disk` - The disk required in MB. Defaults to `200`. 287 288 * `iops` - The number of IOPS required given as a weight between 10-1000. Defaults to `0`. 289 290 * `memory` - The memory required in MB. Defaults to `300`. 291 292 * `network` - The network required. Details below. 293 294 The `network` object supports the following keys: 295 296 * `mbits` (required) - The number of MBits in bandwidth required. 297 298 * `port` - `port` is a repeatable object that can be used to specify both 299 dynamic ports and reserved ports. It has the following format: 300 301 ``` 302 port "label" { 303 // If the `static` field is omitted, a dynamic port will be assigned. 304 static = 6539 305 } 306 ``` 307 308 ### Restart Policy 309 310 The `restart` object supports the following keys: 311 312 * `attempts` - `attempts` is the number of restarts allowed in an `interval`. 313 314 * `interval` - `interval` is a time duration that can be specified using the 315 `s`, `m`, and `h` suffixes, such as `30s`. The `interval` begins when the 316 first task starts and ensures that only `attempts` number of restarts happens 317 within it. If more than `attempts` number of failures happen, behavior is 318 controlled by `mode`. 319 320 * `delay` - A duration to wait before restarting a task. It is specified as a 321 time duration using the `s`, `m`, and `h` suffixes, such as `30s`. A random 322 jitter of up to 25% is added to the delay. 323 324 * `mode` - Controls the behavior when the task fails more than `attempts` 325 times in an interval. Possible values are listed below: 326 327 * `delay` - `delay` will delay the next restart until the next `interval` is 328 reached. 329 330 * `fail` - `fail` will not restart the task again. 331 332 The default `batch` restart policy is: 333 334 ``` 335 restart { 336 attempts = 15 337 delay = "15s" 338 interval = "168h" # 7 days 339 mode = "delay" 340 } 341 ``` 342 343 The default non-batch restart policy is: 344 345 ``` 346 restart { 347 interval = "1m" 348 attempts = 2 349 delay = "15s" 350 mode = "delay" 351 } 352 ``` 353 354 ### Constraint 355 356 The `constraint` object supports the following keys: 357 358 * `attribute` - Specifies the attribute to examine for the 359 constraint. See the table of attributes [here](/docs/jobspec/interpreted.html#interpreted_node_vars). 360 361 * `operator` - Specifies the comparison operator. Defaults to equality, 362 and can be `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The 363 ordering is compared lexically. The following are equivalent: 364 365 * `=`, `==` and `is` 366 * `!=` and `not` 367 368 * `value` - Specifies the value to compare the attribute against. 369 This can be a literal value or another attribute. 370 371 * `version` - Specifies a version constraint against the attribute. 372 This sets the operator to `version` and the `value` to what is 373 specified. This supports a comma separated list of constraints, 374 including the pessimistic operator. See the 375 [go-version](https://github.com/hashicorp/go-version) repository 376 for examples. 377 378 * `regexp` - Specifies a regular expression constraint against 379 the attribute. This sets the operator to "regexp" and the `value` 380 to the regular expression. 381 382 * `distinct_hosts` - `distinct_hosts` accepts a boolean value and defaults to 383 `false`. If set, the scheduler will not co-locate any task groups on the same 384 machine. This can be specified as a job constraint which applies the 385 constraint to all task groups in the job, or as a task group constraint which 386 scopes the effect to just that group. 387 388 Placing the constraint at both the job level and at the task group level is 389 redundant since when placed at the job level, the constraint will be applied 390 to all task groups. 391 392 ### Log Rotation 393 394 The `logs` object configures the log rotation policy for a task's `stdout` and 395 `stderr`. The `logs` object supports the following keys: 396 397 * `max_files` - The maximum number of rotated files Nomad will retain for 398 `stdout` and `stderr`, each tracked individually. 399 400 * `max_file_size` - The size of each rotated file. The size is specified in 401 `MB`. 402 403 If the amount of disk resource requested for the task is less than the total 404 amount of disk space needed to retain the rotated set of files, Nomad will return 405 a validation error when a job is submitted. 406 407 ``` 408 logs { 409 max_files = 3 410 max_file_size = 10 411 } 412 ``` 413 414 In the above example we have asked Nomad to retain 3 rotated files for both 415 `stderr` and `stdout` and size of each file is 10MB. The minimum disk space that 416 would be required for the task would be 60MB. 417 418 ### Artifact 419 420 <a id="artifact_doc"></a> 421 422 Nomad downloads artifacts using 423 [`go-getter`](https://github.com/hashicorp/go-getter). The `go-getter` library 424 allows downloading of artifacts from various sources using a URL as the input 425 source. The key/value pairs given in the `options` block map directly to 426 parameters appended to the supplied `source` url. These are then used by 427 `go-getter` to appropriately download the artifact. `go-getter` also has a CLI 428 tool to validate its URL and can be used to check if the Nomad `artifact` is 429 valid. 430 431 Nomad allows downloading `http`, `https`, and `S3` artifacts. If these artifacts 432 are archives (zip, tar.gz, bz2, etc.), these will be unarchived before the task 433 is started. 434 435 The `artifact` object supports the following keys: 436 437 * `source` - The path to the artifact to download. 438 439 * `destination` - An optional path to download the artifact into relative to the 440 root of the task's directory. If the `destination` key is omitted, it will 441 default to `local/`. 442 443 * `options` - The `options` block allows setting parameters for `go-getter`. 444 Full documentation of supported options are available 445 [here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1). 446 An example is given below: 447 448 ``` 449 options { 450 # Validate the downloaded artifact 451 checksum = "md5:c4aa853ad2215426eb7d70a21922e794" 452 453 # S3 options for downloading artifacts from S3 454 aws_access_key_id = "<id>" 455 aws_access_key_secret = "<secret>" 456 aws_access_token = "<token>" 457 } 458 ``` 459 460 An example of downloading and unzipping an archive is as simple as: 461 462 ``` 463 artifact { 464 # The archive will be extracted before the task is run, making 465 # it easy to ship configurations with your binary. 466 source = "https://example.com/my.zip" 467 468 options { 469 checksum = "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3" 470 } 471 } 472 ``` 473 474 ## JSON Syntax 475 476 Job files can also be specified in JSON. The conversion is straightforward 477 and self-documented. The downsides of JSON are less human readability and 478 the lack of comments. Otherwise, the two are completely interoperable. 479 480 See the [JSON API documentation](/docs/jobspec/json.html) for more details on 481 the JSON structure.