2016-02-21 18:19:37 +00:00
|
|
|
---
|
2016-10-28 00:36:26 +00:00
|
|
|
layout: "http"
|
|
|
|
page_title: "HTTP API: JSON Job Specification"
|
|
|
|
sidebar_current: "docs-http-json-jobs"
|
2016-02-21 18:19:37 +00:00
|
|
|
description: |-
|
2016-10-28 03:01:11 +00:00
|
|
|
Jobs can also be specified via the HTTP API using a JSON format. This guide
|
|
|
|
discusses the job specification in JSON format.
|
2016-02-21 18:19:37 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# Job Specification
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
This guide covers the JSON syntax for submitting jobs to Nomad. A useful command
|
2016-10-28 03:01:11 +00:00
|
|
|
for generating valid JSON versions of HCL jobs is
|
|
|
|
`nomad run -output <job.nomad>` which will emit a JSON version of the job.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
## JSON Syntax
|
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
Below is an example of a JSON object that submits a `periodic` job to Nomad:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
2016-02-21 18:19:37 +00:00
|
|
|
{
|
2016-10-03 22:23:50 +00:00
|
|
|
"Job":{
|
|
|
|
"Region":"global",
|
|
|
|
"ID":"example",
|
|
|
|
"Name":"example",
|
|
|
|
"Type":"batch",
|
|
|
|
"Priority":50,
|
|
|
|
"AllAtOnce":false,
|
|
|
|
"Datacenters":[
|
|
|
|
"dc1"
|
|
|
|
],
|
|
|
|
"Constraints":[
|
|
|
|
{
|
|
|
|
"LTarget":"${attr.kernel.name}",
|
|
|
|
"RTarget":"linux",
|
|
|
|
"Operand":"="
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"TaskGroups":[
|
|
|
|
{
|
|
|
|
"Name":"cache",
|
|
|
|
"Count":1,
|
|
|
|
"Constraints":null,
|
|
|
|
"Tasks":[
|
|
|
|
{
|
|
|
|
"Name":"redis",
|
|
|
|
"Driver":"docker",
|
|
|
|
"User":"foo-user",
|
|
|
|
"Config":{
|
|
|
|
"image":"redis:latest",
|
|
|
|
"port_map":[
|
|
|
|
{
|
|
|
|
"db":6379
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
"Constraints":null,
|
|
|
|
"Env":{
|
|
|
|
"foo":"bar",
|
|
|
|
"baz":"pipe"
|
|
|
|
},
|
|
|
|
"Services":[
|
|
|
|
{
|
|
|
|
"Name":"cache-redis",
|
|
|
|
"Tags":[
|
|
|
|
"global",
|
|
|
|
"cache"
|
|
|
|
],
|
|
|
|
"PortLabel":"db",
|
|
|
|
"Checks":[
|
|
|
|
{
|
|
|
|
"Id":"",
|
|
|
|
"Name":"alive",
|
|
|
|
"Type":"tcp",
|
|
|
|
"Command":"",
|
|
|
|
"Args":null,
|
|
|
|
"Path":"",
|
|
|
|
"Protocol":"",
|
|
|
|
"Interval":10000000000,
|
|
|
|
"Timeout":2000000000
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
],
|
2016-12-15 00:49:38 +00:00
|
|
|
"Vault": {
|
|
|
|
"Policies": ["policy-name"],
|
|
|
|
"Env": true,
|
|
|
|
"ChangeMode": "restart",
|
|
|
|
"ChangeSignal": ""
|
|
|
|
},
|
2016-10-03 22:23:50 +00:00
|
|
|
"Resources":{
|
|
|
|
"CPU":500,
|
|
|
|
"MemoryMB":256,
|
|
|
|
"IOPS":0,
|
|
|
|
"Networks":[
|
|
|
|
{
|
|
|
|
"ReservedPorts":[
|
2016-02-21 18:19:37 +00:00
|
|
|
{
|
2016-10-03 22:23:50 +00:00
|
|
|
"Label":"rpc",
|
|
|
|
"Value":25566
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
2016-10-03 22:23:50 +00:00
|
|
|
],
|
|
|
|
"DynamicPorts":[
|
|
|
|
{
|
|
|
|
"Label":"db"
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"MBits":10
|
2016-04-14 23:47:24 +00:00
|
|
|
}
|
2016-10-03 22:23:50 +00:00
|
|
|
]
|
|
|
|
},
|
|
|
|
"Meta":{
|
|
|
|
"foo":"bar",
|
|
|
|
"baz":"pipe"
|
|
|
|
},
|
|
|
|
"KillTimeout":5000000000,
|
|
|
|
"LogConfig":{
|
|
|
|
"MaxFiles":10,
|
|
|
|
"MaxFileSizeMB":10
|
|
|
|
},
|
2017-01-24 13:46:17 +00:00
|
|
|
"Templates":[
|
|
|
|
{
|
|
|
|
"SourcePath": "local/config.conf.tpl",
|
|
|
|
"DestPath": "local/config.conf",
|
2017-01-24 17:12:42 +00:00
|
|
|
"EmbeddedTmpl": "",
|
2017-01-24 13:46:17 +00:00
|
|
|
"ChangeMode": "signal",
|
|
|
|
"ChangeSignal": "SIGUSR1",
|
|
|
|
"Splay": 5000000000
|
|
|
|
}
|
|
|
|
],
|
2016-10-03 22:23:50 +00:00
|
|
|
"Artifacts":[
|
|
|
|
{
|
|
|
|
"GetterSource":"http://foo.com/artifact.tar.gz",
|
|
|
|
"GetterOptions":{
|
|
|
|
"checksum":"md5:c4aa853ad2215426eb7d70a21922e794"
|
|
|
|
},
|
|
|
|
"RelativeDest":"local/"
|
|
|
|
}
|
2017-01-26 06:15:00 +00:00
|
|
|
],
|
|
|
|
"DispatchPayload": {
|
|
|
|
"File": "config.json"
|
|
|
|
}
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-04-14 23:47:24 +00:00
|
|
|
],
|
2016-10-03 22:23:50 +00:00
|
|
|
"RestartPolicy":{
|
|
|
|
"Interval":300000000000,
|
|
|
|
"Attempts":10,
|
|
|
|
"Delay":25000000000,
|
|
|
|
"Mode":"delay"
|
2016-04-14 23:47:24 +00:00
|
|
|
},
|
2016-10-03 22:23:50 +00:00
|
|
|
"Meta":{
|
|
|
|
"foo":"bar",
|
|
|
|
"baz":"pipe"
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
|
|
|
],
|
|
|
|
"Update":{
|
|
|
|
"Stagger":10000000000,
|
|
|
|
"MaxParallel":1
|
|
|
|
},
|
|
|
|
"Periodic":{
|
|
|
|
"Enabled":true,
|
|
|
|
"Spec":"* * * * *",
|
|
|
|
"SpecType":"cron",
|
|
|
|
"ProhibitOverlap":true
|
|
|
|
},
|
|
|
|
"Meta":{
|
|
|
|
"foo":"bar",
|
|
|
|
"baz":"pipe"
|
2017-01-26 06:15:00 +00:00
|
|
|
},
|
|
|
|
"ParameterizedJob": {
|
|
|
|
"Payload": "required",
|
|
|
|
"MetaRequired": [
|
|
|
|
"foo"
|
|
|
|
],
|
|
|
|
"MetaOptional": [
|
|
|
|
"bar"
|
|
|
|
]
|
|
|
|
},
|
|
|
|
"Payload": null
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Syntax Reference
|
|
|
|
|
|
|
|
Following is a syntax reference for the possible keys that are supported
|
|
|
|
and their default values if any for each type of object.
|
|
|
|
|
|
|
|
### Job
|
|
|
|
|
|
|
|
The `Job` object supports the following keys:
|
|
|
|
|
|
|
|
* `AllAtOnce` - Controls if the entire set of tasks in the job must
|
|
|
|
be placed atomically or if they can be scheduled incrementally.
|
|
|
|
This should only be used for special circumstances. Defaults to `false`.
|
|
|
|
|
|
|
|
* `Constraints` - A list to define additional constraints where a job can be
|
|
|
|
run. See the constraint reference for more details.
|
|
|
|
|
|
|
|
* `Datacenters` - A list of datacenters in the region which are eligible
|
|
|
|
for task placement. This must be provided, and does not have a default.
|
|
|
|
|
|
|
|
* `TaskGroups` - A list to define additional task groups. See the task group
|
|
|
|
reference for more details.
|
|
|
|
|
|
|
|
* `Meta` - Annotates the job with opaque metadata.
|
|
|
|
|
2017-01-26 06:15:00 +00:00
|
|
|
* `ParameterizedJob` - Specifies the job as a paramterized job such that it can
|
|
|
|
be dispatched against. The `ParamaterizedJob` object supports the following
|
|
|
|
attributes:
|
|
|
|
|
|
|
|
* `MetaOptional` - Specifies the set of metadata keys that may be provided
|
|
|
|
when dispatching against the job as a string array.
|
|
|
|
|
|
|
|
* `MetaRequired` - Specifies the set of metadata keys that must be provided
|
|
|
|
when dispatching against the job as a string array.
|
|
|
|
|
|
|
|
* `Payload` - Specifies the requirement of providing a payload when
|
|
|
|
dispatching against the parameterized job. The options for this field are
|
2017-01-26 19:31:47 +00:00
|
|
|
"optional", "required" and "forbidden". The default value is "optional".
|
2017-01-26 06:15:00 +00:00
|
|
|
|
|
|
|
* `Payload` - The payload may not be set when submitting a job but may appear in
|
|
|
|
a dispatched job. The `Payload` will be a base64 encoded string containing the
|
2017-01-26 19:31:47 +00:00
|
|
|
payload that the job was dispatched with. The `payload` has a **maximum size
|
|
|
|
of 16 KiB**.
|
2017-01-26 06:15:00 +00:00
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
* `Priority` - Specifies the job priority which is used to prioritize
|
|
|
|
scheduling and access to resources. Must be between 1 and 100 inclusively,
|
|
|
|
and defaults to 50.
|
|
|
|
|
|
|
|
* `Region` - The region to run the job in, defaults to "global".
|
|
|
|
|
|
|
|
* `Type` - Specifies the job type and switches which scheduler
|
|
|
|
is used. Nomad provides the `service`, `system` and `batch` schedulers,
|
|
|
|
and defaults to `service`. To learn more about each scheduler type visit
|
2016-10-28 00:36:26 +00:00
|
|
|
[here](/docs/runtime/schedulers.html)
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
* `Update` - Specifies the task's update strategy. When omitted, rolling
|
|
|
|
updates are disabled. The `Update` object supports the following attributes:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
* `MaxParallel` - `MaxParallel` is given as an integer value and specifies
|
|
|
|
the number of tasks that can be updated at the same time.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
* `Stagger` - `Stagger` introduces a delay between sets of task updates and
|
|
|
|
is given in nanoseconds.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
An example `Update` block:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Update": {
|
2016-02-21 18:19:37 +00:00
|
|
|
"MaxParallel" : 3,
|
2016-04-14 23:47:24 +00:00
|
|
|
"Stagger" : 10000000000
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
* `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates
|
2016-04-12 16:47:25 +00:00
|
|
|
or intervals. The periodic expression is always evaluated in the UTC
|
|
|
|
timezone to ensure consistent evaluation when Nomad Servers span multiple
|
2016-06-28 17:33:48 +00:00
|
|
|
time zones. The `Periodic` object is optional and supports the following attributes:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
* `Enabled` - `Enabled` determines whether the periodic job will spawn child
|
|
|
|
jobs.
|
|
|
|
|
2017-02-15 22:37:06 +00:00
|
|
|
* `time_zone` - Specifies the time zone to evaluate the next launch interval
|
|
|
|
against. This is useful when wanting to account for day light savings in
|
|
|
|
various time zones. The time zone must be parsable by Golang's
|
|
|
|
[LoadLocation](https://golang.org/pkg/time/#LoadLocation). The default is
|
|
|
|
UTC.
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
* `SpecType` - `SpecType` determines how Nomad is going to interpret the
|
|
|
|
periodic expression. `cron` is the only supported `SpecType` currently.
|
|
|
|
|
|
|
|
* `Spec` - A cron expression configuring the interval the job is launched
|
|
|
|
at. Supports predefined expressions such as "@daily" and "@weekly" See
|
|
|
|
[here](https://github.com/gorhill/cronexpr#implementation) for full
|
|
|
|
documentation of supported cron specs and the predefined expressions.
|
|
|
|
|
|
|
|
* <a id="prohibit_overlap">`ProhibitOverlap`</a> - `ProhibitOverlap` can
|
|
|
|
be set to true to enforce that the periodic job doesn't spawn a new
|
|
|
|
instance of the job if any of the previous jobs are still running. It is
|
|
|
|
defaulted to false.
|
|
|
|
|
|
|
|
An example `periodic` block:
|
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Periodic": {
|
|
|
|
"Spec": "*/15 * * * * *"
|
|
|
|
"SpecType": "cron",
|
|
|
|
"Enabled": true,
|
|
|
|
"ProhibitOverlap": true
|
|
|
|
}
|
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Task Group
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
`TaskGroups` is a list of `TaskGroup` objects, each supports the following
|
2016-02-21 18:19:37 +00:00
|
|
|
attributes:
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `Constraints` - This is a list of `Constraint` objects. See the constraint
|
|
|
|
reference for more details.
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
* `Count` - Specifies the number of the task groups that should
|
2016-04-14 23:47:24 +00:00
|
|
|
be running. Must be non-negative, defaults to one.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-28 00:36:26 +00:00
|
|
|
* `Meta` - A key-value map that annotates the task group with opaque metadata.
|
2016-05-09 23:23:25 +00:00
|
|
|
|
|
|
|
* `Name` - The name of the task group. Must be specified.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
* `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group.
|
|
|
|
If omitted, a default policy for batch and non-batch jobs is used based on the
|
2016-08-03 13:42:51 +00:00
|
|
|
job type. See the [restart policy reference](#restart_policy) for more details.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-04-07 19:49:53 +00:00
|
|
|
* `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the
|
|
|
|
[ephemeral disk reference](#ephemeral_disk) for more details.
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `Tasks` - A list of `Task` object that are part of the task group.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
### Task
|
|
|
|
|
|
|
|
The `Task` object supports the following keys:
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `Artifacts` - `Artifacts` is a list of `Artifact` objects which define
|
|
|
|
artifacts to be downloaded before the task is run. See the artifacts
|
|
|
|
reference for more details.
|
|
|
|
|
2016-10-28 00:36:26 +00:00
|
|
|
* `Config` - A map of key-value configuration passed into the driver
|
2016-05-09 23:23:25 +00:00
|
|
|
to start the task. The details of configurations are specific to
|
|
|
|
each driver.
|
|
|
|
|
|
|
|
* `Constraints` - This is a list of `Constraint` objects. See the constraint
|
|
|
|
reference for more details.
|
|
|
|
|
2017-01-26 06:15:00 +00:00
|
|
|
- `DispatchPayload` - Configures the task to have access to dispatch payloads.
|
|
|
|
The `DispatchPayload` object supports the following attributes:
|
|
|
|
|
|
|
|
* `File` - Specifies the file name to write the content of dispatch payload
|
|
|
|
to. The file is written relative to the task's local directory.
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
* `Driver` - Specifies the task driver that should be used to run the
|
|
|
|
task. See the [driver documentation](/docs/drivers/index.html) for what
|
|
|
|
is available. Examples include `docker`, `qemu`, `java`, and `exec`.
|
|
|
|
|
2016-10-28 00:36:26 +00:00
|
|
|
* `Env` - A map of key-value representing environment variables that
|
2016-05-09 23:23:25 +00:00
|
|
|
will be passed along to the running process. Nomad variables are
|
|
|
|
interpreted when set in the environment variable values. See the table of
|
2016-10-28 00:36:26 +00:00
|
|
|
interpreted variables [here](/docs/runtime/interpolation.html).
|
2016-04-14 23:47:24 +00:00
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
For example the below environment map will be reinterpreted:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Env": {
|
|
|
|
"NODE_CLASS" : "${nomad.class}"
|
|
|
|
}
|
|
|
|
}
|
2016-05-09 23:23:25 +00:00
|
|
|
```
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be
|
|
|
|
used to configure the time between signaling a task it will be killed and
|
|
|
|
actually killing it. Drivers first sends a task the `SIGINT` signal and then
|
|
|
|
sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has
|
2016-09-12 16:53:57 +00:00
|
|
|
elapsed. The default `KillTimeout` is 5 seconds.
|
2016-05-09 23:23:25 +00:00
|
|
|
|
2017-02-13 18:18:34 +00:00
|
|
|
* `leader` - Specifies whether the task is the leader task of the task group. If
|
|
|
|
set to true, when the leader task completes, all other tasks within the task
|
|
|
|
group will be gracefully shutdown.
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr`
|
|
|
|
buffers of a Task. See the log rotation reference below for more details.
|
|
|
|
|
|
|
|
* `Meta` - Annotates the task group with opaque metadata.
|
|
|
|
|
|
|
|
* `Name` - The name of the task. This field is required.
|
|
|
|
|
|
|
|
* `Resources` - Provides the resource requirements of the task.
|
|
|
|
See the resources reference for more details.
|
|
|
|
|
|
|
|
* `Services` - `Services` is a list of `Service` objects. Nomad integrates with
|
|
|
|
Consul for service discovery. A `Service` object represents a routable and
|
|
|
|
discoverable service on the network. Nomad automatically registers when a task
|
|
|
|
is started and de-registers it when the task transitions to the dead state.
|
2016-10-28 00:36:26 +00:00
|
|
|
[Click here](/docs/service-discovery/index.html) to learn more about
|
2016-05-09 23:23:25 +00:00
|
|
|
services. Below is the fields in the `Service` object:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-11 19:52:50 +00:00
|
|
|
* `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
|
|
|
|
`${TASKGROUP}` and `${TASK}` by the name of the job, task group or task,
|
|
|
|
respectively. `${BASE}` expands to the equivalent of
|
|
|
|
`${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service.
|
|
|
|
Each service defined for a given task must have a distinct name, so if
|
|
|
|
a task has multiple services only one of them can use the default name
|
|
|
|
and the others must be explicitly named. Names must adhere to
|
2016-04-22 18:12:02 +00:00
|
|
|
[RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
|
|
|
|
limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
|
|
|
|
less than 64 characters in length.
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `Tags`: A list of string tags associated with this Service. String
|
|
|
|
interpolation is supported in tags.
|
2016-04-22 18:12:02 +00:00
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `PortLabel`: `PortLabel` is an optional string and is used to associate
|
2016-10-11 19:52:50 +00:00
|
|
|
a port with the service. If specified, the port label must match one
|
|
|
|
defined in the resources block. This could be a label of either a
|
|
|
|
dynamic or a static port.
|
2016-04-22 18:12:02 +00:00
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `Checks`: `Checks` is an array of check objects. A check object defines a
|
2016-04-22 18:12:02 +00:00
|
|
|
health check associated with the service. Nomad supports the `script`,
|
|
|
|
`http` and `tcp` Consul Checks. Script checks are not supported for the
|
|
|
|
qemu driver since the Nomad client doesn't have access to the file system
|
2016-10-11 19:52:50 +00:00
|
|
|
of a task using the Qemu driver.
|
2016-04-22 18:12:02 +00:00
|
|
|
|
|
|
|
* `Type`: This indicates the check types supported by Nomad. Valid
|
|
|
|
options are currently `script`, `http` and `tcp`.
|
|
|
|
|
|
|
|
* `Name`: The name of the health check.
|
|
|
|
|
|
|
|
* `Interval`: This indicates the frequency of the health checks that
|
|
|
|
Consul will perform.
|
|
|
|
|
|
|
|
* `Timeout`: This indicates how long Consul will wait for a health
|
|
|
|
check query to succeed.
|
|
|
|
|
2017-04-19 19:27:07 +00:00
|
|
|
* `Path`: The path of the http endpoint which Consul will query to query
|
2016-04-22 18:12:02 +00:00
|
|
|
the health of a service if the type of the check is `http`. Nomad
|
|
|
|
will add the IP of the service and the port, users are only required
|
|
|
|
to add the relative URL of the health check endpoint.
|
|
|
|
|
|
|
|
* `Protocol`: This indicates the protocol for the http checks. Valid
|
2016-10-11 19:52:50 +00:00
|
|
|
options are `http` and `https`. We default it to `http`.
|
2016-04-22 18:12:02 +00:00
|
|
|
|
|
|
|
* `Command`: This is the command that the Nomad client runs for doing
|
|
|
|
script based health check.
|
|
|
|
|
|
|
|
* `Args`: Additional arguments to the `command` for script based health
|
|
|
|
checks.
|
|
|
|
|
2017-04-19 19:27:07 +00:00
|
|
|
* `TLSSkipVerify`: If true, Consul will not attempt to verify the
|
|
|
|
certificate when performing HTTPS checks. Requires Consul >= 0.7.2.
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
* `Templates` - Specifies the set of [`Template`](#template) objects to render for the task.
|
|
|
|
Templates can be used to inject both static and dynamic configuration with
|
|
|
|
data populated from environment variables, Consul and Vault.
|
2016-04-22 18:12:02 +00:00
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `User` - Set the user that will run the task. It defaults to the same user
|
2016-06-12 21:33:45 +00:00
|
|
|
the Nomad client is being run as. This can only be set on Linux platforms.
|
2016-04-14 23:47:24 +00:00
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Resources
|
|
|
|
|
|
|
|
The `Resources` object supports the following keys:
|
|
|
|
|
|
|
|
* `CPU` - The CPU required in MHz.
|
|
|
|
|
|
|
|
* `IOPS` - The number of IOPS required given as a weight between 10-1000.
|
|
|
|
|
|
|
|
* `MemoryMB` - The memory required in MB.
|
|
|
|
|
|
|
|
* `Networks` - A list of network objects.
|
|
|
|
|
|
|
|
The Network object supports the following keys:
|
|
|
|
|
|
|
|
* `MBits` - The number of MBits in bandwidth required.
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
Nomad can allocate two types of ports to a task - Dynamic and Static/Reserved
|
|
|
|
ports. A network object allows the user to specify a list of `DynamicPorts` and
|
|
|
|
`ReservedPorts`. Each object supports the following attributes:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
* `Value` - The port number for static ports. If the port is dynamic, then this
|
|
|
|
attribute is ignored.
|
|
|
|
* `Label` - The label to annotate a port so that it can be referred in the
|
|
|
|
service discovery block or environment variables.
|
|
|
|
|
2017-04-07 19:49:53 +00:00
|
|
|
<a id="ephemeral_disk"></a>
|
|
|
|
|
|
|
|
### Ephemeral Disk
|
|
|
|
|
|
|
|
The `EphemeralDisk` object supports the following keys:
|
|
|
|
|
|
|
|
* `Migrate` - Specifies that the Nomad client should make a best-effort attempt
|
|
|
|
to migrate the data from a remote machine if placement cannot be made on the
|
|
|
|
original node. During data migration, the task will block starting until the
|
|
|
|
data migration has completed. Value is a boolean and the default is false.
|
|
|
|
|
|
|
|
* `SizeMB` - Specifies the size of the ephemeral disk in MB. Default is 300.
|
|
|
|
|
|
|
|
* `Sticky` - Specifies that Nomad should make a best-effort attempt to place the
|
|
|
|
updated allocation on the same machine. This will move the `local/` and
|
|
|
|
`alloc/data` directories to the new allocation. Value is a boolean and the
|
|
|
|
default is false.
|
|
|
|
|
2016-08-03 13:42:51 +00:00
|
|
|
<a id="restart_policy"></a>
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Restart Policy
|
|
|
|
|
|
|
|
The `RestartPolicy` object supports the following keys:
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `Interval` - `Interval` is a time duration that is specified in nanoseconds.
|
|
|
|
The `Interval` begins when the first task starts and ensures that only
|
|
|
|
`Attempts` number of restarts happens within it. If more than `Attempts`
|
|
|
|
number of failures happen, behavior is controlled by `Mode`.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
* `Delay` - A duration to wait before restarting a task. It is specified in
|
|
|
|
nanoseconds. A random jitter of up to 25% is added to the delay.
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `Mode` - `Mode` is given as a string and controls the behavior when the task
|
|
|
|
fails more than `Attempts` times in an `Interval`. Possible values are listed
|
|
|
|
below:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
* `delay` - `delay` will delay the next restart until the next `Interval` is
|
|
|
|
reached.
|
|
|
|
|
|
|
|
* `fail` - `fail` will not restart the task again.
|
|
|
|
|
|
|
|
### Constraint
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
The `Constraint` object supports the following keys:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `LTarget` - Specifies the attribute to examine for the
|
2016-10-28 00:36:26 +00:00
|
|
|
constraint. See the table of attributes [here](/docs/runtime/interpolation.html#interpreted_node_vars).
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `RTarget` - Specifies the value to compare the attribute against.
|
|
|
|
This can be a literal value, another attribute or a regular expression if
|
|
|
|
the `Operator` is in "regexp" mode.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-07-13 22:56:42 +00:00
|
|
|
* `Operand` - Specifies the test to be performed on the two targets. It takes on the
|
|
|
|
following values:
|
2016-10-03 22:23:50 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `regexp` - Allows the `RTarget` to be a regular expression to be matched.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-19 20:06:28 +00:00
|
|
|
* `set_contains` - Allows the `RTarget` to be a comma separated list of values
|
|
|
|
that should be contained in the LTarget's value.
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `distinct_host` - If set, the scheduler will not co-locate any task groups on the same
|
|
|
|
machine. This can be specified as a job constraint which applies the
|
|
|
|
constraint to all task groups in the job, or as a task group constraint which
|
2017-03-12 00:18:01 +00:00
|
|
|
scopes the effect to just that group. The constraint may not be
|
|
|
|
specified at the task level.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
Placing the constraint at both the job level and at the task group level is
|
|
|
|
redundant since when placed at the job level, the constraint will be applied
|
|
|
|
to all task groups. When specified, `LTarget` and `RTarget` should be
|
|
|
|
omitted.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-03-12 00:18:01 +00:00
|
|
|
* `distinct_property` - If set, the scheduler selects nodes that have a
|
|
|
|
distinct value of the specified property for each allocation. This can
|
|
|
|
be specified as a job constraint which applies the constraint to all
|
|
|
|
task groups in the job, or as a task group constraint which scopes the
|
|
|
|
effect to just that group. The constraint may not be specified at the
|
|
|
|
task level.
|
|
|
|
|
|
|
|
Placing the constraint at both the job level and at the task group level is
|
|
|
|
redundant since when placed at the job level, the constraint will be applied
|
|
|
|
to all task groups. When specified, `LTarget` should be the property
|
|
|
|
that should be distinct and and `RTarget` should be omitted.
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The
|
|
|
|
ordering is compared lexically.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
### Log Rotation
|
|
|
|
|
|
|
|
The `LogConfig` object configures the log rotation policy for a task's `stdout` and
|
|
|
|
`stderr`. The `LogConfig` object supports the following attributes:
|
|
|
|
|
|
|
|
* `MaxFiles` - The maximum number of rotated files Nomad will retain for
|
|
|
|
`stdout` and `stderr`, each tracked individually.
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
* `MaxFileSizeMB` - The size of each rotated file. The size is specified in
|
2016-02-21 18:19:37 +00:00
|
|
|
`MB`.
|
|
|
|
|
|
|
|
If the amount of disk resource requested for the task is less than the total
|
|
|
|
amount of disk space needed to retain the rotated set of files, Nomad will return
|
|
|
|
a validation error when a job is submitted.
|
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"LogConfig": {
|
2016-02-21 18:19:37 +00:00
|
|
|
"MaxFiles": 3,
|
|
|
|
"MaxFileSizeMB": 10
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
In the above example we have asked Nomad to retain 3 rotated files for both
|
|
|
|
`stderr` and `stdout` and size of each file is 10MB. The minimum disk space that
|
|
|
|
would be required for the task would be 60MB.
|
|
|
|
|
|
|
|
### Artifact
|
|
|
|
|
|
|
|
Nomad downloads artifacts using
|
|
|
|
[`go-getter`](https://github.com/hashicorp/go-getter). The `go-getter` library
|
|
|
|
allows downloading of artifacts from various sources using a URL as the input
|
2016-10-28 00:36:26 +00:00
|
|
|
source. The key-value pairs given in the `options` block map directly to
|
2016-07-18 14:24:30 +00:00
|
|
|
parameters appended to the supplied `source` URL. These are then used by
|
2016-02-21 18:19:37 +00:00
|
|
|
`go-getter` to appropriately download the artifact. `go-getter` also has a CLI
|
|
|
|
tool to validate its URL and can be used to check if the Nomad `artifact` is
|
|
|
|
valid.
|
|
|
|
|
|
|
|
Nomad allows downloading `http`, `https`, and `S3` artifacts. If these artifacts
|
|
|
|
are archives (zip, tar.gz, bz2, etc.), these will be unarchived before the task
|
|
|
|
is started.
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
The `Artifact` object supports the following keys:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-03-19 19:35:58 +00:00
|
|
|
* `GetterSource` - The path to the artifact to download.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
* `RelativeDest` - An optional path to download the artifact into relative to the
|
|
|
|
root of the task's directory. If omitted, it will default to `local/`.
|
2016-03-19 19:35:58 +00:00
|
|
|
|
2016-03-30 22:22:04 +00:00
|
|
|
* `GetterOptions` - A `map[string]string` block of options for `go-getter`.
|
|
|
|
Full documentation of supported options are available
|
|
|
|
[here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1).
|
|
|
|
An example is given below:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"GetterOptions": {
|
2016-02-21 18:19:37 +00:00
|
|
|
"checksum": "md5:c4aa853ad2215426eb7d70a21922e794",
|
|
|
|
|
|
|
|
"aws_access_key_id": "<id>",
|
|
|
|
"aws_access_key_secret": "<secret>",
|
|
|
|
"aws_access_token": "<token>"
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
An example of downloading and unzipping an archive is as simple as:
|
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
|
|
|
"GetterSource": "https://example.com/my.zip",
|
|
|
|
"GetterOptions": {
|
|
|
|
"checksum": "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3"
|
|
|
|
}
|
2016-05-09 23:23:25 +00:00
|
|
|
}
|
2016-10-03 22:23:50 +00:00
|
|
|
]
|
|
|
|
}
|
2016-04-14 23:47:24 +00:00
|
|
|
```
|
2016-06-03 21:35:43 +00:00
|
|
|
|
|
|
|
#### S3 examples
|
|
|
|
|
|
|
|
S3 has several different types of addressing and more detail can be found
|
|
|
|
[here](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro)
|
|
|
|
|
|
|
|
S3 region specific endpoints can be found
|
|
|
|
[here](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region)
|
|
|
|
|
|
|
|
Path based style:
|
2016-10-03 22:23:50 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
|
|
|
"GetterSource": "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz",
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2016-06-03 21:35:43 +00:00
|
|
|
```
|
|
|
|
|
2016-07-18 14:24:30 +00:00
|
|
|
or to override automatic detection in the URL, use the S3-specific syntax
|
2016-10-03 22:23:50 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
|
|
|
"GetterSource": "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz",
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2016-06-03 21:35:43 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Virtual hosted based style
|
2016-10-03 22:23:50 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
|
|
|
"GetterSource": "my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz",
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2016-06-03 21:35:43 +00:00
|
|
|
```
|
2017-01-24 13:46:17 +00:00
|
|
|
|
|
|
|
### Template
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
The `Template` block instantiates an instance of a template renderer. This
|
|
|
|
creates a convenient way to ship configuration files that are populated from
|
|
|
|
environment variables, Consul data, Vault secrets, or just general
|
|
|
|
configurations within a Nomad task.
|
|
|
|
|
|
|
|
Nomad utilizes a tool called [Consul Template][ct]. Since Nomad v0.5.3, the
|
|
|
|
template can reference [Nomad's runtime environment variables][env]. For a full
|
|
|
|
list of the API template functions, please refer to the [Consul Template
|
|
|
|
README][ct].
|
|
|
|
|
2017-01-24 13:46:17 +00:00
|
|
|
|
|
|
|
`Template` object supports following attributes:
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
- `ChangeMode` - Specifies the behavior Nomad should take if the rendered
|
|
|
|
template changes. The default value is `"restart"`. The possible values are:
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
- `"noop"` - take no action (continue running the task)
|
|
|
|
- `"restart"` - restart the task
|
|
|
|
- `"signal"` - send a configurable signal to the task
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
* `ChangeSignal` - Specifies the signal to send to the task as a string like
|
|
|
|
"SIGUSR1" or "SIGINT". This option is required if the `ChangeMode` is
|
|
|
|
`signal`.
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2017-02-21 00:43:28 +00:00
|
|
|
* `DestPath` - Specifies the location where the resulting template should be
|
|
|
|
rendered, relative to the task directory.
|
|
|
|
|
|
|
|
* `EmbeddedTmpl` - Specifies the raw template to execute. One of `SourcePath`
|
|
|
|
or `EmbeddedTmpl` must be specified, but not both. This is useful for smaller
|
|
|
|
templates, but we recommend using `SourcePath` for larger templates.
|
|
|
|
|
|
|
|
* `LeftDelim` - Specifies the left delimiter to use in the template. The default
|
|
|
|
is "{{" for some templates, it may be easier to use a different delimiter that
|
|
|
|
does not conflict with the output file itself.
|
|
|
|
|
|
|
|
* `Perms` - Specifies the rendered template's permissions. File permissions are
|
2017-02-13 18:18:34 +00:00
|
|
|
given as octal of the unix file permissions rwxrwxrwx.
|
|
|
|
|
2017-02-21 00:43:28 +00:00
|
|
|
* `RightDelim` - Specifies the right delimiter to use in the template. The default
|
|
|
|
is "}}" for some templates, it may be easier to use a different delimiter that
|
|
|
|
does not conflict with the output file itself.
|
|
|
|
|
|
|
|
* `SourcePath` - Specifies the path to the template to be rendered. `SourcePath`
|
|
|
|
is mutually exclusive with `EmbeddedTmpl` attribute. The source can be fetched
|
|
|
|
using an [`Artifact`](#artifact) resource. The template must exist on the
|
|
|
|
machine prior to starting the task; it is not possible to reference a template
|
|
|
|
inside of a Docker container, for example.
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
* `Splay` - Specifies a random amount of time to wait between 0ms and the given
|
|
|
|
splay value before invoking the change mode. Should be specified in
|
|
|
|
nanoseconds.
|
2017-01-24 13:46:17 +00:00
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Templates": [
|
|
|
|
{
|
|
|
|
"SourcePath": "local/config.conf.tpl",
|
|
|
|
"DestPath": "local/config.conf",
|
2017-01-24 17:12:42 +00:00
|
|
|
"EmbeddedTmpl": "",
|
2017-01-24 13:46:17 +00:00
|
|
|
"ChangeMode": "signal",
|
|
|
|
"ChangeSignal": "SIGUSR1",
|
|
|
|
"Splay": 5000000000
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
[ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
|
|
|
|
[env]: /docs/runtime/environment.html "Nomad Runtime Environment"
|