luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity

Merge pull request #1883 from hashicorp/sethvargo/docs

Browse source 
Revamp job specification documentation to be more modular and composable
This commit is contained in:
Seth Vargo 2016-10-28 10:52:12 -04:00 committed by GitHub
parent de8188ea80 d145878fd2
commit 030e493c55
69 changed files with 2065 additions and 885 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
website/Gemfile
View file

@ -1,3 +1,3 @@
source "https://rubygems.org"
gem "middleman-hashicorp", "0.3.3"
gem "middleman-hashicorp", "0.3.4"

8
website/Gemfile.lock
View file

@ -7,7 +7,7 @@ GEM
minitest (~> 5.1)
thread_safe (~> 0.3, >= 0.3.4)
tzinfo (~> 1.1)
autoprefixer-rails (6.5.1)
autoprefixer-rails (6.5.1.1)
execjs
bootstrap-sass (3.3.7)
autoprefixer-rails (>= 5.2.1)
@ -78,7 +78,7 @@ GEM
rack (>= 1.4.5, < 2.0)
thor (>= 0.15.2, < 2.0)
tilt (~> 1.4.1, < 2.0)
middleman-hashicorp (0.3.3)
middleman-hashicorp (0.3.4)
bootstrap-sass (~> 3.3)
builder (~> 3.2)
middleman (~> 3.4)
@ -116,7 +116,7 @@ GEM
rack
rack-test (0.6.3)
rack (>= 1.0)
rb-fsevent (0.9.7)
rb-fsevent (0.9.8)
rb-inotify (0.9.7)
ffi (>= 0.5.0)
redcarpet (3.3.4)
@ -148,7 +148,7 @@ PLATFORMS
ruby
DEPENDENCIES
middleman-hashicorp (= 0.3.3)
middleman-hashicorp (= 0.3.4)
BUNDLED WITH
1.13.5

2
website/Makefile
View file

@ -1,4 +1,4 @@
VERSION?="0.3.3"
VERSION?="0.3.4"
website:
@echo "==> Starting website in Docker..."

47
website/config.rb
View file

@ -5,3 +5,50 @@ activate :hashicorp do |h|
h.version = "0.4.1"
h.github_slug = "hashicorp/nomad"
end
helpers do
# Get the title for the page.
#
# @param [Middleman::Page] page
#
# @return [String]
def title_for(page)
if page && page.data.page_title
return "#{page.data.page_title} - Nomad by HashiCorp"
end
"Nomad by HashiCorp"
end
# Get the description for the page
#
# @param [Middleman::Page] page
#
# @return [String]
def description_for(page)
return escape_html(page.data.description || "")
end
# Returns the id for this page.
# @return [String]
def body_id_for(page)
if name = page.data.sidebar_current && !name.blank?
return "page-#{name.strip}"
end
return "page-home"
end
# Returns the list of classes for this page.
# @return [String]
def body_classes_for(page)
classes = []
if page && page.data.layout
classes << "layout-#{page.data.layout}"
end
classes << "-displaying-bnr"
return classes.join(" ")
end
end

15
website/helpers/command_helpers.rb
View file

@ -1,15 +0,0 @@
module CommandHelpers
# Returns the markdown text for the general options usage.
def general_options_usage()
<<EOF
* `-address=<addr>`: The address of the Nomad server. Overrides the `NOMAD_ADDR`
environment variable if set. Defaults to `http://127.0.0.1:4646`.
* `-region=<region>`: The region of the Nomad server to forward commands to.
Overrides the `NOMAD_REGION` environment variable if set. Defaults to the
Agent's local region.
* `-no-color`: Disables colored command output.
EOF
end
end

35
website/source/assets/stylesheets/_docs.scss
View file

