diff --git a/website/source/docs/jobspec/index.html.md b/website/source/docs/jobspec/index.html.md index 2d4a82f57..6d6e7ecca 100644 --- a/website/source/docs/jobspec/index.html.md +++ b/website/source/docs/jobspec/index.html.md @@ -1,16 +1,288 @@ --- layout: "docs" -page_title: "Job Configuration" -sidebar_current: "docs-jobconf" +page_title: "Job Specification" +sidebar_current: "docs-jobspec" description: |- - Learn about the Job file configuration and features of specific drivers. + Learn about the Job specification used to submit jobs to Nomad. --- -# Job Configuration +# Job Specification -This section covers some high level basic concepts that are important -to understand for day to day Nomad usage and operation. Every page in -this section is recommended reading for anyone consuming or operating -Nomad. +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 = 1 + } + } + } + } +} +``` + +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: + +* `driver` - Specifies the driver that should be used to run the + task. See the driver documentation for what is available. Examples + include "docker", "qemu", "java", and "exec". + +* `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` - The number of dynamic ports. These are + ports that are assigned at task scheduling type, and require + the task to be able to bind dynamically. Defaults to 0. + +* `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: + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDescription
$node.idThe client node identifier
$node.datacenterThe client node datacenter
$node.nameThe client node name
$attr.\The attribute given by `key` on the client node.
$meta.\The metadata value given by `key` on the client node.
+ +Below is a table documenting common node attributes: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescription
archCPU architecture of the client. Examples: "amd64", "386"
consul.datacenterThe Consul datacenter of the client node if Consul found
cpu.numcoresNumber of CPU cores on the client
hostnameHostname of the client
platform.aws.ami-idOn EC2, the AMI ID of the client node
platform.aws.instance-typeOn EC2, the instance type of the client node
os.nameOperating system of the client. Examples: "linux", "windows", "darwin"
os.versionVersion of the client OS
+ +## 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. -Please use the navigation to the left to learn more about a topic.