github.com/smintz/nomad@v0.8.3/website/source/api/json-jobs.html.md (about) 1 --- 2 layout: api 3 page_title: JSON Job Specification - HTTP API 4 sidebar_current: api-json-jobs 5 description: |- 6 Jobs can also be specified via the HTTP API using a JSON format. This guide 7 discusses the job specification in JSON format. 8 --- 9 10 # JSON Job Specification 11 12 This guide covers the JSON syntax for submitting jobs to Nomad. A useful command 13 for generating valid JSON versions of HCL jobs is: 14 15 ```shell 16 $ nomad job run -output my-job.nomad 17 ``` 18 19 ## Syntax 20 21 Below is the JSON representation of the job outputted by `$ nomad init`: 22 23 ```json 24 { 25 "Job": { 26 "ID": "example", 27 "Name": "example", 28 "Type": "service", 29 "Priority": 50, 30 "Datacenters": [ 31 "dc1" 32 ], 33 "TaskGroups": [{ 34 "Name": "cache", 35 "Count": 1, 36 "Migrate": { 37 "HealthCheck": "checks", 38 "HealthyDeadline": 300000000000, 39 "MaxParallel": 1, 40 "MinHealthyTime": 10000000000 41 }, 42 "Tasks": [{ 43 "Name": "redis", 44 "Driver": "docker", 45 "User": "", 46 "Config": { 47 "image": "redis:3.2", 48 "port_map": [{ 49 "db": 6379 50 }] 51 }, 52 "Services": [{ 53 "Id": "", 54 "Name": "redis-cache", 55 "Tags": [ 56 "global", 57 "cache" 58 ], 59 "PortLabel": "db", 60 "AddressMode": "", 61 "Checks": [{ 62 "Id": "", 63 "Name": "alive", 64 "Type": "tcp", 65 "Command": "", 66 "Args": null, 67 "Header": {}, 68 "Method": "", 69 "Path": "", 70 "Protocol": "", 71 "PortLabel": "", 72 "Interval": 10000000000, 73 "Timeout": 2000000000, 74 "InitialStatus": "", 75 "TLSSkipVerify": false, 76 "CheckRestart": { 77 "Limit": 3, 78 "Grace": 30000000000, 79 "IgnoreWarnings": false 80 } 81 }] 82 }], 83 "Resources": { 84 "CPU": 500, 85 "MemoryMB": 256, 86 "Networks": [{ 87 "Device": "", 88 "CIDR": "", 89 "IP": "", 90 "MBits": 10, 91 "DynamicPorts": [{ 92 "Label": "db", 93 "Value": 0 94 }] 95 }] 96 }, 97 "Leader": false 98 }], 99 "RestartPolicy": { 100 "Interval": 1800000000000, 101 "Attempts": 2, 102 "Delay": 15000000000, 103 "Mode": "fail" 104 }, 105 "ReschedulePolicy": { 106 "Attempts": 10, 107 "Delay": 30000000000, 108 "DelayFunction": "exponential", 109 "Interval": 0, 110 "MaxDelay": 3600000000000, 111 "Unlimited": true 112 }, 113 "EphemeralDisk": { 114 "SizeMB": 300 115 } 116 }], 117 "Update": { 118 "MaxParallel": 1, 119 "MinHealthyTime": 10000000000, 120 "HealthyDeadline": 180000000000, 121 "AutoRevert": false, 122 "Canary": 0 123 } 124 } 125 } 126 ``` 127 128 The example JSON could be submitted as a job using the following: 129 130 ```text 131 $ curl -XPUT -d @example.json http://127.0.0.1:4646/v1/job/example 132 { 133 "EvalID": "5d6ded54-0b2a-8858-6583-be5f476dec9d", 134 "EvalCreateIndex": 12, 135 "JobModifyIndex": 11, 136 "Warnings": "", 137 "Index": 12, 138 "LastContact": 0, 139 "KnownLeader": false 140 } 141 ``` 142 143 ## Syntax Reference 144 145 Following is a syntax reference for the possible keys that are supported and 146 their default values if any for each type of object. 147 148 ### Job 149 150 The `Job` object supports the following keys: 151 152 - `AllAtOnce` - Controls whether the scheduler can make partial placements if 153 optimistic scheduling resulted in an oversubscribed node. This does not 154 control whether all allocations for the job, where all would be the desired 155 count for each task group, must be placed atomically. This should only be 156 used for special circumstances. Defaults to `false`. 157 158 - `Constraints` - A list to define additional constraints where a job can be 159 run. See the constraint reference for more details. 160 161 - `Datacenters` - A list of datacenters in the region which are eligible 162 for task placement. This must be provided, and does not have a default. 163 164 - `TaskGroups` - A list to define additional task groups. See the task group 165 reference for more details. 166 167 - `Meta` - Annotates the job with opaque metadata. 168 169 - `Namespace` - The namespace to execute the job in, defaults to "default". 170 Values other than default are not allowed in non-Enterprise versions of Nomad. 171 172 - `ParameterizedJob` - Specifies the job as a parameterized job such that it can 173 be dispatched against. The `ParameterizedJob` object supports the following 174 attributes: 175 176 - `MetaOptional` - Specifies the set of metadata keys that may be provided 177 when dispatching against the job as a string array. 178 179 - `MetaRequired` - Specifies the set of metadata keys that must be provided 180 when dispatching against the job as a string array. 181 182 - `Payload` - Specifies the requirement of providing a payload when 183 dispatching against the parameterized job. The options for this field are 184 "optional", "required" and "forbidden". The default value is "optional". 185 186 - `Payload` - The payload may not be set when submitting a job but may appear in 187 a dispatched job. The `Payload` will be a base64 encoded string containing the 188 payload that the job was dispatched with. The `payload` has a **maximum size 189 of 16 KiB**. 190 191 - `Priority` - Specifies the job priority which is used to prioritize 192 scheduling and access to resources. Must be between 1 and 100 inclusively, 193 and defaults to 50. 194 195 - `Region` - The region to run the job in, defaults to "global". 196 197 - `Type` - Specifies the job type and switches which scheduler 198 is used. Nomad provides the `service`, `system` and `batch` schedulers, 199 and defaults to `service`. To learn more about each scheduler type visit 200 [here](/docs/runtime/schedulers.html) 201 202 - `Update` - Specifies an update strategy to be applied to all task groups 203 within the job. When specified both at the job level and the task group level, 204 the update blocks are merged with the task group's taking precedence. For more 205 details on the update stanza, please see below. 206 207 - `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates 208 or intervals. The periodic expression is always evaluated in the UTC 209 timezone to ensure consistent evaluation when Nomad Servers span multiple 210 time zones. The `Periodic` object is optional and supports the following attributes: 211 212 - `Enabled` - `Enabled` determines whether the periodic job will spawn child 213 jobs. 214 215 - `TimeZone` - Specifies the time zone to evaluate the next launch interval 216 against. This is useful when wanting to account for day light savings in 217 various time zones. The time zone must be parsable by Golang's 218 [LoadLocation](https://golang.org/pkg/time/#LoadLocation). The default is 219 UTC. 220 221 - `SpecType` - `SpecType` determines how Nomad is going to interpret the 222 periodic expression. `cron` is the only supported `SpecType` currently. 223 224 - `Spec` - A cron expression configuring the interval the job is launched 225 at. Supports predefined expressions such as "@daily" and "@weekly" See 226 [here](https://github.com/gorhill/cronexpr#implementation) for full 227 documentation of supported cron specs and the predefined expressions. 228 229 - <a id="prohibit_overlap">`ProhibitOverlap`</a> - `ProhibitOverlap` can 230 be set to true to enforce that the periodic job doesn't spawn a new 231 instance of the job if any of the previous jobs are still running. It is 232 defaulted to false. 233 234 An example `periodic` block: 235 236 ```json 237 { 238 "Periodic": { 239 "Spec": "*/15 - *", 240 "TimeZone": "Europe/Berlin", 241 "SpecType": "cron", 242 "Enabled": true, 243 "ProhibitOverlap": true 244 } 245 } 246 ``` 247 248 - `ReschedulePolicy` - Specifies a reschedule policy to be applied to all task groups 249 within the job. When specified both at the job level and the task group level, 250 the reschedule blocks are merged, with the task group's taking precedence. For more 251 details on `ReschedulePolicy`, please see below. 252 253 ### Task Group 254 255 `TaskGroups` is a list of `TaskGroup` objects, each supports the following 256 attributes: 257 258 - `Constraints` - This is a list of `Constraint` objects. See the constraint 259 reference for more details. 260 261 - `Count` - Specifies the number of the task groups that should 262 be running. Must be non-negative, defaults to one. 263 264 - `Meta` - A key-value map that annotates the task group with opaque metadata. 265 266 - `Migrate` - Specifies a migration strategy to be applied during [node 267 drains][drain]. 268 269 - `HealthCheck` - One of `checks` or `task_states`. Indicates how task health 270 should be determined: either via Consul health checks or whether the task 271 was able to run successfully. 272 273 - `HealthyDeadline` - Specifies duration a task must become healthy within 274 before it is considered unhealthy. 275 276 - `MaxParallel` - Specifies how many allocations may be migrated at once. 277 278 - `MinHealthyTime` - Specifies duration a task must be considered healthy 279 before the migration is considered healthy. 280 281 - `Name` - The name of the task group. Must be specified. 282 283 - `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group. 284 If omitted, a default policy for batch and non-batch jobs is used based on the 285 job type. See the [restart policy reference](#restart_policy) for more details. 286 287 - `ReschedulePolicy` - Specifies the reschedule policy to be applied to tasks in this group. 288 If omitted, a default policy is used for batch and service jobs. System jobs are not eligible 289 for rescheduling. See the [reschedule policy reference](#reschedule_policy) for more details. 290 291 - `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the 292 [ephemeral disk reference](#ephemeral_disk) for more details. 293 294 - `Update` - Specifies an update strategy to be applied to all task groups 295 within the job. When specified both at the job level and the task group level, 296 the update blocks are merged with the task group's taking precedence. For more 297 details on the update stanza, please see below. 298 299 - `Tasks` - A list of `Task` object that are part of the task group. 300 301 ### Task 302 303 The `Task` object supports the following keys: 304 305 - `Artifacts` - `Artifacts` is a list of `Artifact` objects which define 306 artifacts to be downloaded before the task is run. See the artifacts 307 reference for more details. 308 309 - `Config` - A map of key-value configuration passed into the driver 310 to start the task. The details of configurations are specific to 311 each driver. 312 313 - `Constraints` - This is a list of `Constraint` objects. See the constraint 314 reference for more details. 315 316 - `DispatchPayload` - Configures the task to have access to dispatch payloads. 317 The `DispatchPayload` object supports the following attributes: 318 319 - `File` - Specifies the file name to write the content of dispatch payload 320 to. The file is written relative to the task's local directory. 321 322 - `Driver` - Specifies the task driver that should be used to run the 323 task. See the [driver documentation](/docs/drivers/index.html) for what 324 is available. Examples include `docker`, `qemu`, `java`, and `exec`. 325 326 - `Env` - A map of key-value representing environment variables that 327 will be passed along to the running process. Nomad variables are 328 interpreted when set in the environment variable values. See the table of 329 interpreted variables [here](/docs/runtime/interpolation.html). 330 331 For example the below environment map will be reinterpreted: 332 333 ```json 334 { 335 "Env": { 336 "NODE_CLASS" : "${nomad.class}" 337 } 338 } 339 ``` 340 341 - `KillSignal` - Specifies a configurable kill signal for a task, where the 342 default is SIGINT. Note that this is only supported for drivers which accept 343 sending signals (currently `docker`, `exec`, `raw_exec`, and `java` drivers). 344 345 - `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be 346 used to configure the time between signaling a task it will be killed and 347 actually killing it. Drivers first sends a task the `SIGINT` signal and then 348 sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has 349 elapsed. The default `KillTimeout` is 5 seconds. 350 351 - `Leader` - Specifies whether the task is the leader task of the task group. If 352 set to true, when the leader task completes, all other tasks within the task 353 group will be gracefully shutdown. 354 355 - `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr` 356 buffers of a Task. See the log rotation reference below for more details. 357 358 - `Meta` - Annotates the task group with opaque metadata. 359 360 - `Name` - The name of the task. This field is required. 361 362 - `Resources` - Provides the resource requirements of the task. 363 See the resources reference for more details. 364 365 - `Services` - `Services` is a list of `Service` objects. Nomad integrates with 366 Consul for service discovery. A `Service` object represents a routable and 367 discoverable service on the network. Nomad automatically registers when a task 368 is started and de-registers it when the task transitions to the dead state. 369 [Click here](/docs/service-discovery/index.html) to learn more about 370 services. Below is the fields in the `Service` object: 371 372 - `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, 373 `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task, 374 respectively. `${BASE}` expands to the equivalent of 375 `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service. 376 Each service defined for a given task must have a distinct name, so if 377 a task has multiple services only one of them can use the default name 378 and the others must be explicitly named. Names must adhere to 379 [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are 380 limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be 381 less than 64 characters in length. 382 383 - `Tags`: A list of string tags associated with this Service. String 384 interpolation is supported in tags. 385 386 - `PortLabel`: `PortLabel` is an optional string and is used to associate 387 a port with the service. If specified, the port label must match one 388 defined in the resources block. This could be a label of either a 389 dynamic or a static port. 390 391 - `AddressMode`: Specifies what address (host or driver-specific) this 392 service should advertise. This setting is supported in Docker since 393 Nomad 0.6 and rkt since Nomad 0.7. Valid options are: 394 395 - `auto` - Allows the driver to determine whether the host or driver 396 address should be used. Defaults to `host` and only implemented by 397 Docker. If you use a Docker network plugin such as weave, Docker will 398 automatically use its address. 399 400 - `driver` - Use the IP specified by the driver, and the port specified 401 in a port map. A numeric port may be specified since port maps aren't 402 required by all network plugins. Useful for advertising SDN and 403 overlay network addresses. Task will fail if driver network cannot be 404 determined. Only implemented for Docker and rkt. 405 406 - `host` - Use the host IP and port. 407 408 - `Checks`: `Checks` is an array of check objects. A check object defines a 409 health check associated with the service. Nomad supports the `script`, 410 `http` and `tcp` Consul Checks. Script checks are not supported for the 411 qemu driver since the Nomad client doesn't have access to the file system 412 of a task using the Qemu driver. 413 414 - `Type`: This indicates the check types supported by Nomad. Valid 415 options are currently `script`, `http` and `tcp`. 416 417 - `Name`: The name of the health check. 418 419 - `AddressMode`: Same as `AddressMode` on `Service`. Unlike services, 420 checks do not have an `auto` address mode as there's no way for 421 Nomad to know which is the best address to use for checks. Consul 422 needs access to the address for any HTTP or TCP checks. Added in 423 Nomad 0.7.1. Unlike `PortLabel`, this setting is *not* inherited 424 from the `Service`. 425 426 - `PortLabel`: Specifies the label of the port on which the check will 427 be performed. Note this is the _label_ of the port and not the port 428 number unless `AddressMode: "driver"`. The port label must match one 429 defined in the Network stanza. If a port value was declared on the 430 `Service`, this will inherit from that value if not supplied. If 431 supplied, this value takes precedence over the `Service.PortLabel` 432 value. This is useful for services which operate on multiple ports. 433 `http` and `tcp` checks require a port while `script` checks do not. 434 Checks will use the host IP and ports by default. In Nomad 0.7.1 or 435 later numeric ports may be used if `AddressMode: "driver"` is set on 436 the check. 437 438 - `Header`: Headers for HTTP checks. Should be an object where the 439 values are an array of values. Headers will be written once for each 440 value. 441 442 - `Interval`: This indicates the frequency of the health checks that 443 Consul will perform. 444 445 - `Timeout`: This indicates how long Consul will wait for a health 446 check query to succeed. 447 448 - `Method`: The HTTP method to use for HTTP checks. Defaults to GET. 449 450 - `Path`: The path of the HTTP endpoint which Consul will query to query 451 the health of a service if the type of the check is `http`. Nomad 452 will add the IP of the service and the port, users are only required 453 to add the relative URL of the health check endpoint. Absolute paths 454 are not allowed. 455 456 - `Protocol`: This indicates the protocol for the HTTP checks. Valid 457 options are `http` and `https`. We default it to `http`. 458 459 - `Command`: This is the command that the Nomad client runs for doing 460 script based health check. 461 462 - `Args`: Additional arguments to the `command` for script based health 463 checks. 464 465 - `TLSSkipVerify`: If true, Consul will not attempt to verify the 466 certificate when performing HTTPS checks. Requires Consul >= 0.7.2. 467 468 - `CheckRestart`: `CheckRestart` is an object which enables 469 restarting of tasks based upon Consul health checks. 470 471 - `Limit`: The number of unhealthy checks allowed before the 472 service is restarted. Defaults to `0` which disables 473 health-based restarts. 474 475 - `Grace`: The duration to wait after a task starts or restarts 476 before counting unhealthy checks count against the limit. 477 Defaults to "1s". 478 479 - `IgnoreWarnings`: Treat checks that are warning as passing. 480 Defaults to false which means warnings are considered unhealthy. 481 482 - `ShutdownDelay` - Specifies the duration to wait when killing a task between 483 removing it from Consul and sending it a shutdown signal. Ideally services 484 would fail healthchecks once they receive a shutdown signal. Alternatively 485 `ShutdownDelay` may be set to give in flight requests time to complete before 486 shutting down. 487 488 - `Templates` - Specifies the set of [`Template`](#template) objects to render for the task. 489 Templates can be used to inject both static and dynamic configuration with 490 data populated from environment variables, Consul and Vault. 491 492 - `User` - Set the user that will run the task. It defaults to the same user 493 the Nomad client is being run as. This can only be set on Linux platforms. 494 495 ### Resources 496 497 The `Resources` object supports the following keys: 498 499 - `CPU` - The CPU required in MHz. 500 501 - `IOPS` - The number of IOPS required given as a weight between 10-1000. 502 503 - `MemoryMB` - The memory required in MB. 504 505 - `Networks` - A list of network objects. 506 507 The Network object supports the following keys: 508 509 - `MBits` - The number of MBits in bandwidth required. 510 511 Nomad can allocate two types of ports to a task - Dynamic and Static/Reserved 512 ports. A network object allows the user to specify a list of `DynamicPorts` and 513 `ReservedPorts`. Each object supports the following attributes: 514 515 - `Value` - The port number for static ports. If the port is dynamic, then this 516 attribute is ignored. 517 - `Label` - The label to annotate a port so that it can be referred in the 518 service discovery block or environment variables. 519 520 <a id="ephemeral_disk"></a> 521 522 ### Ephemeral Disk 523 524 The `EphemeralDisk` object supports the following keys: 525 526 - `Migrate` - Specifies that the Nomad client should make a best-effort attempt 527 to migrate the data from a remote machine if placement cannot be made on the 528 original node. During data migration, the task will block starting until the 529 data migration has completed. Value is a boolean and the default is false. 530 531 - `SizeMB` - Specifies the size of the ephemeral disk in MB. Default is 300. 532 533 - `Sticky` - Specifies that Nomad should make a best-effort attempt to place the 534 updated allocation on the same machine. This will move the `local/` and 535 `alloc/data` directories to the new allocation. Value is a boolean and the 536 default is false. 537 538 <a id="reschedule_policy"></a> 539 540 ### Reschedule Policy 541 542 The `ReschedulePolicy` object supports the following keys: 543 544 - `Attempts` - `Attempts` is the number of reschedule attempts allowed 545 in an `Interval`. 546 547 - `Interval` - `Interval` is a time duration that is specified in nanoseconds. 548 The `Interval` is a sliding window within which at most `Attempts` number 549 of reschedule attempts are permitted. 550 551 - `Delay` - A duration to wait before attempting rescheduling. It is specified in 552 nanoseconds. 553 554 - `DelayFunction` - Specifies the function that is used to calculate subsequent reschedule delays. 555 The initial delay is specified by the `Delay` parameter. Allowed values for `DelayFunction` are listed below: 556 - `constant` - The delay between reschedule attempts stays at the `Delay` value. 557 - `exponential` - The delay between reschedule attempts doubles. 558 - `fibonacci` - The delay between reschedule attempts is calculated by adding the two most recent 559 delays applied. For example if `Delay` is set to 5 seconds, the next five reschedule attempts will be 560 delayed by 5 seconds, 5 seconds, 10 seconds, 15 seconds, and 25 seconds respectively. 561 562 - `MaxDelay` - `MaxDelay` is an upper bound on the delay beyond which it will not increase. This parameter is used when 563 `DelayFunction` is `exponential` or `fibonacci`, and is ignored when `constant` delay is used. 564 565 - `Unlimited` - `Unlimited` enables unlimited reschedule attempts. If this is set to true 566 the `Attempts` and `Interval` fields are not used. 567 568 569 <a id="restart_policy"></a> 570 571 ### Restart Policy 572 573 The `RestartPolicy` object supports the following keys: 574 575 - `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`. 576 577 - `Interval` - `Interval` is a time duration that is specified in nanoseconds. 578 The `Interval` begins when the first task starts and ensures that only 579 `Attempts` number of restarts happens within it. If more than `Attempts` 580 number of failures happen, behavior is controlled by `Mode`. 581 582 - `Delay` - A duration to wait before restarting a task. It is specified in 583 nanoseconds. A random jitter of up to 25% is added to the delay. 584 585 - `Mode` - `Mode` is given as a string and controls the behavior when the task 586 fails more than `Attempts` times in an `Interval`. Possible values are listed 587 below: 588 589 - `delay` - `delay` will delay the next restart until the next `Interval` is 590 reached. 591 592 - `fail` - `fail` will not restart the task again. 593 594 ### Update 595 596 Specifies the task group update strategy. When omitted, rolling updates are 597 disabled. The update stanza can be specified at the job or task group level. 598 When specified at the job, the update stanza is inherited by all task groups. 599 When specified in both the job and in a task group, the stanzas are merged with 600 the task group's taking precedence. The `Update` object supports the following 601 attributes: 602 603 - `MaxParallel` - `MaxParallel` is given as an integer value and specifies 604 the number of tasks that can be updated at the same time. 605 606 - `HealthCheck` - Specifies the mechanism in which allocations health is 607 determined. The potential values are: 608 609 - "checks" - Specifies that the allocation should be considered healthy when 610 all of its tasks are running and their associated [checks][] are healthy, 611 and unhealthy if any of the tasks fail or not all checks become healthy. 612 This is a superset of "task_states" mode. 613 614 - "task_states" - Specifies that the allocation should be considered healthy 615 when all its tasks are running and unhealthy if tasks fail. 616 617 - "manual" - Specifies that Nomad should not automatically determine health 618 and that the operator will specify allocation health using the [HTTP 619 API](/api/deployments.html#set-allocation-health-in-deployment). 620 621 - `MinHealthyTime` - Specifies the minimum time the allocation must be in the 622 healthy state before it is marked as healthy and unblocks further allocations 623 from being updated. This is specified using a label suffix like "30s" or 624 "15m". 625 626 - `HealthyDeadline` - Specifies the deadline in which the allocation must be 627 marked as healthy after which the allocation is automatically transitioned to 628 unhealthy. This is specified using a label suffix like "2m" or "1h". 629 630 - `AutoRevert` - Specifies if the job should auto-revert to the last stable job 631 on deployment failure. A job is marked as stable if all the allocations as 632 part of its deployment were marked healthy. 633 634 - `Canary` - Specifies that changes to the job that would result in destructive 635 updates should create the specified number of canaries without stopping any 636 previous allocations. Once the operator determines the canaries are healthy, 637 they can be promoted which unblocks a rolling update of the remaining 638 allocations at a rate of `max_parallel`. 639 640 - `Stagger` - Specifies the delay between migrating allocations off nodes marked 641 for draining. This is specified using a label suffix like "30s" or "1h". 642 643 An example `Update` block: 644 645 ```json 646 { 647 "Update": { 648 "MaxParallel": 3, 649 "HealthCheck": "checks", 650 "MinHealthyTime": 15000000000, 651 "HealthyDeadline": 180000000000, 652 "AutoRevert": false, 653 "Canary": 1 654 } 655 } 656 ``` 657 658 ### Constraint 659 660 The `Constraint` object supports the following keys: 661 662 - `LTarget` - Specifies the attribute to examine for the 663 constraint. See the table of attributes [here](/docs/runtime/interpolation.html#interpreted_node_vars). 664 665 - `RTarget` - Specifies the value to compare the attribute against. 666 This can be a literal value, another attribute or a regular expression if 667 the `Operator` is in "regexp" mode. 668 669 - `Operand` - Specifies the test to be performed on the two targets. It takes on the 670 following values: 671 672 - `regexp` - Allows the `RTarget` to be a regular expression to be matched. 673 674 - `set_contains` - Allows the `RTarget` to be a comma separated list of values 675 that should be contained in the LTarget's value. 676 677 - `distinct_hosts` - If set, the scheduler will not co-locate any task groups on the same 678 machine. This can be specified as a job constraint which applies the 679 constraint to all task groups in the job, or as a task group constraint which 680 scopes the effect to just that group. The constraint may not be 681 specified at the task level. 682 683 Placing the constraint at both the job level and at the task group level is 684 redundant since when placed at the job level, the constraint will be applied 685 to all task groups. When specified, `LTarget` and `RTarget` should be 686 omitted. 687 688 - `distinct_property` - If set, the scheduler selects nodes that have a 689 distinct value of the specified property. The `RTarget` specifies how 690 many allocations are allowed to share the value of a property. The 691 `RTarget` must be 1 or greater and if omitted, defaults to 1. This can 692 be specified as a job constraint which applies the constraint to all 693 task groups in the job, or as a task group constraint which scopes the 694 effect to just that group. The constraint may not be specified at the 695 task level. 696 697 Placing the constraint at both the job level and at the task group level is 698 redundant since when placed at the job level, the constraint will be applied 699 to all task groups. When specified, `LTarget` should be the property 700 that should be distinct and and `RTarget` should be omitted. 701 702 - Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The 703 ordering is compared lexically. 704 705 ### Log Rotation 706 707 The `LogConfig` object configures the log rotation policy for a task's `stdout` and 708 `stderr`. The `LogConfig` object supports the following attributes: 709 710 - `MaxFiles` - The maximum number of rotated files Nomad will retain for 711 `stdout` and `stderr`, each tracked individually. 712 713 - `MaxFileSizeMB` - The size of each rotated file. The size is specified in 714 `MB`. 715 716 If the amount of disk resource requested for the task is less than the total 717 amount of disk space needed to retain the rotated set of files, Nomad will return 718 a validation error when a job is submitted. 719 720 ```json 721 { 722 "LogConfig": { 723 "MaxFiles": 3, 724 "MaxFileSizeMB": 10 725 } 726 } 727 ``` 728 729 In the above example we have asked Nomad to retain 3 rotated files for both 730 `stderr` and `stdout` and size of each file is 10 MB. The minimum disk space that 731 would be required for the task would be 60 MB. 732 733 ### Artifact 734 735 Nomad downloads artifacts using 736 [`go-getter`](https://github.com/hashicorp/go-getter). The `go-getter` library 737 allows downloading of artifacts from various sources using a URL as the input 738 source. The key-value pairs given in the `options` block map directly to 739 parameters appended to the supplied `source` URL. These are then used by 740 `go-getter` to appropriately download the artifact. `go-getter` also has a CLI 741 tool to validate its URL and can be used to check if the Nomad `artifact` is 742 valid. 743 744 Nomad allows downloading `http`, `https`, and `S3` artifacts. If these artifacts 745 are archives (zip, tar.gz, bz2, etc.), these will be unarchived before the task 746 is started. 747 748 The `Artifact` object supports the following keys: 749 750 - `GetterSource` - The path to the artifact to download. 751 752 - `RelativeDest` - An optional path to download the artifact into relative to the 753 root of the task's directory. If omitted, it will default to `local/`. 754 755 - `GetterOptions` - A `map[string]string` block of options for `go-getter`. 756 Full documentation of supported options are available 757 [here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1). 758 An example is given below: 759 760 ```json 761 { 762 "GetterOptions": { 763 "checksum": "md5:c4aa853ad2215426eb7d70a21922e794", 764 765 "aws_access_key_id": "<id>", 766 "aws_access_key_secret": "<secret>", 767 "aws_access_token": "<token>" 768 } 769 } 770 ``` 771 772 An example of downloading and unzipping an archive is as simple as: 773 774 ```json 775 { 776 "Artifacts": [ 777 { 778 "GetterSource": "https://example.com/my.zip", 779 "GetterOptions": { 780 "checksum": "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3" 781 } 782 } 783 ] 784 } 785 ``` 786 787 #### S3 examples 788 789 S3 has several different types of addressing and more detail can be found 790 [here](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro) 791 792 S3 region specific endpoints can be found 793 [here](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) 794 795 Path based style: 796 797 ```json 798 { 799 "Artifacts": [ 800 { 801 "GetterSource": "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz", 802 } 803 ] 804 } 805 ``` 806 807 or to override automatic detection in the URL, use the S3-specific syntax 808 809 ```json 810 { 811 "Artifacts": [ 812 { 813 "GetterSource": "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz", 814 } 815 ] 816 } 817 ``` 818 819 Virtual hosted based style 820 821 ```json 822 { 823 "Artifacts": [ 824 { 825 "GetterSource": "my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz", 826 } 827 ] 828 } 829 ``` 830 831 ### Template 832 833 The `Template` block instantiates an instance of a template renderer. This 834 creates a convenient way to ship configuration files that are populated from 835 environment variables, Consul data, Vault secrets, or just general 836 configurations within a Nomad task. 837 838 Nomad utilizes a tool called [Consul Template][ct]. Since Nomad v0.5.3, the 839 template can reference [Nomad's runtime environment variables][env]. For a full 840 list of the API template functions, please refer to the [Consul Template 841 README][ct]. 842 843 844 `Template` object supports following attributes: 845 846 - `ChangeMode` - Specifies the behavior Nomad should take if the rendered 847 template changes. The default value is `"restart"`. The possible values are: 848 849 - `"noop"` - take no action (continue running the task) 850 - `"restart"` - restart the task 851 - `"signal"` - send a configurable signal to the task 852 853 - `ChangeSignal` - Specifies the signal to send to the task as a string like 854 "SIGUSR1" or "SIGINT". This option is required if the `ChangeMode` is 855 `signal`. 856 857 - `DestPath` - Specifies the location where the resulting template should be 858 rendered, relative to the task directory. 859 860 - `EmbeddedTmpl` - Specifies the raw template to execute. One of `SourcePath` 861 or `EmbeddedTmpl` must be specified, but not both. This is useful for smaller 862 templates, but we recommend using `SourcePath` for larger templates. 863 864 - `Envvars` - Specifies the template should be read back as environment 865 variables for the task. 866 867 - `LeftDelim` - Specifies the left delimiter to use in the template. The default 868 is "{{" for some templates, it may be easier to use a different delimiter that 869 does not conflict with the output file itself. 870 871 - `Perms` - Specifies the rendered template's permissions. File permissions are 872 given as octal of the Unix file permissions `rwxrwxrwx`. 873 874 - `RightDelim` - Specifies the right delimiter to use in the template. The default 875 is "}}" for some templates, it may be easier to use a different delimiter that 876 does not conflict with the output file itself. 877 878 - `SourcePath` - Specifies the path to the template to be rendered. `SourcePath` 879 is mutually exclusive with `EmbeddedTmpl` attribute. The source can be fetched 880 using an [`Artifact`](#artifact) resource. The template must exist on the 881 machine prior to starting the task; it is not possible to reference a template 882 inside of a Docker container, for example. 883 884 - `Splay` - Specifies a random amount of time to wait between 0 ms and the given 885 splay value before invoking the change mode. Should be specified in 886 nanoseconds. 887 888 - `VaultGrace` - Specifies the grace period between lease renewal and secret 889 re-acquisition. When renewing a secret, if the remaining lease is less than or 890 equal to the configured grace, the template will request a new credential. 891 This prevents Vault from revoking the secret at its expiration and the task 892 having a stale secret. If the grace is set to a value that is higher than your 893 default TTL or max TTL, the template will always read a new secret. If the 894 task defines several templates, the `vault_grace` will be set to the lowest 895 value across all the templates. 896 897 ```json 898 { 899 "Templates": [ 900 { 901 "SourcePath": "local/config.conf.tpl", 902 "DestPath": "local/config.conf", 903 "EmbeddedTmpl": "", 904 "ChangeMode": "signal", 905 "ChangeSignal": "SIGUSR1", 906 "Splay": 5000000000 907 } 908 ] 909 } 910 ``` 911 912 [ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp" 913 [drain]: /docs/commands/node/drain.html 914 [env]: /docs/runtime/environment.html "Nomad Runtime Environment"