@ -2,15 +2,12 @@
// Docs
// --------------------------------------------------
$docs-font-size: 16px;
$docs-font-size: 15px;
body.layout-docs,
body.layout-inner,
body.layout-downloads,
body.layout-intro{
//background: $light-black image-url('sidebar-wire.png') left 62px no-repeat;
font-size: $docs-font-size - 2;
>.container{
.col-md-8[role=main]{
min-height: 800px;
@ -23,10 +20,26 @@ body.layout-intro{
}
}
*:focus {
outline: none;
}
h1 > code,
h2 > code,
h3 > code,
h4 > code,
h5 > code
h6 > code,
li > code,
table code,
p code,
tt,
.alert code {
font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
font-size: 90%;
background-color: transparent;
color: inherit;
padding: 0;
}
}
@ -79,6 +92,10 @@ body.layout-intro{
}
}
&:focus {
background-color: inherit;
}
&:before{
content: '';
position: absolute;
@ -131,6 +148,10 @@ body.layout-intro{
@include img-retina("caret-light.png", "caret-light@2x.png", 6px, 9px);
}
&:focus {
background-color: inherit;
}
&:hover {
color: #000;
@ -223,6 +244,7 @@ body.layout-intro{
color: $gray-dark;
margin-top: 54px;
margin-bottom: $docs-font-size;
line-height: 1.3;
@include open-sb();
}
@ -230,6 +252,11 @@ body.layout-intro{
font-size: 36px;
}
h2 {
padding-bottom: 3px;
border-bottom: 1px solid $gray-light;
}
#graph {
margin-top: 30px;
}

18
website/source/docs/agent/config.html.md
View file

@ -123,7 +123,7 @@ nodes, unless otherwise specified:
environments. Defaults to `false`.
* `ports`: Controls the network ports used for different services required by
the Nomad agent. The value is a key/value mapping of port numbers, and accepts
the Nomad agent. The value is a key-value mapping of port numbers, and accepts
the following keys:
<br>
* `http`: The port used to run the HTTP server. Applies to both client and
@ -184,7 +184,7 @@ nodes, unless otherwise specified:
<a id="telemetry_config"></a>
* `telemetry`: Used to control how the Nomad agent exposes telemetry data to
external metrics collection servers. This is a key/value mapping and supports
external metrics collection servers. This is a key-value mapping and supports
the following keys:
<br>
* `statsite_address`: Address of a
@ -258,7 +258,7 @@ The following options are used to configure [Consul](https://www.consul.io)
integration and are entirely optional.
* `consul`: The top-level config key used to contain all Consul-related
configuration options. The value is a key/value map which supports the
configuration options. The value is a key-value map which supports the
following keys:
<br>
* `address`: The address to the local Consul agent given in the format of
@ -329,7 +329,7 @@ The following options are used to configure [Atlas](https://atlas.hashicorp.com)
integration and are entirely optional.
* `atlas`: The top-level config key used to contain all Atlas-related
configuration options. The value is a key/value map which supports the
configuration options. The value is a key-value map which supports the
following keys:
<br>
* <a id="infrastructure">`infrastructure`</a>: The Atlas infrastructure name to
@ -351,7 +351,7 @@ The following options are applicable to server agents only and need not be
configured on client nodes.
* `server`: This is the top-level key used to define the Nomad server
configuration. It is a key/value mapping which supports the following keys:
configuration. It is a key-value mapping which supports the following keys:
<br>
* `enabled`: A boolean indicating if server mode should be enabled for the
local agent. All other server options depend on this value being set.
@ -415,7 +415,7 @@ The following options are applicable to client agents only and need not be
configured on server nodes.
* `client`: This is the top-level key used to define the Nomad client
configuration. Like the server configuration, it is a key/value mapping which
configuration. Like the server configuration, it is a key-value mapping which
supports the following keys:
<br>
* `enabled`: A boolean indicating if client mode is enabled. All other client
@ -437,12 +437,12 @@ configured on server nodes.
* <a id="node_class">`node_class`</a>: A string used to logically group client
nodes by class. This can be used during job placement as a filter. This
option is not required and has no default.
* <a id="meta">`meta`</a>: This is a key/value mapping of metadata pairs. This
* <a id="meta">`meta`</a>: This is a key-value mapping of metadata pairs. This
is a free-form map and can contain any string values.
* <a id="options">`options`</a>: This is a key/value mapping of internal
* <a id="options">`options`</a>: This is a key-value mapping of internal
configuration for clients, such as for driver configuration. Please see
[here](#options_map) for a description of available options.
* <a id="chroot_env">`chroot_env`</a>: This is a key/value mapping that
* <a id="chroot_env">`chroot_env`</a>: This is a key-value mapping that
defines the chroot environment for jobs using the Exec and Java drivers.
Please see [here](#chroot_env_map) for an example and further information.
* <a id="network_interface">`network_interface`</a>: This is a string to force

28
website/source/docs/commands/_general_options.html.md Normal file
View file

@ -0,0 +1,28 @@
- `-address=<addr>`: The address of the Nomad server. Overrides the `NOMAD_ADDR`
environment variable if set. Defaults to `http://127.0.0.1:4646`.
- `-region=<region>`: The region of the Nomad server to forward commands to.
Overrides the `NOMAD_REGION` environment variable if set. Defaults to the
Agent's local region.
- `-no-color`: Disables colored command output.
- `-ca-cert=<path>`: Path to a PEM encoded CA cert file to use to verify the
Nomad server SSL certificate. Overrides the `NOMAD_CACERT` environment
variable if set.
- `-ca-path=<path>`: Path to a directory of PEM encoded CA cert files to verify
the Nomad server SSL certificate. If both `-ca-cert` and `-ca-path` are
specified, `-ca-cert` is used. Overrides the `NOMAD_CAPATH` environment
variable if set.
- `-client-cert=<path>`: Path to a PEM encoded client certificate for TLS
authentication to the Nomad server. Must also specify `-client-key`. Overrides
the `NOMAD_CLIENT_CERT` environment variable if set.
- `-client-key=<path>`: Path to an unencrypted PEM encoded private key matching
the client certificate from `-client-cert`. Overrides the `NOMAD_CLIENT_KEY`
environment variable if set.
- `-tls-skip-verify`: Do not verify TLS certificate. This is highly not
recommended. Verification will also be skipped if `NOMAD_SKIP_VERIFY` is set.

2
website/source/docs/commands/agent-info.html.md.erb
View file

@ -20,7 +20,7 @@ nomad agent-info [options]
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Output

2
website/source/docs/commands/alloc-status.html.md.erb
View file

@ -25,7 +25,7 @@ allocations and information will be displayed.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Alloc Status Options

2
website/source/docs/commands/client-config.html.md.erb
View file

@ -23,7 +23,7 @@ description below for specific usage information and requirements.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Client Config Options

2
website/source/docs/commands/eval-status.html.md.erb
View file

@ -40,7 +40,7 @@ indicated by exit code 1.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Eval Status Options

2
website/source/docs/commands/fs.html.md.erb
View file

@ -33,7 +33,7 @@ defaults to `/` of the allocation directory.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Fs Options

12
website/source/docs/commands/init.html.md.erb
View file

@ -8,18 +8,20 @@ description: >
# Command: init
The `init` command creates an example [job specification](/docs/jobspec/) in the current
directory that demonstrates some common configurations for tasks, task groups,
runtime constraints, and resource allocation.
The `init` command creates an example [job specification][jobspec] in the
current directory that demonstrates some common configurations for tasks, task
groups, runtime constraints, and resource allocation.
Please refer to the [jobspec](/docs/jobspec/) and [drivers](/docs/drivers/)
Please refer to the [jobspec][] and [drivers](/docs/drivers/index.html)
pages to learn how to customize the template.
## Examples
Generate an example job file:
```
```text
$ nomad init
Example job file written to example.nomad
```
[jobspec]: /docs/job-specification/index.html "Nomad Job Specification"

2
website/source/docs/commands/inspect.html.md.erb
View file

@ -23,7 +23,7 @@ version of a job Nomad is running.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Inspect Options

2
website/source/docs/commands/logs.html.md.erb
View file

@ -23,7 +23,7 @@ the given job will be chosen.
#
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Logs Options

2
website/source/docs/commands/node-drain.html.md.erb
View file

@ -31,7 +31,7 @@ operation is desired.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Node Drain Options

2
website/source/docs/commands/node-status.html.md.erb
View file

@ -30,7 +30,7 @@ information will be displayed. If running the command on a Nomad Client, the
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Node Status Options

19
website/source/docs/commands/plan.html.md.erb
View file

@ -8,10 +8,10 @@ description: >
# Command: plan
The `plan` command can be used to envoke the scheduler in a dry-run mode with new
jobs or when updating existing jobs to determine what would happen if the job
is submitted. Job files must conform to the [job specification](/docs/jobspec/index.html)
format.
The `plan` command can be used to envoke the scheduler in a dry-run mode with
new jobs or when updating existing jobs to determine what would happen if the
job is submitted. Job files must conform to the [job
specification](/docs/job-specification/index.html) format.
## Usage
@ -20,11 +20,12 @@ nomad plan [options] <file>
```
The plan command requires a single argument, specifying the path to a file
containing a [HCL job specification](/docs/jobspec/index.html). This file
will be read and the job checked for any problems. If the
supplied path is "-", the jobfile is read from STDIN. Otherwise it is read
containing a [HCL job specification](/docs/job-specification/index.html). This
file will be read and the resulting parsed job will be validated. If the
supplied path is "-", the job file is read from STDIN. Otherwise it is read
from the file at the supplied path or downloaded and read from URL specified.
Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
Nomad downloads the job file using
[`go-getter`](https://github.com/hashicorp/go-getter)
and supports `go-getter` syntax.
Plan invokes a dry-run of the scheduler to determine the effects of submitting
@ -52,7 +53,7 @@ Plan will return one of the following exit codes:
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Plan Options

12
website/source/docs/commands/run.html.md.erb
View file

@ -9,21 +9,21 @@ description: >
# Command: run
The `run` command is used to submit new jobs to Nomad or to update existing
jobs. Job files must conform to the [job specification](/docs/jobspec/index.html)
jobs. Job files must conform to the [job specification](/docs/job-specification/index.html)
format.
## Usage
```
nomad run [options] <jobfile>
nomad run [options] <job file>
```
The run command requires a single argument, specifying the path to a file
containing a valid [job specification](/docs/jobspec/index.html). This file
containing a valid [job specification](/docs/job-specification/index.html). This file
will be read and the job will be submitted to Nomad for scheduling. If the
supplied path is "-", the jobfile is read from STDIN. Otherwise it is read
supplied path is "-", the job file is read from STDIN. Otherwise it is read
from the file at the supplied path or downloaded and read from URL specified.
Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
Nomad downloads the job file using [`go-getter`](https://github.com/hashicorp/go-getter)
and supports `go-getter` syntax.
By default, on successful job submission the run command will enter an
@ -45,7 +45,7 @@ precedence, going from highest to lowest: the `-vault-token` flag, the
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Run Options

2
website/source/docs/commands/server-force-leave.html.md.erb
View file

@ -24,7 +24,7 @@ to enter the "left" state.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Examples

2
website/source/docs/commands/server-join.html.md.erb
View file

@ -26,7 +26,7 @@ be 1.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Examples

2
website/source/docs/commands/server-members.html.md.erb
View file

@ -23,7 +23,7 @@ nomad server-members [options]
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Server Members Options

2
website/source/docs/commands/status.html.md.erb
View file

@ -26,7 +26,7 @@ the most useful status fields for each.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Status Options

2
website/source/docs/commands/stop.html.md.erb
View file

@ -29,7 +29,7 @@ reached a terminal state. It is safe to exit the monitor early using ctrl+c.
## General Options
<%= general_options_usage %>
<%= partial "docs/commands/_general_options" %>
## Stop Options

9
website/source/docs/commands/validate.html.md.erb
View file

@ -8,7 +8,7 @@ description: >
# Command: validate
The `validate` command is used to check a [HCL job specification](/docs/jobspec/index.html)
The `validate` command is used to check a [HCL job specification](/docs/job-specification/index.html)
for any syntax errors or validation problems.
## Usage
@ -18,13 +18,12 @@ nomad validate <file>
```
The validate command requires a single argument, specifying the path to a file
containing a [HCL job specification](/docs/jobspec/index.html). This file
containing a [HCL job specification](/docs/job-specification/index.html). This file
will be read and the job checked for any problems. If the
supplied path is "-", the jobfile is read from STDIN. Otherwise it is read
supplied path is "-", the job file is read from STDIN. Otherwise it is read
from the file at the supplied path or downloaded and read from URL specified.
Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter)
Nomad downloads the job file using [`go-getter`](https://github.com/hashicorp/go-getter)
and supports `go-getter` syntax.
On successful validation, exit code 0 will be returned, otherwise an exit code
of 1 indicates an error.

14
website/source/docs/drivers/docker.html.md
View file

@ -26,7 +26,7 @@ task "webservice" {
group = "webservice-cache"
}
}
}
}
```
The `docker` driver supports the following configuration in the job spec:
@ -68,7 +68,7 @@ The `docker` driver supports the following configuration in the job spec:
* `args` - (Optional) A list of arguments to the optional `command`. If no
`command` is specified, the args are passed directly to the container.
References to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
variables](/docs/runtime/interpolation.html) will be interpreted before
launching the task. For example:
```hcl
@ -82,7 +82,7 @@ The `docker` driver supports the following configuration in the job spec:
}
```
* `labels` - (Optional) A key/value map of labels to set to the containers on
* `labels` - (Optional) A key-value map of labels to set to the containers on
start.
```hcl
@ -135,7 +135,7 @@ The `docker` driver supports the following configuration in the job spec:
* `SSL` - (Optional) If this is set to true, Nomad uses SSL to talk to the
repository. The default value is `true`.
* `port_map` - (Optional) A key/value map of port labels (see below).
* `port_map` - (Optional) A key-value map of port labels (see below).
* `auth` - (Optional) Provide authentication for a private registry (see below).
@ -147,7 +147,7 @@ The `docker` driver supports the following configuration in the job spec:
* `shm_size` - (Optional) The size (bytes) of /dev/shm for the container.
* `logging` - (Optional) A key/value map of Docker logging options. The default
* `logging` - (Optional) A key-value map of Docker logging options. The default
value is `syslog`.
```hcl
@ -238,7 +238,7 @@ scope of Nomad.
### Allocating Ports
You can allocate ports to your task using the port syntax described on the
[networking page](/docs/jobspec/networking.html). Here is a recap:
[networking page](/docs/job-specification/network.html). Here is a recap:
```hcl
task "example" {
@ -377,7 +377,7 @@ options](/docs/agent/config.html#options):
* `docker.volumes.selinuxlabel`: Allows the operator to set a SELinux
label to the allocation and task local bind-mounts to containers. If used
with `docker.volumes.enabled` set to false, the labels will still be applied
to the standard binds in the container.
to the standard binds in the container.
* `docker.privileged.enabled` Defaults to `false`. Changing this to `true` will
allow containers to use `privileged` mode, which gives the containers full

8
website/source/docs/drivers/exec.html.md
View file

@ -26,19 +26,19 @@ task "webservice" {
command = "my-binary"
args = ["-flag", "1"]
}
}
}
```
The `exec` driver supports the following configuration in the job spec:
* `command` - The command to execute. Must be provided. If executing a binary
that exists on the host, the path must be absolute. If executing a binary that
is downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc), the
is downloaded from an [`artifact`](/docs/job-specification/artifact.html), the
path can be relative from the allocations's root directory.
* `args` - (Optional) A list of arguments to the `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
variables](/docs/runtime/interpolation.html) will be interpreted before
launching the task.
## Examples
@ -58,7 +58,7 @@ task "example" {
```
To execute a binary downloaded from an
[`artifact`](/docs/jobspec/index.html#artifact_doc):
[`artifact`](/docs/job-specification/artifact.html):
```hcl
task "example" {

9
website/source/docs/drivers/index.html.md
View file

@ -12,14 +12,13 @@ Task drivers are used by Nomad clients to execute a task and provide resource
isolation. By having extensible task drivers, Nomad has the flexibility to
support a broad set of workloads across all major operating systems.
The list of supported task drivers is provided on the left of this page.
Each task driver documents the configuration available in a
[job specification](/docs/jobspec/index.html), the environments it can
be used in, and the resource isolation mechanisms available.
The list of supported task drivers is provided on the left of this page.
Each task driver documents the configuration available in a
[job specification](/docs/job-specification/index.html), the environments it
can be used in, and the resource isolation mechanisms available.
Nomad strives to mask the details of running a task from users and instead
provides a clean abstraction. It is possible for the same task to be executed
with different isolation levels depending on the client running the task.
The goal is to use the strictest isolation available and gracefully degrade
protections where necessary.

4
website/source/docs/drivers/java.html.md
View file

@ -12,7 +12,7 @@ Name: `java`
The `java` driver is used to execute Java applications packaged into a Java Jar
file. The driver requires the Jar file to be accessible from the Nomad
client via the [`artifact` downloader](/docs/jobspec/index.html#artifact_doc).
client via the [`artifact` downloader](/docs/job-specification/artifact.html).
## Task Configuration
@ -36,7 +36,7 @@ The `java` driver supports the following configuration in the job spec:
* `args` - (Optional) A list of arguments to the Jar's main method. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
variables](/docs/runtime/interpolation.html) will be interpreted before
launching the task.
* `jvm_options` - (Optional) A list of JVM options to be passed while invoking

4
website/source/docs/drivers/qemu.html.md
View file

@ -20,7 +20,7 @@ The `qemu` driver can execute any regular `qemu` image (e.g. `qcow`, `img`,
`iso`), and is currently invoked with `qemu-system-x86_64`.
The driver requires the image to be accessible from the Nomad client via the
[`artifact` downloader](/docs/jobspec/index.html#artifact_doc).
[`artifact` downloader](/docs/job-specification/artifact.html).
## Task Configuration
@ -47,7 +47,7 @@ The `qemu` driver supports the following configuration in the job spec:
If the host machine has `qemu` installed with KVM support, users can specify
`kvm` for the `accelerator`. Default is `tcg`.
* `port_map` - (Optional) A key/value map of port labels.
* `port_map` - (Optional) A key-value map of port labels.
```hcl
config {

6
website/source/docs/drivers/raw_exec.html.md
View file

@ -31,12 +31,12 @@ The `raw_exec` driver supports the following configuration in the job spec:
* `command` - The command to execute. Must be provided. If executing a binary
that exists on the host, the path must be absolute. If executing a binary that
is downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc), the
is downloaded from an [`artifact`](/docs/job-specification/artifact.html), the
path can be relative from the allocations's root directory.
* `args` - (Optional) A list of arguments to the `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
variables](/docs/runtime/interpolation.html) will be interpreted before
launching the task.
## Examples
@ -55,7 +55,7 @@ task "example" {
}
```
To execute a binary downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc):
To execute a binary downloaded from an [`artifact`](/docs/job-specification/artifact.html):
```
task "example" {

6
website/source/docs/drivers/rkt.html.md
View file

@ -26,7 +26,7 @@ task "webservice" {
config {
image = "redis:3.2"
}
}
}
```
The `rkt` driver supports the following configuration in the job spec:
@ -50,7 +50,7 @@ The `rkt` driver supports the following configuration in the job spec:
* `args` - (Optional) A list of arguments to the optional `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
variables](/docs/runtime/interpolation.html) will be interpreted before
launching the task.
```hcl
@ -135,7 +135,7 @@ task "redis" {
### Allocating Ports
You can allocate ports to your task using the port syntax described on the
[networking page](/docs/jobspec/networking.html).
[networking page](/docs/job-specification/network.html).
When you use port allocation, the image manifest needs to declare public ports and host has configured network.
For more information, please refer to [rkt Networking](https://coreos.com/rkt/docs/latest/networking/overview.html).

10
website/source/docs/http/job.html.md
View file

@ -307,9 +307,7 @@ region is used; another region can be specified using the `?region=` query param
<li>
<span class="param">Job</span>
<span class="param-flags">required</span>
The JSON definition of the job. The general structure is given
by the [job specification](/docs/jobspec/index.html), and matches
the return response of GET.
The JSON definition of the job.
</li>
</ul>
</dd>
@ -378,9 +376,7 @@ region is used; another region can be specified using the `?region=` query param
<li>
<span class="param">Job</span>
<span class="param-flags">required</span>
The JSON definition of the job. The general structure is given
by the [job specification](/docs/jobspec/index.html), and matches
the return response of GET.
The JSON definition of the job.
</li>
<li>
<span class="param">Diff</span>
@ -571,7 +567,7 @@ region is used; another region can be specified using the `?region=` query param
<dd>
Forces a new instance of the periodic job. A new instance will be created
even if it violates the job's
[`prohibit_overlap`](/docs/jobspec/index.html#prohibit_overlap) settings. As
[`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap) settings. As
such, this should be only used to immediately run a periodic job.
</dd>

2
website/source/docs/http/jobs.html.md
View file

@ -85,7 +85,7 @@ another region can be specified using the `?region=` query parameter.
<span class="param">Job</span>
<span class="param-flags">required</span>
The JSON definition of the job. The general structure is given
by the [job specification](/docs/jobspec/json.html).
by the [job specification](/docs/http/json-jobs.html).
</li>
</ul>
</dd>

30
website/source/docs/jobspec/json.html.md → website/source/docs/http/json-jobs.html.md
View file

@ -1,17 +1,17 @@
---
layout: "docs"
page_title: "JSON Job Specification"
sidebar_current: "docs-jobspec-json-syntax"
layout: "http"
page_title: "HTTP API: JSON Job Specification"
sidebar_current: "docs-http-json-jobs"
description: |-
Learn about the Job specification used to submit jobs to Nomad in JSON.
Jobs can also be specified via the HTTP API using a JSON format. This guide
discusses the job specification in JSON format.
---
# Job Specification
Jobs can be specified either in [HCL](https://github.com/hashicorp/hcl) or JSON.
This guide covers the JSON syntax for submitting jobs to Nomad. A useful command
for generating valid JSON versions of HCL jobs is `nomad run -output <job.nomad>`
which will emit a JSON version of the job.
for generating valid JSON versions of HCL jobs is
`nomad run -output <job.nomad>` which will emit a JSON version of the job.
## JSON Syntax
@ -187,7 +187,7 @@ The `Job` object supports the following keys:
* `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
[here](/docs/jobspec/schedulers.html)
[here](/docs/runtime/schedulers.html)
* `Update` - Specifies the task's update strategy. When omitted, rolling
updates are disabled. The `Update` object supports the following attributes:
@ -254,7 +254,7 @@ attributes:
* `Count` - Specifies the number of the task groups that should
be running. Must be non-negative, defaults to one.
* `Meta` - A key/value map that annotates the task group with opaque metadata.
* `Meta` - A key-value map that annotates the task group with opaque metadata.
* `Name` - The name of the task group. Must be specified.
@ -272,7 +272,7 @@ The `Task` object supports the following keys:
artifacts to be downloaded before the task is run. See the artifacts
reference for more details.
* `Config` - A map of key/value configuration passed into the driver
* `Config` - A map of key-value configuration passed into the driver
to start the task. The details of configurations are specific to
each driver.
@ -283,10 +283,10 @@ The `Task` object supports the following keys:
task. See the [driver documentation](/docs/drivers/index.html) for what
is available. Examples include `docker`, `qemu`, `java`, and `exec`.
* `Env` - A map of key/value representing environment variables that
* `Env` - A map of key-value representing environment variables that
will be passed along to the running process. Nomad variables are
interpreted when set in the environment variable values. See the table of
interpreted variables [here](/docs/jobspec/interpreted.html).
interpreted variables [here](/docs/runtime/interpolation.html).
For example the below environment map will be reinterpreted:
@ -318,7 +318,7 @@ The `Task` object supports the following keys:
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.
[Click here](/docs/jobspec/servicediscovery.html) to learn more about
[Click here](/docs/service-discovery/index.html) to learn more about
services. Below is the fields in the `Service` object:
* `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
@ -432,7 +432,7 @@ The `RestartPolicy` object supports the following keys:
The `Constraint` object supports the following keys:
* `LTarget` - Specifies the attribute to examine for the
constraint. See the table of attributes [here](/docs/jobspec/interpreted.html#interpreted_node_vars).
constraint. See the table of attributes [here](/docs/runtime/interpolation.html#interpreted_node_vars).
* `RTarget` - Specifies the value to compare the attribute against.
This can be a literal value, another attribute or a regular expression if
@ -492,7 +492,7 @@ would be required for the task would be 60MB.
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
source. The key/value pairs given in the `options` block map directly to
source. The key-value pairs given in the `options` block map directly to
parameters appended to the supplied `source` URL. These are then used by
`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

172
website/source/docs/job-specification/artifact.html.md Normal file
View file

@ -0,0 +1,172 @@
---
layout: "docs"
page_title: "artifact Stanza - Job Specification"
sidebar_current: "docs-job-specification-artifact"
description: |-
The "artifact" stanza instructs Nomad to fetch and unpack a remote resource,
such as a file, tarball, or binary, and permits downloading artifacts from a
variety of locations using a URL as the input source.
---
# `artifact` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> task -> **artifact**</code>
</td>
</tr>
</table>
The `artifact` stanza instructs Nomad to fetch and unpack a remote resource,
such as a file, tarball, or binary. Nomad downloads artifacts using the popular
[`go-getter`][go-getter] library, which permits downloading artifacts from a
variety of locations using a URL as the input source.
```hcl
job "docs" {
group "example" {
task "server" {
artifact {
source = "https://example.com/file.tar.gz"
destination = "/tmp/file"
options {
checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33"
}
}
}
}
}
```
Nomad supports downloading `http`, `https`, and `S3` artifacts. If these
artifacts are archived (`zip`, `tgz`, `bz2`), they are automatically unarchived
before the starting the task.
## `artifact` Parameters
- `destination` `(string: "local/$1")` - Specifies the path to download the
artifact, relative to the root of the task's directory. If omitted, the
default value is to place the binary in `local/`.
- `source` `(string: required)` - Specifies the URL of the artifact to download. The can be any URL as defined by the [`go-getter`][go-getter] library.
- `options` `(map<string|string>: nil)` - Specifies configuration parameters to
fetch the artifact. The key-value pairs map directly to parameters appended to
the supplied `source` URL. Please see the [`go-getter`
documentation][go-getter] for a complete list of options and examples
## `artifact` Examples
The following examples only show the `artifact` stanzas. Remember that the
`artifact` Remember that the `artifact` stanza is only valid in the placements
listed above.
### Download File
This example downloads the artifact from the provided URL and places it in
`local/file.txt`. The `local/` path is relative to the task's directory.
```hcl
artifact {
source = "https://example.com/file.txt"
}
```
### Download with Custom Destination
This example downloads the artifact from the provided URL and places it at
`/tmp/example.txt`, as specified by the optional `destination` parameter.
```hcl
artifact {
source = "https://example.com/file.txt"
destination = "/tmp/example.txt"
}
```
### Download and Unarchive
This example downloads and unarchives the result in `local/file`. Because the
source URL is an archive extension, Nomad will automatically decompress it:
```hcl
artifact {
source = "https://example.com/file.tar.gz"
}
```
To disable automatic unarchiving, set the `archive` option to false:
```hcl
artifact {
source = "https://example.com/file.tar.gz"
options {
archive = false
}
}
```
### Download and Verify Checksums
This example downloads an artifact and verifies the resulting artifact's
checksum before proceeding. If the checksum is invalid, an error will be
returned.
```hcl
artifact {
source = "https://example.com/file.zip"
options {
checksum = "md5:df6a4178aec9fbdc1d6d7e3634d1bc33"
}
}
```
### Download from an S3 Bucket
These examples download artifacts from Amazon S3. There are several different
types of [S3 bucket addressing][s3-bucket-addr] and [S3 region-specific
endpoints][s3-region-endpoints].
This example uses path-based notation on a publicly-accessible bucket:
```hcl
artifact {
source = "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz"
}
```
If a bucket requires authentication, it may be supplied via the `options`
parameter:
```hcl
artifact {
options {
aws_access_key_id = "<id>"
aws_access_key_secret = "<secret>"
aws_access_token = "<token>"
}
}
```
To force the S3-specific syntax, use the `s3::` prefix:
```hcl
artifact {
source = "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz"
}
```
Alternatively you can use virtual hosted style:
```hcl
artifact {
source = "https://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
}
```
[go-getter]: https://github.com/hashicorp/go-getter "HashiCorp go-getter Library"
[s3-bucket-addr]: http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro "Amazon S3 Bucket Addressing"
[s3-region-endpoints]: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region "Amazon S3 Region Endpoints"

223
website/source/docs/job-specification/constraint.html.md Normal file
View file

@ -0,0 +1,223 @@
---
layout: "docs"
page_title: "constraint Stanza - Job Specification"
sidebar_current: "docs-job-specification-constraint"
description: |-
The "constraint" stanza allows restricting the set of eligible nodes.
Constraints may filter on attributes or metadata. Additionally constraints may
be specified at the job, group, or task levels for ultimate flexibility.
---
# `constraint` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> **constraint**</code>
<br>
<code>job -> group -> **constraint**</code>
<br>
<code>job -> group -> task -> **constraint**</code>
</td>
</tr>
</table>
The `constraint` allows restricting the set of eligible nodes. Constraints may
filter on [attributes][interpolation] or [metadata][meta]. Additionally
constraints may be specified at the [job][job], [group][group], or [task][task]
levels for ultimate flexibility.
```hcl
job "docs" {
# All tasks in this job must run on linux.
constraint {
attribute = "${attr.kernel.name}"
value = "linux"
}
group "example" {
# All groups in this job should be scheduled on different hosts.
constraint {
operator = "distinct_hosts"
value = "true"
}
task "server" {
# All tasks must run where "my_custom_value" is greater than 3.
constraint {
attribute = "${meta.my_custom_value}"
operator = ">"
value = "3"
}
}
}
}
```
Placing constraints at both the job level and at the group level is redundant
since constraints are applied hierarchically. The job constraints will affect
all groups (and tasks) in the job.
## `constraint` Parameters
- `attribute` `(string: "")` - Specifies the name or reference of the attribute
to examine for the constraint. This can be any of the [Nomad interpolated
values](/docs/runtime/interpolation.html#interpreted_node_vars).
- `operator` `(string: "=")` - Specifies the comparison operator.The ordering is
compared lexically. Possible values include:
```text
=
!=
>
>=
<
<=
regexp
set_contains
version
```
For a detailed explanation of these values and their behavior, please see
the [operator values section](#operator-values).
- `value` `(string: "")` - Specifies the value to compare the attribute against
using the specified operation. This can be a literal value, another attribute,
or any [Nomad interpolated
values](/docs/runtime/interpolation.html#interpreted_node_vars).
### `operator` Values
This section details the specific values for the "operator" parameter in the
Nomad job specification for constraints. The operator is always specified as a
string, but the string can take on different values which change the behavior of
the overall constraint evaluation.
```hcl
constraint {
operator = "..."
}
```
- `"distinct_hosts"` - Instructs the scheduler to not co-locate any groups on
the same machine. When specified as a job constraint, it applies to all groups
in the job. When specified as a group constraint, the effect is constrained to
that group. Note that the `attribute` parameter should be omitted when using
this constraint.
```hcl
constraint {
operator = "distinct_hosts"
value = "true"
}
```
- `"regexp"` - Specifies a regular expression constraint against the attribute.
The syntax of the regular expressions accepted is the same general syntax used
by Perl, Python, and many other languages. More precisely, it is the syntax
accepted by RE2 and described at in the [Google RE2
syntax](https://golang.org/s/re2syntax).
```hcl
constraint {
attribute = "..."
operator = "regexp"
value = "[a-z0-9]"
}
```
- `"set_contains"` - Specifies a contains constraint against the attribute. The
attribute and the list being checked are split using commas. This will check
that the given attribute contains **all** of the specified elements.
```hcl
constraint {
attribute = "..."
operator = "set_contains"
value = "a,b,c"
}
```
- `"version"` - Specifies a version constraint against the attribute. This
supports a comma-separated list of constraints, including the pessimistic
operator. For more examples please see the [go-version
repository](https://github.com/hashicorp/go-version) for more specific
examples.
```hcl
constraint {
attribute = "..."
operator = "version"
value = ">= 0.1.0, < 0.2"
}
```
## `constraint` Examples
The following examples only show the `constraint` stanzas. Remember that the
`constraint` Remember that the `constraint` stanza is only valid in the
placements listed above.
### Kernel Data
This example restricts the task to running on nodes which have a kernel version
higher than "3.19".
```hcl
constraint {
attribute = "${attr.kernel.version}"
operator = "version"
value = "> 3.19"
}
```
### Operating Systems
This example restricts the task to running on nodes that are running Ubuntu
14.04
```hcl
constraint {
attribute = "${attr.os.name}"
value = "ubuntu"
}
constraint {
attribute = "${attr.os.version}"
value = "14.04"
}
```
### Cloud Metadata
When possible, Nomad populates node attributes from the cloud environment. These
values are accessible as filters in constraints. This example constrains this
task to only run on nodes that are memory-optimized on AWS.
```hcl
constraint {
attribute = "${attr.platform.aws.instance-type}"
value = "m4.xlarge"
}
```
### User-Specified Metadata
This example restricts the task to running on nodes where the binaries for
redis, cypress, and nginx are all cached locally. This particular example is
utilizing node [metadata][meta].
```hcl
constraint {
attribute = "${node.meta.cached_binaries}"
set_contains = "redis,cypress,nginx"
}
```
[job]: /docs/job-specification/job.html "Nomad job Job Specification"
[group]: /docs/job-specification/group.html "Nomad group Job Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"

76
website/source/docs/job-specification/env.html.md Normal file
View file

@ -0,0 +1,76 @@
---
layout: "docs"
page_title: "env Stanza - Job Specification"
sidebar_current: "docs-job-specification-env"
description: |-
The "env" stanza configures a list of environment variables to populate the
task's environment before starting.
---
# `env` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> task -> **env**</code>
</td>
</tr>
</table>
The `env` stanza configures a list of environment variables to populate the
task's environment before starting.
```hcl
job "docs" {
group "example" {
task "server" {
env {
my-key = "my-value"
}
}
}
}
```
## `env` Parameters
The "parameters" for the `env` stanza can be any key-value. The keys and values
are both of type `string`, but they can be specified as other types. They will
automatically be converted to strings.
## `env` Examples
The following examples only show the `env` stanzas. Remember that the `env`
Remember that the `env` stanza is only valid in the placements listed above.
### Coercion
This example shows the different ways to specify key-value pairs. Internally,
these values will be stored as their string representation. No type information
is preserved.
```hcl
env {
key = "true"
key = true
"key" = true
key = 1.4
key = "1.4"
}
```
### Interpolation
This example shows using [Nomad interpolation][interpolation] to populate
environment variables.
```hcl
env {
NODE_CLASS = "${nomad.class}"
}
```
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"

106
website/source/docs/job-specification/group.html.md Normal file
View file

@ -0,0 +1,106 @@
---
layout: "docs"
page_title: "group Stanza - Job Specification"
sidebar_current: "docs-job-specification-group"
description: |-
The "group" stanza defines a series of tasks that should be co-located on the
same Nomad client. Any task within a group will be placed on the same client.
---
# `group` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> **group**</code>
</td>
</tr>
</table>
The `group` stanza defines a series of tasks that should be co-located on the
same Nomad client. Any [task][] within a group will be placed on the same
client.
```hcl
job "docs" {
group "example" {
# ...
}
}
```
## `group` Parameters
- `constraint` <code>([Constraint][]: nil)</code> -
This can be provided multiple times to define additional constraints.
- `count` `(int: 1)` - Specifies the number of the task groups that should
be running under this group. This value must be non-negative.
- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
with user-defined metadata.
- `restart` <code>([Restart][]: nil)</code> - Specifies the restart policy for
all tasks in this group. If omitted, a default policy exists for each job
type, which can be found in the [restart stanza documentation][restart].
- `task` <code>([Task][]: required)</code> - Specifies one or more tasks to run
within this group. This can be specified multiple times, to add a task as part
of the group.
## `group` Examples
The following examples only show the `group` stanzas. Remember that the `group`
Remember that the `group` stanza is only valid in the placements listed above.
### Specifying Count
This example specifies that 5 instances of the tasks within this group should be
running:
```hcl
group "example" {
count = 5
}
```
### Tasks with Constraint
This example shows two abbreviated tasks with a constraint on the group. This
will restrict the tasks to 64-bit operating systems.
```hcl
group "example" {
constraint {
attribute = "${attr.arch}"
value = "amd64"
}
task "cache" {
# ...
}
task "server" {
# ...
}
}
```
### Metadata
This example show arbitrary user-defined metadata on the group:
```hcl
group "example" {
meta {
"my-key" = "my-value"
}
}
```
[task]: /docs/job-specification/task.html "Nomad task Specification"
[job]: /docs/job-specification/job.html "Nomad job Specification"
[constraint]: /docs/job-specification/constraint.html "Nomad constraint Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Specification"
[restart]: /docs/job-specification/restart.html "Nomad restart Specification"

133
website/source/docs/job-specification/index.html.md Normal file
View file

@ -0,0 +1,133 @@
---
layout: "docs"
page_title: "Job Specification"
sidebar_current: "docs-job-specification-syntax"
description: |-
Learn about the Job specification used to submit jobs to Nomad.
---
# Job Specification
The Nomad job specification (or "jobspec" for short) defines the schema for
Nomad jobs. Nomad jobs are specified in [HCL][], which aims to strike a balance
between human readable and editable, and machine-friendly.
The job specification is broken down into smaller pieces, which you will find
expanded in the navigation menu. We recommend getting started at the [job][]
stanza. Alternatively, you can keep reading to see a few examples.
For machine-friendliness, Nomad can also read JSON-equivalent configurations. In
general, we recommend using the HCL syntax.
The general hierarchy for a job is:
```text
job
\_ group
\_ task
```
Each job file has only a single job, however a job may have multiple groups, and
each group may have multiple tasks. Groups contain a set of tasks that are
co-located on a machine.
## Example
This example shows a sample job file. We tried to keep it as simple as possible,
while still showcasing the power of Nomad. For a more detailed explanation of
any of these fields, please use the navigation to dive deeper.
```hcl
# This declares a job named "docs". There can be exactly one
# job declaration per job file.
job "docs" {
# Specify this job should run in the region named "us". Regions
# are defined by the Nomad servers' configuration.
region = "us"
# Spread the tasks in this job between us-west-1 and us-east-1.
datacenters = ["us-west-1", "us-east-1"]
# Run this job as a "service" type. Each job type has different
# properties. See the documentation below for more examples.
type = "service"
# Specify this job to have rolling updates, two-at-a-time, with
# 30 second intervals.
update {
stagger = "30s"
max_parallel = 1
}
# A group defines a series of tasks that should be co-located
# on the same client (host). All tasks within a group will be
# placed on the same host.
group "webs" {
# Specify the number of these tasks we want.
count = 5
# Create an individual task (unit of work). This particular
# task utilizes a Docker container to front a web application.
task "frontend" {
# Specify the driver to be "docker". Nomad supports
# multiple drivers.
driver = "docker"
# Configuration is specific to each driver.
config {
image = "hashicorp/web-frontend"
}
# The service block tells Nomad how to register this service
# with Consul for service discovery and monitoring.
service {
# This tells Consul to monitor the service on the port
# labled "http". Since Nomad allocates high dynamic port
# numbers, we use labels to refer to them.
port = "http"
check {
type = "http"
path = "/health"
interval = "10s"
timeout = "2s"
}
}
# It is possible to set environment variables which will be
# available to the job when it runs.
env {
"DB_HOST" = "db01.example.com"
"DB_USER" = "web"
"DB_PASS" = "loremipsum"
}
# Specify the maximum resources required to run the job,
# include CPU, memory, and bandwidth.
resources {
cpu = 500 # MHz
memory = 128 # MB
network {
mbits = 100
# This requests a dynamic port named "http". This will
# be something like "46283", but we refer to it via the
# label "http".
port "http" {}
# This requests a static port on 443 on the host. This
# will restrict this task to running once per host, since
# there is only one port 443 on each host.
port "https" {
static = 443
}
}
}
}
}
}
```
[hcl]: https://github.com/hashicorp/hcl "HashiCorp Configuration Language"
[job]: /docs/job-specification/job.html "Nomad job Job Specification"

155
website/source/docs/job-specification/job.html.md Normal file
View file

@ -0,0 +1,155 @@
---
layout: "docs"
page_title: "job Stanza - Job Specification"
sidebar_current: "docs-job-specification-job"
description: |-
The "job" stanza is the top-most configuration option in the job
specification. A job is a declarative specification of tasks that Nomad
should run.
---
# `job` Stanza
The `job` stanza is the top-most configuration option in the job specification.
A job is a declarative specification of tasks that Nomad should run. Jobs have a
globally unique name, one or many task groups, which are themselves collections
of one or many tasks.
```hcl
job "docs" {
all_at_once = true
constraint {
# ...
}
datacenters = ["us-east-1"]
group "example" {
# ...
}
meta {
"my-key" = "my-value"
}
priority = 100
region = "north-america"
task "docs" {
# ...
}
update {
# ...
}
periodic {
# ...
}
}
```
## `job` Parameters
- `all_at_once` `(bool: false)` - 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.
- `constraint` <code>([Constraint][constraint]: nil)</code> -
This can be provided multiple times to define additional constraints. See the
[Nomad constraint reference](/docs/job-specification/constraint.html) for more
details.
- `datacenters` `(array<string>: required)` - A list of datacenters in the region which are eligible
for task placement. This must be provided, and does not have a default.
- `group` <code>([Group][group]: required)</code> - Specifies the start of a
group of tasks. This can be provided multiple times to define additional
groups. Group names must be unique within the job file.
- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
with user-defined metadata.
- `periodic` <code>([Periodic][]: nil)</code> - Allows the job to be scheduled
at fixed times, dates or intervals.
- `priority` `(int: 50)` - Specifies the job priority which is used to
prioritize scheduling and access to resources. Must be between 1 and 100
inclusively, with a larger value corresponding to a higher priority.
- `region` `(string: "global")` - The region in which to execute the job.
- `type` `(string: "service")` - Specifies the [Nomad scheduler][scheduler] to
use. Nomad provides the `service`, `system` and `batch` schedulers.
- `update` <code>([Update][update]: nil)</code> - Specifies the task's update
strategy. When omitted, rolling updates are disabled.
## `job` Examples
### Docker Container
This example job starts a Docker container which runs as a service. Even though
the type is not specified as "service", that is the default job type.
```hcl
job "docs" {
datacenters = ["default"]
group "example" {
task "server" {
driver = "docker"
config {
image = "hashicorp/http-echo"
args = ["-text", "hello"]
}
resources {
memory = 128
}
}
}
}
```
### Batch Job
This example job executes the `uptime` command across all Nomad clients in the
fleet, as long as those machines are running Linux.
```hcl
job "docs" {
datacenters = ["default"]
type = "batch"
constraint {
attribute = "${attr.kernel.name}"
value = "linux"
}
group "example" {
task "uptime" {
driver = "exec"
config {
command = "uptime"
}
resources {
cpu = 10
}
}
}
}
```
[constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification"
[group]: /docs/job-specification/group.html "Nomad group Job Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"
[periodic]: /docs/job-specification/periodic.html "Nomad periodic Job Specification"
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[update]: /docs/job-specification/update.html "Nomad update Job Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"
[scheduler]: /docs/runtime/schedulers.html "Nomad Scheduler Types"

82
website/source/docs/job-specification/logs.html.md Normal file
View file

@ -0,0 +1,82 @@
---
layout: "docs"
page_title: "logs Stanza - Job Specification"
sidebar_current: "docs-job-specification-logs"
description: |-
The "logs" stanza configures the log rotation policy for a task's stdout and
stderr. Logging is enabled by default with sane defaults. The "logs" stanza
allows for finer-grained control over how Nomad handles log files.
---
# `logs` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> task -> **logs**</code>
</td>
</tr>
</table>
The `logs` stanza configures the log rotation policy for a task's `stdout` and
`stderr`. Logging is enabled by default with sane defaults (provided in the
parameters section below), and there is currently no way to disable logging for
tasks. The `logs` stanza allows for finer-grained control over how Nomad handles
log files.
```hcl
job "docs" {
group "example" {
task "server" {
logs {
max_files = 10
max_file_size = 10
}
}
}
}
```
For information on how to interact with logs after they have been configured, please see the [`nomad logs`][logs-command] command.
## `logs` Parameters
- `max_files` `(int: 10)` - Specifies the maximum number of rotated files Nomad
will retain for `stdout` and `stderr`. Each stream is tracked individually, so
specifying a value of 2 will create 4 files - 2 for stdout and 2 for stderr
- `max_file_size` `(int: 10)` - Specifies the maximum size of each rotated file
in `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.
## `logs` Examples
The following examples only show the `logs` stanzas. Remember that the
`logs` Remember that the `logs` stanza is only valid in the placements
listed above.
### Configure Defaults
This example shows a default logging configuration. Yes, it is empty on purpose.
Nomad automatically enables logging with sane defaults as described in the
parameters section above.
```hcl
```
### Customization
This example asks Nomad to retain 3 rotated files for each of `stderr` and
`stdout`, each a maximum size of 5MB per file. The minimum disk space this
would require is 60MB (3 `stderr` &plus; 3 `stdout` &times; 5MB &equals; 30MB).
```hcl
logs {
max_files = 3
max_file_size = 5
}
```
[logs-command]: /docs/commands/logs.html "nomad logs command"

94
website/source/docs/job-specification/meta.html.md Normal file
View file

@ -0,0 +1,94 @@
---
layout: "docs"
page_title: "meta Stanza - Job Specification"
sidebar_current: "docs-job-specification-meta"
description: |-
The "meta" stanza allows for user-defined arbitrary key-value pairs.
---
# `meta` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> **meta**</code>
<br>
<code>job -> group -> **meta**</code>
<br>
<code>job -> group -> task -> **meta**</code>
</td>
</tr>
</table>
The `meta` stanza allows for user-defined arbitrary key-value pairs. It is
possible to use the `meta` stanza at the [job][], [group][], or [task][] level.
```hcl
job "docs" {
meta {
my-key = "my-value"
}
group "example" {
meta {
my-key = "my-value"
}
task "server" {
meta {
my-key = "my-value"
}
}
}
}
```
Metadata is merged up the job specification, so metadata defined at the job
level applies to all groups and tasks within that job. Metadata defined at the
group layer applies to all tasks within that group.
## `meta` Parameters
The "parameters" for the `meta` stanza can be any key-value. The keys and values
are both of type `string`, but they can be specified as other types. They will
automatically be converted to strings.
## `meta` Examples
The following examples only show the `meta` stanzas. Remember that the `meta`
Remember that the `meta` stanza is only valid in the placements listed above.
### Coercion
This example shows the different ways to specify key-value pairs. Internally,
these values will be stored as their string representation. No type information
is preserved.
```hcl
meta {
key = "true"
key = true
"key" = true
key = 1.4
key = "1.4"
}
```
### Interpolation
This example shows using [Nomad interpolation][interpolation] to populate
environment variables.
```hcl
meta {
class = "${nomad.class}"
}
```
[job]: /docs/job-specification/job.html "Nomad job Job Specification"
[group]: /docs/job-specification/group.html "Nomad group Job Specification"
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"

173
website/source/docs/job-specification/network.html.md Normal file
View file

@ -0,0 +1,173 @@
---
layout: "docs"
page_title: "network Stanza - Job Specification"
sidebar_current: "docs-job-specification-network"
description: |-
The "network" stanza specifies the networking requirements for the task,
including the minimum bandwidth and port allocations.
---
# `network` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> task -> resources -> **network**</code>
</td>
</tr>
</table>
The `network` stanza specifies the networking requirements for the task,
including the minimum bandwidth and port allocations. When scheduling jobs in
Nomad they are provisioned across your fleet of machines along with other jobs
and services. Because you don't know in advance what host your job will be
provisioned on, Nomad will provide your tasks with network configuration when
they start up.
Note that this document only applies to services that want to _listen_ on a
port. Batch jobs or services that only make outbound connections do not need to
allocate ports, since they will use any available interface to make an outbound
connection.
```hcl
job "docs" {
group "example" {
task "server" {
resources {
network {
mbits = 200
port "http" {}
port "https" {}
port "lb" {
static = "8889"
}
}
}
}
}
}
```
## `network` Parameters
- `mbits` `(int: required)` - Specifies the bandwidth required in MBits.
- `port` <code>([Port](#port-parameters): nil)</code> - Specifies a port
allocation and can be used to specify both dynamic ports and reserved ports.
### `port` Parameters
- `static` `(int: nil)` - Specifies the static port to allocate. If omitted, a dynamic port is chosen. We **do not recommend** using static ports, except
for `system` or specialized jobs like load balancers.
The label assigned to the port is used to identify the port in service
discovery, and used in the name of the environment variable that indicates
which port your application should bind to. For example:
```hcl
port "foo" {}
```
When the task starts, it will be passed the following environment variables:
- <tt>NOMAD_IP_foo</tt> - The IP to bind on for the given port label.
- <tt>NOMAD_PORT_foo</tt> - The port value for the given port label.
- <tt>NOMAD_ADDR_foo</tt> - A combined <tt>ip:port</tt> that can be used for convenience.
The label of the port is just text - it has no special meaning to Nomad.
## `network` Examples
The following examples only show the `network` stanzas. Remember that the
`network` Remember that the `network` stanza is only valid in the placements
listed above.
### Bandwidth
This example specifies a resource requirement of 1BGits in bandwidth:
```hcl
network {
mbits = 1000
}
```
### Dynamic Ports
This example specifies a dynamic port allocation for the port labeled "http".
Dynamic ports are allocated in a range from `20000` to `60000`.
Most services run in your cluster should use dynamic ports. This means that the
port will be allocated dynamically by the scheduler, and your service will have
to read an environment variable to know which port to bind to at startup.
```hcl
task "example" {
resources {
network {
port "http" {}
port "https" {}
}
}
}
```
```hcl
network {
port "http" {}
}
```
### Static Ports
This example specifies a static port allocation for the port labeled "lb". Static
ports bind your job to a specific port on the host they' are placed on. Since
multiple services cannot share a port, the port must be open in order to place
your task.
```hcl
network {
port "lb" {
static = 6539
}
}
```
### Mapped Ports
Some drivers (such as [Docker][docker-driver] and [QEMU][qemu-driver]) allow you
to map ports. A mapped port means that your application can listen on a fixed
port (it does not need to read the environment variable) and the dynamic port
will be mapped to the port in your container or virtual machine.
```hcl
task "example" {
driver = "docker"
config {
port_map = {
http = 8080
}
}
resources {
network {
port "http" {}
}
}
}
```
The above example is for the Docker driver. The service is listening on port
`8080` inside the container. The driver will automatically map the dynamic port
to this service.
When the task is started, it is passed an additional environment variable named
`NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is
bound to.
[docker-driver]: /docs/drivers/docker.html "Nomad Docker Driver"
[qemu-driver]: /docs/drivers/qemu.html "Nomad QEMU Driver"

64
website/source/docs/job-specification/periodic.html.md Normal file
View file

@ -0,0 +1,64 @@
---
layout: "docs"
page_title: "periodic Stanza - Job Specification"
sidebar_current: "docs-job-specification-periodic"
description: |-
The "periodic" stanza allows a job to run at fixed times, dates, or intervals.
The easiest way to think about the periodic scheduler is "Nomad cron" or
"distributed cron".
---
# `periodic` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> **periodic**</code>
</td>
</tr>
</table>
The `periodic` stanza allows a job to run at fixed times, dates, or intervals.
The easiest way to think about the periodic scheduler is "Nomad cron" or
"distributed cron".
```hcl
job "docs" {
periodic {
cron = "*/15 * * * * *"
prohibit_overlap = true
}
}
```
The periodic expression is always evaluated in the **UTC timezone** to ensure
consistent evaluation when Nomad spans multiple time zones.
## `periodic` Parameters
- `cron` `(string: required)` - Specifies a cron expression configuring the
interval to launch the job. In addition to [cron-specific formats][cron], this
option also includes predefined expressions such as `@daily` or `@weekly`.
- `prohibit_overlap` `(bool: false)` - Specifies if this job should wait until
previous instances of this job have completed. This only applies to this job;
it does not prevent other periodic jobs from running at the same time.
## `periodic` Examples
The following examples only show the `periodic` stanzas. Remember that the
`periodic` Remember that the `periodic` stanza is only valid in the placements
listed above.
### Run Daily
This example shows running a periodic job daily:
```hcl
periodic {
cron = "@daily"
}
```
[cron]: https://github.com/gorhill/cronexpr#implementation "List of cron expressions"

106
website/source/docs/job-specification/resources.html.md Normal file
View file

@ -0,0 +1,106 @@
---
layout: "docs"
page_title: "resources Stanza - Job Specification"
sidebar_current: "docs-job-specification-resources"
description: |-
The "resources" stanza describes the requirements a task needs to execute.
Resource requirements include memory, disk space, network, cpu, and more.
---
# `resources` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> task -> **resources**</code>
</td>
</tr>
</table>
The `resources` stanza describes the requirements a task needs to execute.
Resource requirements include memory, disk space, network, cpu, and more.
```hcl
job "docs" {
group "example" {
task "server" {
resources {
cpu = 100
disk = 50
memory = 256
network {
mbits = 100
port "http" {}
port "ssh" {
static = 22
}
}
}
}
}
}
```
## `resources` Parameters
- `cpu` `(int: 100)` - Specifies the CPU required to run this task in MHz.
- `disk` `(int: 200)` - Specifies the disk space required in MB.
- `iops` `(int: 0)` - Specifies the number of IOPS required given as a weight
between 0-1000.
- `memory` `(int: 300)` - Specifies the memory required in MB
- `network` <code>([Network][]: required)</code> - Specifies the network
requirements, including static and dynamic port allocations.
## `resources` Examples
The following examples only show the `resources` stanzas. Remember that the
`resources` Remember that the `resources` stanza is only valid in the placements
listed above.
### Disk Space
This example specifies the task requires 100MB of disk space to operate:
```hcl
resources {
disk = 100
}
```
### Memory
This example specifies the task requires 2GB of RAM to operate. 2GB is the
equivalent of 2000MB:
```hcl
resources {
memory = 2000
}
```
### Network
This example shows network constraints as specified in the [network][] stanza
which require 1GBit of bandwidth, dynamically allocates two ports, and
statically allocates one port:
```hcl
resources {
network {
mbits = 1000
port "http" {}
port "https" {}
port "lb" {
static = "8889"
}
}
}
```
[network]: /docs/job-specification/network.html "Nomad network Job Specification"

97
website/source/docs/job-specification/restart.html.md Normal file
View file

@ -0,0 +1,97 @@
---
layout: "docs"
page_title: "restart Stanza - Job Specification"
sidebar_current: "docs-job-specification-restart"
description: |-
The "restart" stanza configures a group's behavior on task failure.
---
# `restart` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> **restart**</code>
</td>
</tr>
</table>
The `restart` stanza configures a group's behavior on task failure.
```hcl
job "docs" {
group "example" {
restart {
attempts = 3
delay = "30s"
}
}
}
```
## `restart` Parameters
- `attempts` `(int: <varies>)` - Specifies the number of restarts allowed in the
configured interval. Defaults vary by job type, see below for more
information.
- `delay` `(string: "15s")` - Specifies the duration to wait before restarting a
task. This is specified using a label suffix like "30s" or "1h". A random
jitter of up to 25% is added to the delay.
- `interval` `(string: <varies>)` - Specifies the duration which 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`. This is specified using a label suffix like "30s" or
"1h". Defaults vary by job type, see below for more information.
- `mode` `(string: "delay")` - Controls the behavior when the task fails more
than `attempts` times in an interval. For a detailed explanation of these
values and their behavior, please see the [mode values section](#mode-values).
### `restart` Parameter Defaults
The values for many of the `restart` parameters vary by job type. Here are the
defaults by job type:
- The default batch restart policy is:
```hcl
restart {
attempts = 15
delay = "15s"
interval = "168h"
mode = "delay"
}
```
- The default non-batch restart policy is:
```hcl
restart {
interval = "1m"
attempts = 2
delay = "15s"
mode = "delay"
}
```
### `mode` Values
This section details the specific values for the "mode" parameter in the Nomad
job specification for constraints. The mode is always specified as a string
```hcl
restart {
mode = "..."
}
```
- `"delay"` - Instructs the scheduler to delay the next restart until the next
`interval` is reached. This is the default behavior.
- `"fail"` - Instructs the scheduler to not attempt to restart the task on
failure. This mode is useful for non-idempotent jobs which are not safe to
simply restart.

155
website/source/docs/job-specification/task.html.md Normal file
View file

@ -0,0 +1,155 @@
---
layout: "docs"
page_title: "task Stanza - Job Specification"
sidebar_current: "docs-job-specification-task"
description: |-
The "task" stanza creates an individual unit of work, such as a Docker
container, web application, or batch processing.
---
# `task` Stanza
The `task` stanza creates an individual unit of work, such as a Docker
container, web application, or batch processing.
```hcl
job "docs" {
group "example" {
task "server" {
# ...
}
}
}
```
## `task` Parameters
- `artifact` <code>([Artifact][]: nil)</code> - Defines an artifact to download
before running the task. This may be specified multiple times to download
multiple artifacts.
- `config` `(map<string|string>: nil)` - Specifies the driver configuration,
which is passed directly to the driver to start the task. The details of
configurations are specific to each driver, so please see specific driver
documentation for more information.
- `constraint` <code>([Constraint][]: nil)</code> - Specifies user-defined
constraints on the task. This can be provided multiple times to define
additional constraints.
- `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`.
- `env` <code>([Env][]: nil)</code> - Specifies environment variables that will
be passed to the running process.
- `kill_timeout` `(string: "5s")` - Specifies the duration to wait for an
application to gracefully quit before force-killing. Nomad sends an `SIGINT`.
If the task does not exit before the configured timeout, `SIGKILL` is sent to
the task.
- `logs` <code>([Logs][]: nil)</code> - Specifies logging configuration for the
`stdout` and `stderr` of the task.
- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
with user-defined metadata.
- `resources` <code>([Resources][]: required)</code> - Specifies the minimum
resource requirements such as RAM, CPU, disk, and network.
- `service` <code>([Service][]: nil)</code> - Specifies integrations with
[Consul][] for service discovery. Nomad automatically registers when a task
is started and de-registers it when the task dies.
- `user` `(string: <varies>)` - Specifies the user that will run the task. This
defaults to the same user as the Nomad client. This can only be set on Linux
platforms.
## `task` Examples
### Docker Container
This example defines a task that starts a Docker container as a service. Docker
is just one of many drivers supported by Nomad. Read more about drivers in the
[Nomad drivers documentation](/docs/drivers/index.html).
```hcl
task "server" {
driver = "docker"
config {
image = "hashicorp/http-echo"
args = ["-text", "hello world"]
}
resources {
network {
mbits = 250
}
}
}
```
### Metadata and Environment Variables
This example uses custom metadata and environment variables to pass information
to the task.
```hcl
task "server" {
driver = "exec"
config {
command = "/bin/env"
}
meta {
my-key = "my-value"
}
env {
MY_KEY = "${meta.my-key}"
}
resources {
cpu = 10
}
}
```
### Service Discovery
This example creates a service in Consul. To read more about service discovery
in Nomad, please see the [Nomad service discovery documentation][service].
```hcl
task "server" {
driver = "docker"
config {
image = "hashicorp/http-echo"
args = ["-text", "hello world"]
}
service {
tags = ["default"]
check {
type = "tcp"
interval = "10s"
timeout = "2s"
}
}
resources {
cpu = 10
}
}
```
[artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification"
[consul]: https://www.consul.io/ "Consul by HashiCorp"
[constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification"
[env]: /docs/job-specification/env.html "Nomad env Job Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"
[resources]: /docs/job-specification/resources.html "Nomad resources Job Specification"
[logs]: /docs/job-specification/logs.html "Nomad logs Job Specification"
[service]: /docs/service-discovery/index.html "Nomad Service Discovery"

71
website/source/docs/job-specification/update.html.md Normal file
View file

@ -0,0 +1,71 @@
---
layout: "docs"
page_title: "update Stanza - Job Specification"
sidebar_current: "docs-job-specification-update"
description: |-
The "update" stanza specifies the job update strategy. The update strategy is
used to control things like rolling upgrades. If omitted, rolling updates are
disabled.
---
# `update` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> **update**</code>
</td>
</tr>
</table>
The `update` stanza specifies the job update strategy. The update strategy is
used to control things like rolling upgrades. If omitted, rolling updates are
disabled.
```hcl
job "docs" {
update {
max_parallel = 3
stagger = "30s"
}
}
```
## `update` Parameters
- `max_parallel` `(int: 0)` - Specifies the number of tasks that can be updated
at the same time.
- `stagger` `(string: "0ms")` - Specifies the delay between sets of updates.
This is specified using a label suffix like "30s" or "1h".
## `update` Examples
The following examples only show the `update` stanzas. Remember that the
`update` Remember that the `update` stanza is only valid in the placements
listed above.
### Serial Upgrades
This example uses a serial upgrade strategy, meaning exactly one task will be
updated at a time, waiting 60 seconds until the next task is upgraded.
```hcl
update {
max_parallel = 1
stagger = "60s"
}
```
### Parallel Upgrades
This example performs 10 upgrades at a time, waiting 30 seconds before moving on
to the next batch:
```hcl
update {
max_parallel = 10
stagger = "30s"
}
```

562
website/source/docs/jobspec/index.html.md
View file

@ -1,562 +0,0 @@
---
layout: "docs"
page_title: "Job Specification"
sidebar_current: "docs-jobspec-syntax"
description: |-
Learn about the Job specification used to submit jobs to Nomad.
---
# Job Specification
Jobs can be specified either in [HCL](https://github.com/hashicorp/hcl) or JSON.
HCL is meant to strike a balance between human readable and editable, and
machine-friendly.
For machine-friendliness, Nomad can also read JSON configurations. In general,
we recommend using the HCL syntax.
## HCL Syntax
For a detailed description of HCL general syntax, [see this
guide](https://github.com/hashicorp/hcl#syntax). Here we cover the details of
the Job specification for Nomad:
```hcl
# This declares a job named "docs". There can be exactly one
# job declaration per job file.
job "docs" {
# Specify this job should run in the region named "us". Regions
# are defined by the Nomad servers' configuration.
region = "us"
# Spread the tasks in this job between us-west-1 and us-east-1.
datacenters = ["us-west-1", "us-east-1"]
# Run this job as a "service" type. Each job type has different
# properties. See the documentation below for more examples.
type = "service"
# Specify this job to have rolling updates, two-at-a-time, with
# 30 second intervals.
update {
stagger = "30s"
max_parallel = 1
}
# A group defines a series of tasks that should be co-located
# on the same client (host). All tasks within a group will be
# placed on the same host.
group "webs" {
# Specify the number of these tasks we want.
count = 5
# Create an individual task (unit of work). This particular
# task utilizes a Docker container to front a web application.
task "frontend" {
# Specify the driver to be "docker". Nomad supports
# multiple drivers.
driver = "docker"
# Configuration is specific to each driver.
config {
image = "hashicorp/web-frontend"
}
# The service block tells Nomad how to register this service
# with Consul for service discovery and monitoring.
service {
# This tells Consul to monitor the service on the port
# labled "http". Since Nomad allocates high dynamic port
# numbers, we use labels to refer to them.
port = "http"
check {
type = "http"
path = "/health"
interval = "10s"
timeout = "2s"
}
}
# It is possible to set environment variables which will be
# available to the job when it runs.
env {
DB_HOST = "db01.example.com"
DB_USER = "web"
DB_PASS = "loremipsum"
}
# Specify the maximum resources required to run the job,
# include CPU, memory, and bandwidth.
resources {
cpu = 500 # MHz
memory = 128 # MB
network {
mbits = 100
# This requests a dynamic port named "http". This will
# be something like "46283", but we refer to it via the
# label "http".
port "http" {}
# This requests a static port on 443 on the host. This
# will restrict this task to running once per host, since
# there is only one port 443 on each host.
port "https" {
static = 443
}
}
}
}
}
}
```
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.name}"
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:
```
meta {
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,
with a larger value corresponding to a higher priority. 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`, `system` and `batch` schedulers,
and defaults to `service`. To learn more about each scheduler type visit
[here](/docs/jobspec/schedulers.html)
<a id="update"></a>
* `update` - Specifies the task's update strategy. When omitted, rolling
updates are disabled. The `update` block supports the following keys:
* `max_parallel` - integer that specifies the number of tasks that can be
updated at the same time.
* `stagger` - introduces a delay between sets of task updates and is given as
an 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".
Here is an example `update` block:
```hcl
update {
# Update 3 tasks at a time.
max_parallel = 3
# Wait 30 seconds between updates.
stagger = "30s"
}
```
<a id="periodic"></a>
* `periodic` - `periodic` allows the job to be scheduled at fixed times, dates
or intervals. The periodic expression is always evaluated in the UTC
timezone to ensure consistent evaluation when Nomad Servers span multiple
time zones. The `periodic` block is optional and supports the following keys:
* `enabled` - determines whether the periodic job will spawn child
jobs. `enabled` is defaulted to true if the block is included.
* `cron` - 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">`prohibit_overlap`</a> - this 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.
Here is an example `periodic` block:
```hcl
periodic {
# Launch every 15 minutes
cron = "*/15 * * * * *"
# Do not allow overlapping runs.
prohibit_overlap = true
}
```
### Task Group
The `group` object supports the following keys:
* `count` - Specifies the number of the task groups that should
be running. Must be non-negative, defaults to one.
* `constraint` - This can be provided multiple times to define additional
constraints. See the constraint reference for more details.
* `restart` - 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
job type. See the [restart policy reference](#restart_policy) for more details.
* `task` - This can be specified multiple times, to add a task as
part of the group.
* `meta` - A key/value map that annotates the task group with opaque metadata.
### Task
The `task` object supports the following keys:
* `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`.
* `user` - Set the user that will run the task. It defaults to the same user
the Nomad client is being run as. This can only be set on Linux platforms.
* `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.
* `service` - Nomad integrates with Consul for service discovery. A service
block 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. [Click
here](/docs/jobspec/servicediscovery.html) to learn more about services.
* `env` - A map of key/value representing environment variables that will be
passed along to the running process. Nomad variables are interpreted when set
in the environment variable values. See the table of interpreted variables
[here](/docs/jobspec/interpreted.html).
For example the below environment map will be reinterpreted:
```hcl
env {
# The value will be interpreted by the client and set to the
# correct value.
NODE_CLASS = "${nomad.class}"
}
```
* `resources` - Provides the resource requirements of the task.
See the [resources reference](#resources) for more details.
* `meta` - Annotates the task group with opaque metadata.
<a id="kill_timeout"></a>
* `kill_timeout` - `kill_timeout` is a time duration that can be specified using
the `s`, `m`, and `h` suffixes, such as `30s`. It can be used to configure the
time between signaling a task it will be killed and actually killing it. Nomad
sends an `os.Interrupt` which on Unix systems is defined as `SIGINT`. After
the timeout a kill signal is sent (on Unix `SIGKILL`). The default
`kill_timeout` is 5 seconds.
* `logs` - Logs allows configuring log rotation for the `stdout` and `stderr`
buffers of a Task. See the [log rotation section](#log_rotation) for more details.
* `artifact` - Defines an artifact to be downloaded before the task is run. This
can be provided multiple times to define additional artifacts to download. See
the [artifacts reference section](#artifact_doc) for more details.
### Resources
The `resources` object supports the following keys:
* `cpu` - The CPU required in MHz. Defaults to `100`.
* `disk` - The disk required in MB. Defaults to `200`.
* `iops` - The number of IOPS required given as a weight between 10-1000. Defaults to `0`.
* `memory` - The memory required in MB. Defaults to `300`.
* `network` - The network required. Details below.
The `network` object supports the following keys:
* `mbits` (required) - The number of MBits in bandwidth required.
* `port` - a repeatable object that can be used to specify both
dynamic ports and reserved ports. It has the following format:
```hcl
port "label" {
# If the `static` field is omitted, a dynamic port is assigned.
static = 6539
}
```
<a id="restart_policy"></a>
### Restart Policy
The `restart` object supports the following keys:
* `attempts` - `attempts` is the number of restarts allowed in an `interval`.
* `interval` - `interval` is a time duration that can be specified using the
`s`, `m`, and `h` suffixes, such as `30s`. 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`.
* `delay` - A duration to wait before restarting a task. It is specified as a
time duration using the `s`, `m`, and `h` suffixes, such as `30s`. A random
jitter of up to 25% is added to the delay.
* `mode` - Controls the behavior when the task fails more than `attempts` times
in an interval. Possible values are listed below:
* `delay` - delay the next restart until the next `interval` is reached.
* `fail` - do not restart the task again on failure.
The default `batch` restart policy is:
```hcl
restart {
attempts = 15
delay = "15s"
interval = "168h" # 7 days
mode = "delay"
}
```
The default non-batch restart policy is:
```hcl
restart {
interval = "1m"
attempts = 2
delay = "15s"
mode = "delay"
}
```
### Constraint
The `constraint` object supports the following keys:
* `attribute` - Specifies the attribute to examine for the
constraint. See the table of attributes [here](/docs/jobspec/interpreted.html#interpreted_node_vars).
* `operator` - Specifies the comparison operator. Defaults to equality, and can
be `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The ordering is
compared lexically. The following are equivalent:
* `=`, `==` and `is`
* `!=` and `not`
* `value` - Specifies the value to compare the attribute against.
This can be a literal value or another attribute.
* `version` - Specifies a version constraint against the attribute.
This sets the operator to `version` and the `value` to what is
specified. This supports a comma-separated list of constraints,
including the pessimistic operator. See the
[go-version](https://github.com/hashicorp/go-version) repository
for examples.
* `regexp` - Specifies a regular expression constraint against
the attribute. This sets the operator to "regexp" and the `value`
to the regular expression.
* `set_contains` - Specifies a set contains constraint against
the attribute. This sets the operator to "set_contains" and the `value`
to the what is specified. This will check that the given attribute contains
each of the specified elements. The attribute and the list being checked are
split using commas.
* `distinct_hosts` - `distinct_hosts` accepts a boolean value and defaults to
`false`. 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
scopes the effect to just that group.
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.
<a id="log_rotation"></a>
### Log Rotation
The `logs` object configures the log rotation policy for a task's `stdout` and
`stderr`. The `logs` object supports the following keys:
* `max_files` - The maximum number of rotated files Nomad will retain for
`stdout` and `stderr`, each tracked individually.
* `max_file_size` - The size of each rotated file. The size is specified in
`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.
```hcl
logs {
max_files = 3
max_file_size = 10 # Size is in MB
}
```
In the above example we have asked Nomad to retain 3 rotated files for each of
`stderr` and `stdout`, each a maximum size of 10MB per file. The minimum disk
space this would require is 60MB
(3 `stderr` files * 3 `stdout` files * 10MB = 60MB).
<a id="artifact_doc"></a>
### 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
source. The key/value pairs given in the `options` block map directly to
parameters appended to the supplied `source` URL. These are then used by
`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.
The `artifact` object supports the following keys:
* `source` - The path to the artifact to download.
* `destination` - An optional path to download the artifact into relative to the
root of the task's directory. If the `destination` key is omitted, it will
default to `local/`.
* `options` - The `options` block allows setting parameters 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:
```hcl
options {
# Validate the downloaded artifact
checksum = "md5:c4aa853ad2215426eb7d70a21922e794"
# S3 options for downloading artifacts from S3
aws_access_key_id = "<id>"
aws_access_key_secret = "<secret>"
aws_access_token = "<token>"
}
```
An example of downloading and unzipping an archive is as simple as:
```hcl
artifact {
# The archive will be extracted before the task is run,
# making it easy to ship configurations with your binary.
source = "https://example.com/my.zip"
options {
checksum = "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3"
}
}
```
#### 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:
```hcl
artifact {
source = "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz"
}
```
or to override automatic detection in the URL, use the S3-specific syntax
```hcl
artifact {
source = "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz"
}
```
Virtual hosted based style
```hcl
artifact {
source = "my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
}
```
## 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 [JSON API documentation](/docs/jobspec/json.html) for more details on
the JSON structure.

115
website/source/docs/jobspec/networking.html.md
View file

@ -1,115 +0,0 @@
---
layout: "docs"
page_title: "Networking"
sidebar_current: "docs-jobspec-networking"
description: |-
Learn how to configure networking and ports for Nomad tasks.
---
# Networking
When scheduling jobs in Nomad they are provisioned across your fleet of
machines along with other jobs and services. Because you don't know in advance
what host your job will be provisioned on, Nomad will provide your tasks with
network configuration when they start up.
Note that this document only applies to services that want to _listen_
on a port. Batch jobs or services that only make outbound connections do not
need to allocate ports, since they will use any available interface to make an
outbound connection.
## Ports
In addition to allocating an interface, Nomad can allocate static or dynamic
ports to your task.
### Dynamic Ports
Dynamic ports are allocated in a range from `20000` to `60000`.
Most services run in your cluster should use dynamic ports. This means that the
port will be allocated dynamically by the scheduler, and your service will have
to read an environment variable (see below) to know which port to bind to at
startup.
```hcl
task "example" {
resources {
network {
port "http" {}
port "https" {}
}
}
}
```
### Static Ports
Static ports bind your job to a specific port on the host they're placed on.
Since multiple services cannot share a port, the port must be open in order to
place your task.
```hcl
task "example" {
resources {
network {
port "dns" {
static = 53
}
}
}
}
```
We recommend _only_ using static ports for [system
jobs](/docs/jobspec/schedulers.html) or specialized jobs like load balancers.
### Labels and Environment Variables
The label assigned to the port is used to identify the port in service
discovery, and used for the name of the environment variable that indicates
which port your application should bind to. For example, we've labeled this
port `http`:
```hcl
port "http" {}
```
When the task is started, it is passed the following environment variables:
* `NOMAD_IP_http` - The IP to bind on for the given port label.
* `NOMAD_PORT_http` - The port value for the given port label.
* `NOMAD_ADDR_http` - A combined `IP:Port` that can be used for convenience.
### Mapped Ports <a id="mapped_ports"></a>
Some drivers (such as Docker and QEMU) allow you to map ports. A mapped port
means that your application can listen on a fixed port (it does not need to
read the environment variable) and the dynamic port will be mapped to the port
in your container or VM.
```hcl
task "example" {
driver = "docker"
port "http" {}
config {
port_map = {
http = 8080
}
}
}
```
The above example is for the Docker driver. The service is listening on port
`8080` inside the container. The driver will automatically map the dynamic port
to this service.
When the task is started, it is passed an additional environment variable named
`NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is
bound to.
Please refer to the [Docker](/docs/drivers/docker.html) and [QEMU](/docs/drivers/qemu.html) drivers for additional information.

2
website/source/docs/operating-a-job/accessing-logs.html.md
View file

@ -14,7 +14,7 @@ Viewing application logs is critical for debugging issues, examining performance
problems, or even just verifying the application started correctly. To make this
as simple as possible, Nomad provides:
- Job specification for [log rotation](/docs/jobspec/index.html#log_rotation)
- Job specification for [log rotation](/docs/job-specification/logs.html)
- CLI command for [log viewing](/docs/commands/logs.html)
- API for programatic [log access](/docs/http/client-fs.html#logs)

6
website/source/docs/operating-a-job/configuring-tasks.html.md
View file

@ -68,7 +68,7 @@ job "docs" {
Nomad has many [drivers](/docs/drivers/index.html), and most support passing
arguments to their tasks via the `args` parameter. This option also optionally
accepts [Nomad interpolation](/docs/jobspec/interpreted.html). For example, if
accepts [Nomad interpolation](/docs/runtime/interpolation.html). For example, if
you wanted Nomad to dynamically allocate a high port to bind the service on
intead of relying on a static port for the previous job:
@ -103,7 +103,7 @@ job "docs" {
Not all applications accept their configuration via command-line flags.
Sometimes applications accept their configurations using files instead. Nomad
supports downloading [artifacts](/docs/jobspec/index.html#artifact_doc) prior to
supports downloading [artifacts](/docs/job-specification/artifact.html) prior to
launching tasks. This allows shipping of configuration files and other assets
that the task needs to run properly.
@ -133,4 +133,4 @@ job "docs" {
}
```
For more information on the artifact resource, please see the [artifact documentation](/docs/jobspec/index.html#artifact_doc).
For more information on the artifact resource, please see the [artifact documentation](/docs/job-specification/artifact.html).

2
website/source/docs/operating-a-job/index.html.md
View file

@ -10,7 +10,7 @@ description: |-
The general flow for operating a job in Nomad is:
1. Author the job file according to the [job specification](/docs/jobspec/index.html)
1. Author the job file according to the [job specification](/docs/job-specification/index.html)
1. Plan and review the changes with a Nomad server
1. Submit the job file to a Nomad server
1. (Optional) Review job status and logs

5
website/source/docs/operating-a-job/submitting-jobs.html.md
View file

@ -24,9 +24,10 @@ The general flow for submitting a job in Nomad is:
Here is a very basic example to get you started.
## Author a Job File
Authoring a job file is very easy. For more detailed information, please see the
[job specification](/docs/jobspec/index.html). Here is a sample job file which
runs a small docker container web server to get us started.
[job specification](/docs/job-specification/index.html). Here is a sample job
file which runs a small docker container web server to get us started.
```hcl
job "docs" {

2
website/source/docs/operating-a-job/update-strategies/blue-green-and-canary-deployments.html.md
View file

@ -148,5 +148,5 @@ job "docs" {
Here you can see there is exactly one canary version of our application (v1.4)
and ten regular versions. Typically canary versions are also tagged
appropriately in the [service discovery](/docs/jobspec/servicediscovery.html)
appropriately in the [service discovery](/docs/service-discovery/index.html)
layer to prevent unnecessary routing.

4
website/source/docs/operating-a-job/update-strategies/handling-signals.html.md
View file

@ -33,5 +33,5 @@ job "docs" {
}
```
For more detail on the `kill_timeout` option, please see the [job specification
documentation](/docs/jobspec/index.html#kill_timeout).
For more detail on the `kill_timeout` option, please see the
[job specification documentation](/docs/job-specification/task.html#kill_timeout).

6
website/source/docs/operating-a-job/update-strategies/rolling-upgrades.html.md
View file

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Rolling Upgrades - Operating a Job"
sidebar_current: "docs-operating-a-job-updating-rolling-upgrades"
description: |-
In order to update a service while reducing downtime, Nomad provides a
In order to update a service while reducing downtime, Nomad provides a
built-in mechanism for rolling upgrades. Rolling upgrades allow for a subset
of applications to be updated at a time, with a waiting period between to
reduce downtime.
@ -86,5 +86,5 @@ potentially invalid.
Here we can see that Nomad will destroy the 3 existing tasks and create 3
replacements but it will occur with a rolling update with a stagger of `30s`.
For more details on the `update` block, see the [job specification
documentation](/docs/jobspec/index.html#update).
For more details on the `update` block, see the
[job specification documentation](/docs/job-specification/update.html).

12
website/source/docs/jobspec/environment.html.md → website/source/docs/runtime/environment.html.md
View file

@ -1,14 +1,14 @@
---
layout: "docs"
page_title: "Runtime Environment"
sidebar_current: "docs-jobspec-environment"
page_title: "Environment - Runtime"
sidebar_current: "docs-runtime-environment"
description: |-
Learn how to configure the Nomad runtime environment.
---
# Runtime Environment
Some settings you specify in your [job specification](/docs/jobspec/) are passed
Some settings you specify in your [job specification][jobspec] are passed
to tasks when they start. Other settings are dynamically allocated when your job
is scheduled. Both types of values are made available to your job through
environment variables.
@ -112,10 +112,10 @@ cluster gets more or less busy.
### Networking
Nomad assigns IPs and ports to your jobs and exposes them via environment
variables. See the [Networking](/docs/jobspec/networking.html) page for more
variables. See the [Networking](/docs/job-specification/network.html) page for more
details.
### Task Directories <a id="task_dir"></a>
### Task Directories
Nomad makes the following two directories available to tasks:
@ -147,3 +147,5 @@ environment variables, where `key` is UPPERCASED from the job specification.
Currently there is no enforcement that the meta keys be lowercase, but using
multiple keys with the same uppercased representation will lead to undefined
behavior.
[jobspec]: /docs/job-specification/index.html "Nomad Job Specification"

20
website/source/docs/runtime/index.html.md Normal file
View file

@ -0,0 +1,20 @@
---
layout: "docs"
page_title: "Runtime"
sidebar_current: "docs-runtime"
description: |-
Learn about Nomad's runtime environment variables, interpolation, caveats,
and more.
---
# Runtime
This section details nomad's runtime information, including environment
variables, interpolations, caveats, and more.
To learn more about Nomad's runtime, choose an item from the sidebar, or choose
one of the options below:
- [Environment](/docs/runtime/environment.html)
- [Interpolation](/docs/runtime/interpolation.html)
- [Schedulers](/docs/runtime/schedulers.html)

31
website/source/docs/jobspec/interpreted.html.md → website/source/docs/runtime/interpolation.html.md
View file

@ -1,17 +1,18 @@
---
layout: "docs"
page_title: "Interpreted Variables"
sidebar_current: "docs-jobspec-interpreted"
page_title: "Interpolation - Runtime"
sidebar_current: "docs-runtime-interpolation"
description: |-
Learn about the Nomad's interpreted variables.
Learn about the Nomad's interpolation and interpreted variables.
---
# Interpreted Variables
Nomad supports interpreting two classes of variables, node attributes and runtime
environment variables. Node attributes are interpretable in constraints, task
environment variables and certain driver fields. Runtime environment variables
are not interpretable in constraints because they are only defined once the
scheduler has placed them on a particular node.
# Interpolation
Nomad supports interpreting two classes of variables, node attributes and
runtime environment variables. Node attributes are interpretable in constraints,
task environment variables and certain driver fields. Runtime environment
variables are not interpretable in constraints because they are only defined
once the scheduler has placed them on a particular node.
The syntax for interpreting variables is `${variable}`. An example and a
comprehensive list of interpretable fields can be seen below:
@ -194,11 +195,11 @@ a particular node and as such can not be used in constraints.
</tr>
<tr>
<td><tt>${NOMAD_ALLOC_DIR}</tt></td>
<td>The path to the shared <tt>alloc/</tt> directory. See [here](/docs/jobspec/environment.html#task_dir) for more information.</td>
<td>The path to the shared <tt>alloc/</tt> directory. See [here](/docs/runtime/environment.html#task-directories) for more information.</td>
</tr>
<tr>
<td><tt>${NOMAD_TASK_DIR}</tt></td>
<td>The path to the task <tt>local/</tt> directory. See [here](/docs/jobspec/environment.html#task_dir) for more information.</td>
<td>The path to the task <tt>local/</tt> directory. See [here](/docs/runtime/environment.html#task-directories) for more information.</td>
</tr>
<tr>
<td><tt>${NOMAD_MEMORY_LIMIT}</tt></td>
@ -231,21 +232,21 @@ a particular node and as such can not be used in constraints.
<tr>
<td><tt>${NOMAD_IP_&lt;label&gt;}</tt></td>
<td>The IP for the given port <tt>label</tt>. See
[here](/docs/jobspec/networking.html) for more information.</td>
[here](/docs/job-specification/network.html) for more information.</td>
</tr>
<tr>
<td><tt>${NOMAD_PORT_&lt;label&gt;}</tt></td>
<td>The port for the port <tt>label</tt>. See [here](/docs/jobspec/networking.html) for more information.</td>
<td>The port for the port <tt>label</tt>. See [here](/docs/job-specification/network.html) for more information.</td>
</tr>
<tr>
<td><tt>${NOMAD_ADDR_&lt;label&gt;}</tt></td>
<td>The <tt>ip:port</tt> pair for the given port <tt>label</tt>. See
[here](/docs/jobspec/networking.html) for more information.</td>
[here](/docs/job-specification/network.html) for more information.</td>
</tr>
<tr>
<td><tt>${NOMAD_HOST_PORT_&lt;label&gt;}</tt></td>
<td>The port on the host if port forwarding is being used for the port
<tt>label</tt>. See [here](/docs/jobspec/networking.html#mapped_ports) for more
<tt>label</tt>. See [here](/docs/job-specification/network.html#mapped_ports) for more
information.</td>
</tr>
<tr>

10
website/source/docs/jobspec/schedulers.html.md → website/source/docs/runtime/schedulers.html.md
View file

@ -1,16 +1,16 @@
---
layout: "docs"
page_title: "Scheduler Types"
sidebar_current: "docs-jobspec-schedulers"
page_title: "Scheduler Types - Runtime"
sidebar_current: "docs-runtime-schedulers"
description: |-
Learn about Nomad's various schedulers.
---
# Scheduler Types
Nomad has three scheduler types that can be used when creating your
[job](/docs/jobspec/): `service`, `batch` and `system`. Here we will describe
the differences between each of these schedulers.
Nomad has three scheduler types that can be used when creating your job:
`service`, `batch` and `system`. Here we will describe the differences between
each of these schedulers.
## Service

2
website/source/docs/jobspec/servicediscovery.html.md → website/source/docs/service-discovery/index.html.md
View file

@ -1,7 +1,7 @@
---
layout: "docs"
page_title: "Service Discovery"
sidebar_current: "docs-jobspec-service-discovery"
sidebar_current: "docs-service-discovery"
description: |-
Learn how to add service discovery to jobs
---

8
website/source/intro/getting-started/jobs.html.md
View file

@ -13,8 +13,8 @@ Nomad. A job is a declarative specification of tasks that Nomad should run.
Jobs have a globally unique name, one or many task groups, which are themselves
collections of one or many tasks.
The format of the jobs is [documented here](/docs/jobspec/index.html). They
can either be specified in [HashiCorp Configuration Language](https://github.com/hashicorp/hcl) (HCL) or JSON,
The format of the jobs is documented in the [job specification][jobspec]. They
can either be specified in [HashiCorp Configuration Language][hcl] or JSON,
however we recommend only using JSON when the configuration is generated by a machine.
## Running a Job
@ -241,7 +241,7 @@ Here we can see the `plan` reports it will do three create/destroy updates
which stops the old tasks and starts the new tasks because we have changed the
version of redis to run. We also see that the update will happen with a rolling
update. This is because our example job is configured to do a rolling update
via the `stagger` attribute, doing a single update every 10 seconds.
via the `stagger` attribute, doing a single update every 10 seconds.
Once ready, use `run` to push the updated specification now:
@ -300,3 +300,5 @@ how to create and scale our job, perform an application update,
and do a job tear down. Next we will add another Nomad
client to [create our first cluster](cluster.html)
[jobspec]: /docs/job-specification/index.html "Nomad Job Specification"
[hcl]: https://github.com/hashicorp/hcl "HashiCorp Configuration Language"

2
website/source/layouts/_header.erb
View file

@ -6,7 +6,7 @@
<div class="navbar-header">
<div class="navbar-brand">
<a class="logo" href="/">Nomad</a>
<a class="by" href="https://www.hashicorp.com/"><span class="svg-wrap">by</span><%= partial "layouts/svg/svg-by-hashicorp" %><%= partial "layouts/svg/svg-hashicorp-logo" %>Hashicorp</a>
<a class="by" href="https://www.hashicorp.com/"><span class="svg-wrap">by</span><%= partial "layouts/svg/svg-by-hashicorp" %><%= partial "layouts/svg/svg-hashicorp-logo" %>HashiCorp</a>
</div>
<button class="navbar-toggle" type="button">
<span class="sr-only">Toggle navigation</span>

6
website/source/layouts/_meta.erb
View file

@ -3,11 +3,11 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="<%= current_page.data.description %>">
<meta name="description" content="<%= description_for(current_page) %>">
<link rel="shortcut icon" href="<%= image_path('favicon.png') %>">
<title><%= [current_page.data.page_title, "Nomad by HashiCorp"].compact.join(" - ") %></title>
<title><%= title_for(current_page) %></title>
<%= stylesheet_link_tag "application" %>
@ -18,4 +18,4 @@
<%= yield_content :head %>
</head>
<body id="page-<%= current_page.data.page_title ? "#{current_page.data.page_title}" : "home" %>" class="<%= yield_content(:body_class) %> page-<%= current_page.data.page_title ? "#{current_page.data.page_title} layout-#{current_page.data.layout} page-sub" : "home layout-#{current_page.data.layout}" %> -displaying-bnr">
<body id="<%= body_id_for(current_page) %>" class="<%= body_classes_for(current_page) %>">

79
website/source/layouts/docs.erb
View file

@ -24,33 +24,70 @@
</ul>
</li>
<li<%= sidebar_current("docs-jobspec") %>>
<a href="/docs/jobspec/index.html">Job Specification</a>
<li<%= sidebar_current("docs-runtime") %>>
<a href="/docs/runtime/index.html">Runtime</a>
<ul class="nav">
<li<%= sidebar_current("docs-jobspec-syntax") %>>
<a href="/docs/jobspec/index.html">HCL Syntax</a>
<li<%= sidebar_current("docs-runtime-environment") %>>
<a href="/docs/runtime/environment.html">Environment</a>
</li>
<li<%= sidebar_current("docs-jobspec-json-syntax") %>>
<a href="/docs/jobspec/json.html">JSON Syntax</a>
<li<%= sidebar_current("docs-runtime-interpolation") %>>
<a href="/docs/runtime/interpolation.html">Interpolation</a>
</li>
<li<%= sidebar_current("docs-jobspec-interpreted") %>>
<a href="/docs/jobspec/interpreted.html">Interpreted Variables</a>
</li>
<li<%= sidebar_current("docs-jobspec-environment") %>>
<a href="/docs/jobspec/environment.html">Runtime Environment</a>
</li>
<li<%= sidebar_current("docs-jobspec-schedulers") %>>
<a href="/docs/jobspec/schedulers.html">Scheduler Types</a>
</li>
<li<%= sidebar_current("docs-jobspec-service-discovery") %>>
<a href="/docs/jobspec/servicediscovery.html">Service Discovery</a>
</li>
<li<%= sidebar_current("docs-jobspec-networking") %>>
<a href="/docs/jobspec/networking.html">Networking</a>
<li<%= sidebar_current("docs-runtime-schedulers") %>>
<a href="/docs/runtime/schedulers.html">Schedulers</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-job-specification") %>>
<a href="/docs/job-specification/index.html">Job Specification</a>
<ul class="nav">
<li<%= sidebar_current("docs-job-specification-artifact")%>>
<a href="/docs/job-specification/artifact.html">artifact</a>
</li>
<li<%= sidebar_current("docs-job-specification-constraint")%>>
<a href="/docs/job-specification/constraint.html">constraint</a>
</li>
<li<%= sidebar_current("docs-job-specification-env")%>>
<a href="/docs/job-specification/env.html">env</a>
</li>
<li<%= sidebar_current("docs-job-specification-group")%>>
<a href="/docs/job-specification/group.html">group</a>
</li>
<li<%= sidebar_current("docs-job-specification-job")%>>
<a href="/docs/job-specification/job.html">job</a>
</li>
<li<%= sidebar_current("docs-job-specification-logs")%>>
<a href="/docs/job-specification/logs.html">logs</a>
</li>
<li<%= sidebar_current("docs-job-specification-meta")%>>
<a href="/docs/job-specification/meta.html">meta</a>
</li>
<li<%= sidebar_current("docs-job-specification-network")%>>
<a href="/docs/job-specification/network.html">network</a>
</li>
<li<%= sidebar_current("docs-job-specification-periodic")%>>
<a href="/docs/job-specification/periodic.html">periodic</a>
</li>
<li<%= sidebar_current("docs-job-specification-resources")%>>
<a href="/docs/job-specification/resources.html">resources</a>
</li>
<li<%= sidebar_current("docs-job-specification-restart")%>>
<a href="/docs/job-specification/restart.html">restart</a>
</li>
<li<%= sidebar_current("docs-job-specification-task")%>>
<a href="/docs/job-specification/task.html">task</a>
</li>
<li<%= sidebar_current("docs-job-specification-update")%>>
<a href="/docs/job-specification/update.html">update</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-service-discovery") %>>
<a href="/docs/service-discovery/index.html">Service Discovery</a>
</li>
<li<%= sidebar_current("docs-operating-a-job") %>>
<a href="/docs/operating-a-job/index.html">Operating a Job</a>
<ul class="nav">
@ -87,7 +124,7 @@
</li>
<li<%= sidebar_current("docs-drivers") %>>
<a href="/docs/drivers/index.html">Task Drivers</a>
<a href="/docs/drivers/index.html">Drivers</a>
<ul class="nav">
<li<%= sidebar_current("docs-drivers-docker") %>>
<a href="/docs/drivers/docker.html">Docker</a>

41
website/source/layouts/http.erb
View file

@ -10,7 +10,11 @@
<li<%= sidebar_current("docs-http-overview") %>>
<a href="/docs/http/index.html">Overview</a>
</li>
</li>
<li<%= sidebar_current("docs-http-json-jobs") %>>
<a href="/docs/http/json-jobs.html">JSON Jobs</a>
</li>
<li<%= sidebar_current("docs-http-job") %>>
<a href="#">Jobs</a>
@ -23,7 +27,7 @@
<a href="/docs/http/job.html">/v1/job</a>
</li>
</ul>
</li>
</li>
<li<%= sidebar_current("docs-http-node") %>>
<a href="#">Nodes</a>
@ -49,7 +53,7 @@
<a href="/docs/http/alloc.html">/v1/allocation</a>
</li>
</ul>
</li>
</li>
<li<%= sidebar_current("docs-http-eval") %>>
<a href="#">Evaluations</a>
@ -69,15 +73,15 @@
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-agent-self") %>>
<a href="/docs/http/agent-self.html">/v1/agent/self</a>
</li>
</li>
<li<%= sidebar_current("docs-http-agent-join") %>>
<a href="/docs/http/agent-join.html">/v1/agent/join</a>
</li>
</li>
<li<%= sidebar_current("docs-http-agent-members") %>>
<a href="/docs/http/agent-members.html">/v1/agent/members</a>
</li>
</li>
<li<%= sidebar_current("docs-http-agent-force-leave") %>>
<a href="/docs/http/agent-force-leave.html">/v1/agent/force-leave</a>
@ -87,36 +91,35 @@
<a href="/docs/http/agent-servers.html">/v1/agent/servers</a>
</li>
</ul>
</li>
</li>
<li<%= sidebar_current("docs-http-client") %>>
<a href="#">Client</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-client-fs") %>>
<a href="/docs/http/client-fs.html">/v1/client/fs</a>
</li>
</li>
<li<%= sidebar_current("docs-http-client-stats") %>>
<li<%= sidebar_current("docs-http-client-stats") %>>
<a href="/docs/http/client-stats.html">/v1/client/stats</a>
</li>
</li>
<li<%= sidebar_current("docs-http-client-allocation-stats") %>>
<li<%= sidebar_current("docs-http-client-allocation-stats") %>>
<a href="/docs/http/client-allocation-stats.html">/v1/client/allocation</a>
</li>
</li>
</ul>
</li>
</li>
<li<%= sidebar_current("docs-http-regions") %>>
<a href="/docs/http/regions.html">Regions</a>
</li>
<li<%= sidebar_current("docs-http-regions") %>>
<a href="/docs/http/regions.html">Regions</a>
</li>
<li<%= sidebar_current("docs-http-status") %>>
<a href="/docs/http/status.html">Status</a>
</li>
</li>
<li<%= sidebar_current("docs-http-system") %>>
<a href="/docs/http/system.html">System</a>
</li>
</li>
</ul>
</div>
<% end %>