github.com/dkerwin/nomad@v0.3.3-0.20160525181927-74554135514b/website/source/docs/jobspec/json.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "JSON Job Specification" 4 sidebar_current: "docs-jobspec-json-syntax" 5 description: |- 6 Learn about the Job specification used to submit jobs to Nomad in JSON. 7 --- 8 9 # Job Specification 10 11 Jobs can be specified either in [HCL](https://github.com/hashicorp/hcl) or JSON. 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 `nomad run -output <job.nomad>` 14 which will emit a JSON version of the job. 15 16 ## JSON Syntax 17 18 Below is an example of a JSON object that submits a `Periodic` job to Nomad: 19 20 ``` 21 { 22 "Job": { 23 "Region": "global", 24 "ID": "example", 25 "Name": "example", 26 "Type": "batch", 27 "Priority": 50, 28 "AllAtOnce": false, 29 "Datacenters": [ 30 "dc1" 31 ], 32 "Constraints": [ 33 { 34 "LTarget": "${attr.kernel.name}", 35 "RTarget": "linux", 36 "Operand": "=" 37 } 38 ], 39 "TaskGroups": [ 40 { 41 "Name": "cache", 42 "Count": 1, 43 "Constraints": null, 44 "Tasks": [ 45 { 46 "Name": "redis", 47 "Driver": "docker", 48 "User": "foo-user", 49 "Config": { 50 "image": "redis:latest", 51 "port_map": [ 52 { 53 "db": 6379 54 } 55 ] 56 }, 57 "Constraints": null, 58 "Env": { 59 "foo": "bar", 60 "baz": "pipe" 61 } 62 "Services": [ 63 { 64 "Name": "cache-redis", 65 "Tags": [ 66 "global", 67 "cache" 68 ], 69 "PortLabel": "db", 70 "Checks": [ 71 { 72 "Id": "", 73 "Name": "alive", 74 "Type": "tcp", 75 "Command": "", 76 "Args": null, 77 "Path": "", 78 "Protocol": "", 79 "Interval": 10000000000, 80 "Timeout": 2000000000 81 } 82 ] 83 } 84 ], 85 "Resources": { 86 "CPU": 500, 87 "MemoryMB": 256, 88 "DiskMB": 300, 89 "IOPS": 0, 90 "Networks": [ 91 { 92 "ReservedPorts": [ 93 { 94 "Label": "rpc", 95 "Value": 25566 96 } 97 ], 98 "DynamicPorts": [ 99 { 100 "Label": "db", 101 } 102 ], 103 "MBits": 10 104 } 105 ] 106 }, 107 "Meta": { 108 "foo": "bar", 109 "baz": "pipe" 110 }, 111 "KillTimeout": 5000000000, 112 "LogConfig": { 113 "MaxFiles": 10, 114 "MaxFileSizeMB": 10 115 }, 116 "Artifacts": [ 117 { 118 "GetterSource": "http://foo.com/artifact.tar.gz", 119 "GetterOptions": { 120 "checksum": "md5:c4aa853ad2215426eb7d70a21922e794" 121 }, 122 "RelativeDest": "local/" 123 } 124 ] 125 } 126 ], 127 "RestartPolicy": { 128 "Interval": 300000000000, 129 "Attempts": 10, 130 "Delay": 25000000000, 131 "Mode": "delay" 132 }, 133 "Meta": { 134 "foo": "bar", 135 "baz": "pipe" 136 } 137 } 138 ], 139 "Update": { 140 "Stagger": 10000000000, 141 "MaxParallel": 1 142 }, 143 "Periodic": { 144 "Enabled": true, 145 "Spec": "* * * * *", 146 "SpecType": "cron", 147 "ProhibitOverlap": true 148 }, 149 "Meta": { 150 "foo": "bar", 151 "baz": "pipe" 152 } 153 } 154 } 155 ``` 156 157 ## Syntax Reference 158 159 Following is a syntax reference for the possible keys that are supported 160 and their default values if any for each type of object. 161 162 ### Job 163 164 The `Job` object supports the following keys: 165 166 * `AllAtOnce` - Controls if the entire set of tasks in the job must 167 be placed atomically or if they can be scheduled incrementally. 168 This should only be used for special circumstances. Defaults to `false`. 169 170 * `Constraints` - A list to define additional constraints where a job can be 171 run. See the constraint reference for more details. 172 173 * `Datacenters` - A list of datacenters in the region which are eligible 174 for task placement. This must be provided, and does not have a default. 175 176 * `TaskGroups` - A list to define additional task groups. See the task group 177 reference for more details. 178 179 * `Meta` - Annotates the job with opaque metadata. 180 181 * `Priority` - Specifies the job priority which is used to prioritize 182 scheduling and access to resources. Must be between 1 and 100 inclusively, 183 and defaults to 50. 184 185 * `Region` - The region to run the job in, defaults to "global". 186 187 * `Type` - Specifies the job type and switches which scheduler 188 is used. Nomad provides the `service`, `system` and `batch` schedulers, 189 and defaults to `service`. To learn more about each scheduler type visit 190 [here](/docs/jobspec/schedulers.html) 191 192 * `Update` - Specifies the task's update strategy. When omitted, rolling 193 updates are disabled. The `Update` object supports the following attributes: 194 195 * `MaxParallel` - `MaxParallel` is given as an integer value and specifies 196 the number of tasks that can be updated at the same time. 197 198 * `Stagger` - `Stagger` introduces a delay between sets of task updates and 199 is given in nanoseconds. 200 201 An example `Update` block: 202 203 ``` 204 "Update": { 205 "MaxParallel" : 3, 206 "Stagger" : 10000000000 207 } 208 ``` 209 210 * `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates 211 or intervals. The periodic expression is always evaluated in the UTC 212 timezone to ensure consistent evaluation when Nomad Servers span multiple 213 time zones. The `Periodic` object supports the following attributes: 214 215 * `Enabled` - `Enabled` determines whether the periodic job will spawn child 216 jobs. 217 218 * `SpecType` - `SpecType` determines how Nomad is going to interpret the 219 periodic expression. `cron` is the only supported `SpecType` currently. 220 221 * `Spec` - A cron expression configuring the interval the job is launched 222 at. Supports predefined expressions such as "@daily" and "@weekly" See 223 [here](https://github.com/gorhill/cronexpr#implementation) for full 224 documentation of supported cron specs and the predefined expressions. 225 226 * <a id="prohibit_overlap">`ProhibitOverlap`</a> - `ProhibitOverlap` can 227 be set to true to enforce that the periodic job doesn't spawn a new 228 instance of the job if any of the previous jobs are still running. It is 229 defaulted to false. 230 231 An example `periodic` block: 232 233 ``` 234 "Periodic": { 235 "Spec": "*/15 * * * * *" 236 "SpecType": "cron", 237 "Enabled": true, 238 "ProhibitOverlap": true 239 } 240 ``` 241 242 ### Task Group 243 244 `TaskGroups` is a list of `TaskGroup` objects, each supports the following 245 attributes: 246 247 * `Constraints` - This is a list of `Constraint` objects. See the constraint 248 reference for more details. 249 250 * `Count` - Specifies the number of the task groups that should 251 be running. Must be non-negative, defaults to one. 252 253 * `Meta` - A key/value map that annotates the task group with opaque metadata. 254 255 * `Name` - The name of the task group. Must be specified. 256 257 * `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group. 258 If omitted, a default policy for batch and non-batch jobs is used based on the 259 job type. See the restart policy reference for more details. 260 261 * `Tasks` - A list of `Task` object that are part of the task group. 262 263 ### Task 264 265 The `Task` object supports the following keys: 266 267 * `Artifacts` - `Artifacts` is a list of `Artifact` objects which define 268 artifacts to be downloaded before the task is run. See the artifacts 269 reference for more details. 270 271 * `Config` - A map of key/value configuration passed into the driver 272 to start the task. The details of configurations are specific to 273 each driver. 274 275 * `Constraints` - This is a list of `Constraint` objects. See the constraint 276 reference for more details. 277 278 * `Driver` - Specifies the task driver that should be used to run the 279 task. See the [driver documentation](/docs/drivers/index.html) for what 280 is available. Examples include `docker`, `qemu`, `java`, and `exec`. 281 282 * `Env` - A map of key/value representing environment variables that 283 will be passed along to the running process. Nomad variables are 284 interpreted when set in the environment variable values. See the table of 285 interpreted variables [here](/docs/jobspec/interpreted.html). 286 287 For example the below environment map will be reinterpreted: 288 289 ``` 290 "Env": { 291 "NODE_CLASS" : "${nomad.class}" 292 } 293 ``` 294 295 * `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be 296 used to configure the time between signaling a task it will be killed and 297 actually killing it. Drivers first sends a task the `SIGINT` signal and then 298 sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has 299 elapsed. 300 301 * `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr` 302 buffers of a Task. See the log rotation reference below for more details. 303 304 * `Meta` - Annotates the task group with opaque metadata. 305 306 * `Name` - The name of the task. This field is required. 307 308 * `Resources` - Provides the resource requirements of the task. 309 See the resources reference for more details. 310 311 * `Services` - `Services` is a list of `Service` objects. Nomad integrates with 312 Consul for service discovery. A `Service` object represents a routable and 313 discoverable service on the network. Nomad automatically registers when a task 314 is started and de-registers it when the task transitions to the dead state. 315 [Click here](/docs/jobspec/servicediscovery.html) to learn more about 316 services. Below is the fields in the `Service` object: 317 318 * `Name`: Nomad automatically determines the name of a Task. By default the 319 name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can 320 explicitly name the service by specifying this option. If multiple 321 services are defined for a Task then only one task can have the default 322 name, all the services have to be explicitly named. Users can add the 323 following to the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, 324 `${BASE}`. Nomad will replace them with the appropriate value of the 325 Job, Task Group, and Task names while registering the Job. `${BASE}` 326 expands to `${JOB}-${TASKGROUP}-${TASK}`. Names must be adhere to 327 [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are 328 limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be 329 less than 64 characters in length. 330 331 * `Tags`: A list of string tags associated with this Service. String 332 interpolation is supported in tags. 333 334 * `PortLabel`: `PortLabel` is an optional string and is used to associate 335 the port with the service. If specified, the port label must match one 336 defined in the resources block. This could be a label to either a 337 dynamic or a static port. If an incorrect port label is specified, Nomad 338 doesn't register the IP:Port with Consul. 339 340 * `Checks`: `Checks` is an array of check objects. A check object defines a 341 health check associated with the service. Nomad supports the `script`, 342 `http` and `tcp` Consul Checks. Script checks are not supported for the 343 qemu driver since the Nomad client doesn't have access to the file system 344 of a tasks using the Qemu driver. 345 346 * `Type`: This indicates the check types supported by Nomad. Valid 347 options are currently `script`, `http` and `tcp`. 348 349 * `Name`: The name of the health check. 350 351 * `Interval`: This indicates the frequency of the health checks that 352 Consul will perform. 353 354 * `Timeout`: This indicates how long Consul will wait for a health 355 check query to succeed. 356 357 * `Path`:The path of the http endpoint which Consul will query to query 358 the health of a service if the type of the check is `http`. Nomad 359 will add the IP of the service and the port, users are only required 360 to add the relative URL of the health check endpoint. 361 362 * `Protocol`: This indicates the protocol for the http checks. Valid 363 options are `http` and `https`. We default it to `http` 364 365 * `Command`: This is the command that the Nomad client runs for doing 366 script based health check. 367 368 * `Args`: Additional arguments to the `command` for script based health 369 checks. 370 371 372 * `User` - Set the user that will run the task. It defaults to the same user 373 the Nomad client is being run as. 374 375 ### Resources 376 377 The `Resources` object supports the following keys: 378 379 * `CPU` - The CPU required in MHz. 380 381 * `DiskMB` - The disk required in MB. 382 383 * `IOPS` - The number of IOPS required given as a weight between 10-1000. 384 385 * `MemoryMB` - The memory required in MB. 386 387 * `Networks` - A list of network objects. 388 389 The Network object supports the following keys: 390 391 * `MBits` - The number of MBits in bandwidth required. 392 393 Nomad can allocate two types of ports to a task - Dynamic and Static/Reserved 394 ports. A network object allows the user to specify a list of `DynamicPorts` and 395 `ReservedPorts`. Each object supports the following attributes: 396 397 * `Value` - The port number for static ports. If the port is dynamic, then this 398 attribute is ignored. 399 * `Label` - The label to annotate a port so that it can be referred in the 400 service discovery block or environment variables. 401 402 ### Restart Policy 403 404 The `RestartPolicy` object supports the following keys: 405 406 * `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`. 407 408 * `Interval` - `Interval` is a time duration that is specified in nanoseconds. 409 The `Interval` begins when the first task starts and ensures that only 410 `Attempts` number of restarts happens within it. If more than `Attempts` 411 number of failures happen, behavior is controlled by `Mode`. 412 413 * `Delay` - A duration to wait before restarting a task. It is specified in 414 nanoseconds. A random jitter of up to 25% is added to the delay. 415 416 * `Mode` - `Mode` is given as a string and controls the behavior when the task 417 fails more than `Attempts` times in an `Interval`. Possible values are listed 418 below: 419 420 * `delay` - `delay` will delay the next restart until the next `Interval` is 421 reached. 422 423 * `fail` - `fail` will not restart the task again. 424 425 ### Constraint 426 427 The `Constraint` object supports the following keys: 428 429 * `LTarget` - Specifies the attribute to examine for the 430 constraint. See the table of attributes [here](/docs/jobspec/interpreted.html#interpreted_node_vars). 431 432 * `RTarget` - Specifies the value to compare the attribute against. 433 This can be a literal value, another attribute or a regular expression if 434 the `Operator` is in "regexp" mode. 435 436 * `Operator` - `Operator` if omitted defaults to `==` and an take on the 437 following values: 438 439 * `regexp` - Allows the `RTarget` to be a regular expression to be matched. 440 441 * `distinct_host` - If set, the scheduler will not co-locate any task groups on the same 442 machine. This can be specified as a job constraint which applies the 443 constraint to all task groups in the job, or as a task group constraint which 444 scopes the effect to just that group. 445 446 Placing the constraint at both the job level and at the task group level is 447 redundant since when placed at the job level, the constraint will be applied 448 to all task groups. When specified, `LTarget` and `RTarget` should be 449 omitted. 450 451 * Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The 452 ordering is compared lexically. 453 454 ### Log Rotation 455 456 The `LogConfig` object configures the log rotation policy for a task's `stdout` and 457 `stderr`. The `LogConfig` object supports the following attributes: 458 459 * `MaxFiles` - The maximum number of rotated files Nomad will retain for 460 `stdout` and `stderr`, each tracked individually. 461 462 * `MaxFileSizeMB` - The size of each rotated file. The size is specified in 463 `MB`. 464 465 If the amount of disk resource requested for the task is less than the total 466 amount of disk space needed to retain the rotated set of files, Nomad will return 467 a validation error when a job is submitted. 468 469 ``` 470 "LogConfig: { 471 "MaxFiles": 3, 472 "MaxFileSizeMB": 10 473 } 474 ``` 475 476 In the above example we have asked Nomad to retain 3 rotated files for both 477 `stderr` and `stdout` and size of each file is 10MB. The minimum disk space that 478 would be required for the task would be 60MB. 479 480 ### Artifact 481 482 Nomad downloads artifacts using 483 [`go-getter`](https://github.com/hashicorp/go-getter). The `go-getter` library 484 allows downloading of artifacts from various sources using a URL as the input 485 source. The key/value pairs given in the `options` block map directly to 486 parameters appended to the supplied `source` url. These are then used by 487 `go-getter` to appropriately download the artifact. `go-getter` also has a CLI 488 tool to validate its URL and can be used to check if the Nomad `artifact` is 489 valid. 490 491 Nomad allows downloading `http`, `https`, and `S3` artifacts. If these artifacts 492 are archives (zip, tar.gz, bz2, etc.), these will be unarchived before the task 493 is started. 494 495 The `Artifact` object supports the following keys: 496 497 * `GetterSource` - The path to the artifact to download. 498 499 * `RelativeDest` - An optional path to download the artifact into relative to the 500 root of the task's directory. If omitted, it will default to `local/`. 501 502 * `GetterOptions` - A `map[string]string` block of options for `go-getter`. 503 Full documentation of supported options are available 504 [here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1). 505 An example is given below: 506 507 ``` 508 "GetterOptions": { 509 "checksum": "md5:c4aa853ad2215426eb7d70a21922e794", 510 511 "aws_access_key_id": "<id>", 512 "aws_access_key_secret": "<secret>", 513 "aws_access_token": "<token>" 514 } 515 ``` 516 517 An example of downloading and unzipping an archive is as simple as: 518 519 ``` 520 "Artifacts": [ 521 { 522 # The archive will be extracted before the task is run, making 523 # it easy to ship configurations with your binary. 524 "GetterSource": "https://example.com/my.zip", 525 526 "GetterOptions": { 527 "checksum": "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3" 528 } 529 } 530 ] 531 ```