open-nomad/website/source/docs/jobspec/index.html.md

298 lines
9.0 KiB
Markdown
Raw Normal View History

2015-09-12 00:01:02 +00:00
---
layout: "docs"
2015-09-20 22:06:56 +00:00
page_title: "Job Specification"
sidebar_current: "docs-jobspec"
2015-09-12 00:01:02 +00:00
description: |-
2015-09-20 22:06:56 +00:00
Learn about the Job specification used to submit jobs to Nomad.
2015-09-12 00:01:02 +00:00
---
2015-09-20 22:06:56 +00:00
# Job Specification
2015-09-12 00:01:02 +00:00
2015-09-20 22:06:56 +00:00
Jobs can be specified either in [HCL](https://github.com/hashicorp/hcl) which is meant
to strike a balance between human readable and editable as well as being machine-friendly.
For machine-friendliness, Nomad can also read JSON configurations. In general, we recommend
recommend using the HCL syntax.
## HCL Syntax
For a detailed description of HCL general syntax, [see the guide](https://github.com/hashicorp/hcl#syntax).
Here we cover the details of the Job specification for Nomad, here is an example:
```
# Define a job called my-service
job "my-service" {
# Job should run in the US region
region = "us"
# Spread tasks between us-west-1 and us-east-1
datacenters = ["us-west-1", "us-east-1"]
# Rolling updates should be sequential
update {
stagger = "30s"
max_parallel = 1
}
group "webs" {
# We want 5 web servers
count = 5
# Create a web front end using a docker image
task "frontend" {
driver = "docker"
config {
image = "hashicorp/web-frontend"
}
resources {
cpu = 500
memory = 128
network {
mbits = 100
dynamic_ports = [
"http",
"https",
]
2015-09-20 22:06:56 +00:00
}
}
}
}
}
```
This is a fairly simple example job, but demonstrates many of the features and syntax
of the job specification. The primary "objects" are the job, task group, and task.
Each job file has only a single job, however a job may have multiple task groups,
and each task group may have multiple tasks. Task groups are a set of tasks that
must be co-located on a machine. Groups with a single task and count of one
can be declared outside of a group which is created implicitly.
Constraints can be specified at the job, task group, or task level to restrict
where a task is eligible for running. An example constraint looks like:
```
# Restrict to only nodes running linux
constraint {
attribute = "$attr.kernel.os"
value = "linux"
}
```
Jobs can also specify additional metadata at the job, task group, or task level.
This metadata is opaque to Nomad and can be used for any purpose, including
defining constraints on the metadata. Metadata can be specified by:
```
# Setup ELB via metadata and setup foo
meta {
foo = "bar"
elb_mode = "tcp"
elb_check_interval = "10s"
}
```
## 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:
* `all_at_once` - 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`.
* `constraint` - This can be provided multiple times to define additional
constraints. 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.
* `group` - This can be provided multiple times to define additional
task groups. See the task group reference for more details.
* `meta` - Annotates the job with opaque metadata.
* `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".
* `task` - This can be specified multiple times to add a task as
part of the job. Tasks defined directly in a job are wrapped in
a task group of the same name.
* `type` - Specifies the job type and switches which scheduler
is used. Nomad provides the `service` and `batch` schedulers,
and defaults to `service`.
* `update` - Specifies the task update strategy. This requires providing
`max_parallel` as an integer and `stagger` as a time duration. If stagger
is provided as an integer, seconds are assumed. Otherwise the "s", "m",
and "h" suffix can be used, such as "30s". Both values default to zero,
which disables rolling updates.
### Task Group
The `group` object supports the following keys:
* `count` - Specifies the number of the task groups that should
be running. Must be positive, defaults to one.
* `constraint` - This can be provided multiple times to define additional
constraints. See the constraint reference for more details.
* `task` - This can be specified multiple times, to add a task as
part of the group.
* `meta` - Annotates the task group with opaque metadata.
### Task
The `task` object supports the following keys:
2015-09-20 22:51:49 +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".
2015-09-20 22:06:56 +00:00
* `constraint` - This can be provided multiple times to define additional
constraints. See the constraint reference for more details.
* `config` - A map of key/value configuration passed into the driver
to start the task. The details of configurations are specific to
each driver.
* `resources` - Provides the resource requirements of the task.
See the resources reference for more details.
* `meta` - Annotates the task group with opaque metadata.
### Resources
The `resources` object supports the following keys:
* `cpu` - The CPU required in MHz.
* `disk` - The disk required in MB.
* `iops` - The number of IOPS required.
* `memory` - The memory required in MB.
* `network` - The network required. Details below.
The `network` object supports teh following keys:
* `dynamic_ports` - List of port labels which may contain letters, numbers and underscores.
Each label will be associated with a dynamic port when the task starts. Port allocation
will be passed to the task as an environment variable like `NOMAD_PORT_{{ .Label }}`
(upper-cased). Some Drivers may infer additional semantics from the label. See
[Docker](/docs/drivers/docker.html) for an example.
2015-09-20 22:06:56 +00:00
* `mbits` - The number of MBits in bandwidth required.
* `reserved_ports` - This is a list of specific ports required.
For applications that cannot use a dynamic port, they can
request a specific port.
### Constraint
The `constraint` object supports the following keys:
* `attribute` - Specifies the attribute to examine for the
constraint. See the table of attributes below.
* `hard` - Specifies if this is a hard or soft constraint. Defaults
to true. Soft constraints are not currently supported.
* `operator` - Specifies the comparison operator. Defaults to equality,
and can be `=`, `==`, `is`, `!=`, `not`.
* `value` - Specifies the value to compare the attribute against.
This can be a literal value or another attribute.
Below is a table documenting the variables that can be interpretted:
<table class="table table-bordered table-striped">
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
<tr>
<td>$node.id</td>
<td>The client node identifier</td>
</tr>
<tr>
<td>$node.datacenter</td>
<td>The client node datacenter</td>
</tr>
<tr>
<td>$node.name</td>
<td>The client node name</td>
</tr>
<tr>
<td>$attr.\<key\></td>
<td>The attribute given by `key` on the client node.</td>
</tr>
<tr>
<td>$meta.\<key\></td>
<td>The metadata value given by `key` on the client node.</td>
</tr>
</table>
Below is a table documenting common node attributes:
<table class="table table-bordered table-striped">
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
<tr>
<td>arch</td>
<td>CPU architecture of the client. Examples: "amd64", "386"</td>
</tr>
<tr>
<td>consul.datacenter</td>
<td>The Consul datacenter of the client node if Consul found</td>
</tr>
<tr>
<td>cpu.numcores</td>
<td>Number of CPU cores on the client</td>
</tr>
2015-09-20 22:51:49 +00:00
<tr>
<td>driver.\<key\></td>
<td>See the [task drivers](/docs/drivers/index.html) for attribute documentation</td>
</tr>
2015-09-20 22:06:56 +00:00
<tr>
<td>hostname</td>
<td>Hostname of the client</td>
</tr>
<tr>
<td>platform.aws.ami-id</td>
<td>On EC2, the AMI ID of the client node</td>
</tr>
<tr>
<td>platform.aws.instance-type</td>
<td>On EC2, the instance type of the client node</td>
</tr>
<tr>
<td>os.name</td>
<td>Operating system of the client. Examples: "linux", "windows", "darwin"</td>
</tr>
<tr>
<td>os.version</td>
<td>Version of the client OS</td>
</tr>
</table>
## JSON Syntax
Job files can also be specified in JSON. The conversion is straightforward
and self-documented. The downsides of JSON are less human readability and
the lack of comments. Otherwise, the two are completely interoperable.
See the API documentation for more details on the JSON structure.
2015-09-12 00:01:02 +00:00