diff --git a/website/Gemfile b/website/Gemfile index 360489e56..be3179745 100644 --- a/website/Gemfile +++ b/website/Gemfile @@ -1,3 +1,3 @@ source "https://rubygems.org" -gem "middleman-hashicorp", "0.3.3" +gem "middleman-hashicorp", "0.3.4" diff --git a/website/Gemfile.lock b/website/Gemfile.lock index 2a223a05d..08bac5e9b 100644 --- a/website/Gemfile.lock +++ b/website/Gemfile.lock @@ -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 diff --git a/website/Makefile b/website/Makefile index be5c1d1ce..f776fc319 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,4 +1,4 @@ -VERSION?="0.3.3" +VERSION?="0.3.4" website: @echo "==> Starting website in Docker..." diff --git a/website/config.rb b/website/config.rb index 415076ccf..9df483a2a 100644 --- a/website/config.rb +++ b/website/config.rb @@ -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 diff --git a/website/helpers/command_helpers.rb b/website/helpers/command_helpers.rb deleted file mode 100644 index 451fe50c6..000000000 --- a/website/helpers/command_helpers.rb +++ /dev/null @@ -1,15 +0,0 @@ -module CommandHelpers - # Returns the markdown text for the general options usage. - def general_options_usage() - <`: The address of the Nomad server. Overrides the `NOMAD_ADDR` - environment variable if set. Defaults to `http://127.0.0.1:4646`. - -* `-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 diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 1d266f27e..7fcc73b9b 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -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; } diff --git a/website/source/docs/agent/config.html.md b/website/source/docs/agent/config.html.md index f0fe59f22..269588638 100644 --- a/website/source/docs/agent/config.html.md +++ b/website/source/docs/agent/config.html.md @@ -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:
* `http`: The port used to run the HTTP server. Applies to both client and @@ -184,7 +184,7 @@ nodes, unless otherwise specified: * `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:
* `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:
* `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:
* `infrastructure`: 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:
* `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:
* `enabled`: A boolean indicating if client mode is enabled. All other client @@ -437,12 +437,12 @@ configured on server nodes. * `node_class`: 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. - * `meta`: This is a key/value mapping of metadata pairs. This + * `meta`: This is a key-value mapping of metadata pairs. This is a free-form map and can contain any string values. - * `options`: This is a key/value mapping of internal + * `options`: 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. - * `chroot_env`: This is a key/value mapping that + * `chroot_env`: 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. * `network_interface`: This is a string to force diff --git a/website/source/docs/commands/_general_options.html.md b/website/source/docs/commands/_general_options.html.md new file mode 100644 index 000000000..a3d95dfb6 --- /dev/null +++ b/website/source/docs/commands/_general_options.html.md @@ -0,0 +1,28 @@ +- `-address=`: The address of the Nomad server. Overrides the `NOMAD_ADDR` + environment variable if set. Defaults to `http://127.0.0.1:4646`. + +- `-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 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 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 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 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. diff --git a/website/source/docs/commands/agent-info.html.md.erb b/website/source/docs/commands/agent-info.html.md.erb index ceb7f3448..d4eef9353 100644 --- a/website/source/docs/commands/agent-info.html.md.erb +++ b/website/source/docs/commands/agent-info.html.md.erb @@ -20,7 +20,7 @@ nomad agent-info [options] ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Output diff --git a/website/source/docs/commands/alloc-status.html.md.erb b/website/source/docs/commands/alloc-status.html.md.erb index 66707e990..46eb7e091 100644 --- a/website/source/docs/commands/alloc-status.html.md.erb +++ b/website/source/docs/commands/alloc-status.html.md.erb @@ -25,7 +25,7 @@ allocations and information will be displayed. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Alloc Status Options diff --git a/website/source/docs/commands/client-config.html.md.erb b/website/source/docs/commands/client-config.html.md.erb index 0a70461b4..b72f2b296 100644 --- a/website/source/docs/commands/client-config.html.md.erb +++ b/website/source/docs/commands/client-config.html.md.erb @@ -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 diff --git a/website/source/docs/commands/eval-status.html.md.erb b/website/source/docs/commands/eval-status.html.md.erb index 05a8c23b1..713ba331f 100644 --- a/website/source/docs/commands/eval-status.html.md.erb +++ b/website/source/docs/commands/eval-status.html.md.erb @@ -40,7 +40,7 @@ indicated by exit code 1. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Eval Status Options diff --git a/website/source/docs/commands/fs.html.md.erb b/website/source/docs/commands/fs.html.md.erb index 4e96237ca..a28fa404a 100644 --- a/website/source/docs/commands/fs.html.md.erb +++ b/website/source/docs/commands/fs.html.md.erb @@ -33,7 +33,7 @@ defaults to `/` of the allocation directory. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Fs Options diff --git a/website/source/docs/commands/init.html.md.erb b/website/source/docs/commands/init.html.md.erb index 21206f757..61efa4b08 100644 --- a/website/source/docs/commands/init.html.md.erb +++ b/website/source/docs/commands/init.html.md.erb @@ -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" diff --git a/website/source/docs/commands/inspect.html.md.erb b/website/source/docs/commands/inspect.html.md.erb index e29974001..3517416db 100644 --- a/website/source/docs/commands/inspect.html.md.erb +++ b/website/source/docs/commands/inspect.html.md.erb @@ -23,7 +23,7 @@ version of a job Nomad is running. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Inspect Options diff --git a/website/source/docs/commands/logs.html.md.erb b/website/source/docs/commands/logs.html.md.erb index 8c4de0191..68aa7cade 100644 --- a/website/source/docs/commands/logs.html.md.erb +++ b/website/source/docs/commands/logs.html.md.erb @@ -23,7 +23,7 @@ the given job will be chosen. # ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Logs Options diff --git a/website/source/docs/commands/node-drain.html.md.erb b/website/source/docs/commands/node-drain.html.md.erb index 64096e55b..443967ff6 100644 --- a/website/source/docs/commands/node-drain.html.md.erb +++ b/website/source/docs/commands/node-drain.html.md.erb @@ -31,7 +31,7 @@ operation is desired. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Node Drain Options diff --git a/website/source/docs/commands/node-status.html.md.erb b/website/source/docs/commands/node-status.html.md.erb index d55628359..b52e19317 100644 --- a/website/source/docs/commands/node-status.html.md.erb +++ b/website/source/docs/commands/node-status.html.md.erb @@ -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 diff --git a/website/source/docs/commands/plan.html.md.erb b/website/source/docs/commands/plan.html.md.erb index 10604ea4a..389905ec8 100644 --- a/website/source/docs/commands/plan.html.md.erb +++ b/website/source/docs/commands/plan.html.md.erb @@ -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] ``` 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 diff --git a/website/source/docs/commands/run.html.md.erb b/website/source/docs/commands/run.html.md.erb index 95a7be81b..5ba1a93de 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -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] +nomad run [options] ``` 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 diff --git a/website/source/docs/commands/server-force-leave.html.md.erb b/website/source/docs/commands/server-force-leave.html.md.erb index 5000923a4..fb46cd267 100644 --- a/website/source/docs/commands/server-force-leave.html.md.erb +++ b/website/source/docs/commands/server-force-leave.html.md.erb @@ -24,7 +24,7 @@ to enter the "left" state. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Examples diff --git a/website/source/docs/commands/server-join.html.md.erb b/website/source/docs/commands/server-join.html.md.erb index d0faf1aa3..03bf90c40 100644 --- a/website/source/docs/commands/server-join.html.md.erb +++ b/website/source/docs/commands/server-join.html.md.erb @@ -26,7 +26,7 @@ be 1. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Examples diff --git a/website/source/docs/commands/server-members.html.md.erb b/website/source/docs/commands/server-members.html.md.erb index d5fe869ab..04454b69a 100644 --- a/website/source/docs/commands/server-members.html.md.erb +++ b/website/source/docs/commands/server-members.html.md.erb @@ -23,7 +23,7 @@ nomad server-members [options] ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Server Members Options diff --git a/website/source/docs/commands/status.html.md.erb b/website/source/docs/commands/status.html.md.erb index f1c69235f..80e3e046d 100644 --- a/website/source/docs/commands/status.html.md.erb +++ b/website/source/docs/commands/status.html.md.erb @@ -26,7 +26,7 @@ the most useful status fields for each. ## General Options -<%= general_options_usage %> +<%= partial "docs/commands/_general_options" %> ## Status Options diff --git a/website/source/docs/commands/stop.html.md.erb b/website/source/docs/commands/stop.html.md.erb index 641cb636f..372993b7e 100644 --- a/website/source/docs/commands/stop.html.md.erb +++ b/website/source/docs/commands/stop.html.md.erb @@ -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 diff --git a/website/source/docs/commands/validate.html.md.erb b/website/source/docs/commands/validate.html.md.erb index 5bf5e8fb9..7383e8552 100644 --- a/website/source/docs/commands/validate.html.md.erb +++ b/website/source/docs/commands/validate.html.md.erb @@ -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 ``` 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. - diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md index 6acc04edb..bbcfd9327 100644 --- a/website/source/docs/drivers/docker.html.md +++ b/website/source/docs/drivers/docker.html.md @@ -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 diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 83eaf9289..d800ea0ab 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -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" { diff --git a/website/source/docs/drivers/index.html.md b/website/source/docs/drivers/index.html.md index 3de9ca7a6..36168452c 100644 --- a/website/source/docs/drivers/index.html.md +++ b/website/source/docs/drivers/index.html.md @@ -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. - diff --git a/website/source/docs/drivers/java.html.md b/website/source/docs/drivers/java.html.md index 91bbb4001..9451c3567 100644 --- a/website/source/docs/drivers/java.html.md +++ b/website/source/docs/drivers/java.html.md @@ -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 diff --git a/website/source/docs/drivers/qemu.html.md b/website/source/docs/drivers/qemu.html.md index 954ad9617..14490de06 100644 --- a/website/source/docs/drivers/qemu.html.md +++ b/website/source/docs/drivers/qemu.html.md @@ -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 { diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index fb930b06f..5be1ba7a3 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -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" { diff --git a/website/source/docs/drivers/rkt.html.md b/website/source/docs/drivers/rkt.html.md index 48630572f..b942a8e2f 100644 --- a/website/source/docs/drivers/rkt.html.md +++ b/website/source/docs/drivers/rkt.html.md @@ -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). diff --git a/website/source/docs/http/job.html.md b/website/source/docs/http/job.html.md index 763c50d6f..20345f671 100644 --- a/website/source/docs/http/job.html.md +++ b/website/source/docs/http/job.html.md @@ -307,9 +307,7 @@ region is used; another region can be specified using the `?region=` query param
  • Job required - 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.
    • @@ -378,9 +376,7 @@ region is used; another region can be specified using the `?region=` query param
  • Job required - 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.
  • Diff @@ -571,7 +567,7 @@ region is used; another region can be specified using the `?region=` query param
    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.
    diff --git a/website/source/docs/http/jobs.html.md b/website/source/docs/http/jobs.html.md index 607b5cebe..34f5125cc 100644 --- a/website/source/docs/http/jobs.html.md +++ b/website/source/docs/http/jobs.html.md @@ -85,7 +85,7 @@ another region can be specified using the `?region=` query parameter. Job required 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).
    • diff --git a/website/source/docs/jobspec/json.html.md b/website/source/docs/http/json-jobs.html.md similarity index 95% rename from website/source/docs/jobspec/json.html.md rename to website/source/docs/http/json-jobs.html.md index d15770cb7..f6551fd6a 100644 --- a/website/source/docs/jobspec/json.html.md +++ b/website/source/docs/http/json-jobs.html.md @@ -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 ` -which will emit a JSON version of the job. +for generating valid JSON versions of HCL jobs is +`nomad run -output ` 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 diff --git a/website/source/docs/job-specification/artifact.html.md b/website/source/docs/job-specification/artifact.html.md new file mode 100644 index 000000000..fbd335878 --- /dev/null +++ b/website/source/docs/job-specification/artifact.html.md @@ -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 + + + + + + +
    Placement + job -> group -> task -> **artifact** +
    + +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: 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 = "" + aws_access_key_secret = "" + aws_access_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" diff --git a/website/source/docs/job-specification/constraint.html.md b/website/source/docs/job-specification/constraint.html.md new file mode 100644 index 000000000..eb69343ba --- /dev/null +++ b/website/source/docs/job-specification/constraint.html.md @@ -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 + + + + + + +
    Placement + job -> **constraint** +
    + job -> group -> **constraint** +
    + job -> group -> task -> **constraint** +
    + +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" diff --git a/website/source/docs/job-specification/env.html.md b/website/source/docs/job-specification/env.html.md new file mode 100644 index 000000000..dad61d658 --- /dev/null +++ b/website/source/docs/job-specification/env.html.md @@ -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 + + + + + + +
    Placement + job -> group -> task -> **env** +
    + +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" diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md new file mode 100644 index 000000000..f45652c50 --- /dev/null +++ b/website/source/docs/job-specification/group.html.md @@ -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 + + + + + + +
    Placement + job -> **group** +
    + +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` ([Constraint][]: nil) - + 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` ([Meta][]: nil) - Specifies a key-value map that annotates + with user-defined metadata. + +- `restart` ([Restart][]: nil) - 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` ([Task][]: required) - 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" diff --git a/website/source/docs/job-specification/index.html.md b/website/source/docs/job-specification/index.html.md new file mode 100644 index 000000000..627df1004 --- /dev/null +++ b/website/source/docs/job-specification/index.html.md @@ -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" diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md new file mode 100644 index 000000000..e7659b79c --- /dev/null +++ b/website/source/docs/job-specification/job.html.md @@ -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` ([Constraint][constraint]: nil) - + 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: 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` ([Group][group]: required) - 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` ([Meta][]: nil) - Specifies a key-value map that annotates + with user-defined metadata. + +- `periodic` ([Periodic][]: nil) - 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` ([Update][update]: nil) - 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" diff --git a/website/source/docs/job-specification/logs.html.md b/website/source/docs/job-specification/logs.html.md new file mode 100644 index 000000000..d8e1d4a1e --- /dev/null +++ b/website/source/docs/job-specification/logs.html.md @@ -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 + + + + + + +
    Placement + job -> group -> task -> **logs** +
    + +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` + 3 `stdout` × 5MB = 30MB). + +```hcl +logs { + max_files = 3 + max_file_size = 5 +} +``` + +[logs-command]: /docs/commands/logs.html "nomad logs command" diff --git a/website/source/docs/job-specification/meta.html.md b/website/source/docs/job-specification/meta.html.md new file mode 100644 index 000000000..9cd9aaffc --- /dev/null +++ b/website/source/docs/job-specification/meta.html.md @@ -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 + + + + + + +
    Placement + job -> **meta** +
    + job -> group -> **meta** +
    + job -> group -> task -> **meta** +
    + +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" diff --git a/website/source/docs/job-specification/network.html.md b/website/source/docs/job-specification/network.html.md new file mode 100644 index 000000000..a0b71b643 --- /dev/null +++ b/website/source/docs/job-specification/network.html.md @@ -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 + + + + + + +
    Placement + job -> group -> task -> resources -> **network** +
    + +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` ([Port](#port-parameters): nil) - 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: + +- NOMAD_IP_foo - The IP to bind on for the given port label. +- NOMAD_PORT_foo - The port value for the given port label. +- NOMAD_ADDR_foo - A combined ip:port 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" diff --git a/website/source/docs/job-specification/periodic.html.md b/website/source/docs/job-specification/periodic.html.md new file mode 100644 index 000000000..665d7dc0d --- /dev/null +++ b/website/source/docs/job-specification/periodic.html.md @@ -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 + + + + + + +
    Placement + job -> **periodic** +
    + +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" diff --git a/website/source/docs/job-specification/resources.html.md b/website/source/docs/job-specification/resources.html.md new file mode 100644 index 000000000..37b90e1c6 --- /dev/null +++ b/website/source/docs/job-specification/resources.html.md @@ -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 + + + + + + +
    Placement + job -> group -> task -> **resources** +
    + +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` ([Network][]: required) - 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" diff --git a/website/source/docs/job-specification/restart.html.md b/website/source/docs/job-specification/restart.html.md new file mode 100644 index 000000000..09230cf73 --- /dev/null +++ b/website/source/docs/job-specification/restart.html.md @@ -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 + + + + + + +
    Placement + job -> group -> **restart** +
    + +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: )` - 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: )` - 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. diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md new file mode 100644 index 000000000..f241c31d4 --- /dev/null +++ b/website/source/docs/job-specification/task.html.md @@ -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` ([Artifact][]: nil) - Defines an artifact to download + before running the task. This may be specified multiple times to download + multiple artifacts. + +- `config` `(map: 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` ([Constraint][]: nil) - 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` ([Env][]: nil) - 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` ([Logs][]: nil) - Specifies logging configuration for the + `stdout` and `stderr` of the task. + +- `meta` ([Meta][]: nil) - Specifies a key-value map that annotates + with user-defined metadata. + +- `resources` ([Resources][]: required) - Specifies the minimum + resource requirements such as RAM, CPU, disk, and network. + +- `service` ([Service][]: nil) - 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: )` - 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" diff --git a/website/source/docs/job-specification/update.html.md b/website/source/docs/job-specification/update.html.md new file mode 100644 index 000000000..c42b30f7d --- /dev/null +++ b/website/source/docs/job-specification/update.html.md @@ -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 + + + + + + +
    Placement + job -> **update** +
    + +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" +} +``` diff --git a/website/source/docs/jobspec/index.html.md b/website/source/docs/jobspec/index.html.md deleted file mode 100644 index 20b9c5b4f..000000000 --- a/website/source/docs/jobspec/index.html.md +++ /dev/null @@ -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) - - - -* `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" - } - ``` - - - -* `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. - - * `prohibit_overlap` - 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. - - - -* `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 - } - ``` - - - -### 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. - - - -### 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). - - - -### 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 = "" - aws_access_key_secret = "" - aws_access_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. diff --git a/website/source/docs/jobspec/networking.html.md b/website/source/docs/jobspec/networking.html.md deleted file mode 100644 index 3d2dcf969..000000000 --- a/website/source/docs/jobspec/networking.html.md +++ /dev/null @@ -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 - -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. diff --git a/website/source/docs/operating-a-job/accessing-logs.html.md b/website/source/docs/operating-a-job/accessing-logs.html.md index 5d348db61..e0daf7520 100644 --- a/website/source/docs/operating-a-job/accessing-logs.html.md +++ b/website/source/docs/operating-a-job/accessing-logs.html.md @@ -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) diff --git a/website/source/docs/operating-a-job/configuring-tasks.html.md b/website/source/docs/operating-a-job/configuring-tasks.html.md index fc1e38375..7d6f69af9 100644 --- a/website/source/docs/operating-a-job/configuring-tasks.html.md +++ b/website/source/docs/operating-a-job/configuring-tasks.html.md @@ -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). diff --git a/website/source/docs/operating-a-job/index.html.md b/website/source/docs/operating-a-job/index.html.md index 3962a1645..5306fa84e 100644 --- a/website/source/docs/operating-a-job/index.html.md +++ b/website/source/docs/operating-a-job/index.html.md @@ -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 diff --git a/website/source/docs/operating-a-job/submitting-jobs.html.md b/website/source/docs/operating-a-job/submitting-jobs.html.md index c97c6ca7c..61b4ecae6 100644 --- a/website/source/docs/operating-a-job/submitting-jobs.html.md +++ b/website/source/docs/operating-a-job/submitting-jobs.html.md @@ -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" { diff --git a/website/source/docs/operating-a-job/update-strategies/blue-green-and-canary-deployments.html.md b/website/source/docs/operating-a-job/update-strategies/blue-green-and-canary-deployments.html.md index a8deb442d..0df8446f2 100644 --- a/website/source/docs/operating-a-job/update-strategies/blue-green-and-canary-deployments.html.md +++ b/website/source/docs/operating-a-job/update-strategies/blue-green-and-canary-deployments.html.md @@ -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. diff --git a/website/source/docs/operating-a-job/update-strategies/handling-signals.html.md b/website/source/docs/operating-a-job/update-strategies/handling-signals.html.md index eadcd743c..c2d6859b7 100644 --- a/website/source/docs/operating-a-job/update-strategies/handling-signals.html.md +++ b/website/source/docs/operating-a-job/update-strategies/handling-signals.html.md @@ -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). diff --git a/website/source/docs/operating-a-job/update-strategies/rolling-upgrades.html.md b/website/source/docs/operating-a-job/update-strategies/rolling-upgrades.html.md index afcdaa583..50a9be003 100644 --- a/website/source/docs/operating-a-job/update-strategies/rolling-upgrades.html.md +++ b/website/source/docs/operating-a-job/update-strategies/rolling-upgrades.html.md @@ -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). diff --git a/website/source/docs/jobspec/environment.html.md b/website/source/docs/runtime/environment.html.md similarity index 93% rename from website/source/docs/jobspec/environment.html.md rename to website/source/docs/runtime/environment.html.md index 864b5b42b..c9539112f 100644 --- a/website/source/docs/jobspec/environment.html.md +++ b/website/source/docs/runtime/environment.html.md @@ -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 +### 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" diff --git a/website/source/docs/runtime/index.html.md b/website/source/docs/runtime/index.html.md new file mode 100644 index 000000000..b7af10a21 --- /dev/null +++ b/website/source/docs/runtime/index.html.md @@ -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) diff --git a/website/source/docs/jobspec/interpreted.html.md b/website/source/docs/runtime/interpolation.html.md similarity index 87% rename from website/source/docs/jobspec/interpreted.html.md rename to website/source/docs/runtime/interpolation.html.md index b3f7c45e1..e8da3a22c 100644 --- a/website/source/docs/jobspec/interpreted.html.md +++ b/website/source/docs/runtime/interpolation.html.md @@ -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. ${NOMAD_ALLOC_DIR} - The path to the shared alloc/ directory. See [here](/docs/jobspec/environment.html#task_dir) for more information. + The path to the shared alloc/ directory. See [here](/docs/runtime/environment.html#task-directories) for more information. ${NOMAD_TASK_DIR} - The path to the task local/ directory. See [here](/docs/jobspec/environment.html#task_dir) for more information. + The path to the task local/ directory. See [here](/docs/runtime/environment.html#task-directories) for more information. ${NOMAD_MEMORY_LIMIT} @@ -231,21 +232,21 @@ a particular node and as such can not be used in constraints. ${NOMAD_IP_<label>} The IP for the given port label. See - [here](/docs/jobspec/networking.html) for more information. + [here](/docs/job-specification/network.html) for more information. ${NOMAD_PORT_<label>} - The port for the port label. See [here](/docs/jobspec/networking.html) for more information. + The port for the port label. See [here](/docs/job-specification/network.html) for more information. ${NOMAD_ADDR_<label>} The ip:port pair for the given port label. See - [here](/docs/jobspec/networking.html) for more information. + [here](/docs/job-specification/network.html) for more information. ${NOMAD_HOST_PORT_<label>} The port on the host if port forwarding is being used for the port - label. See [here](/docs/jobspec/networking.html#mapped_ports) for more + label. See [here](/docs/job-specification/network.html#mapped_ports) for more information. diff --git a/website/source/docs/jobspec/schedulers.html.md b/website/source/docs/runtime/schedulers.html.md similarity index 90% rename from website/source/docs/jobspec/schedulers.html.md rename to website/source/docs/runtime/schedulers.html.md index c57fd3cc1..07ad6a357 100644 --- a/website/source/docs/jobspec/schedulers.html.md +++ b/website/source/docs/runtime/schedulers.html.md @@ -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 diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/service-discovery/index.html.md similarity index 99% rename from website/source/docs/jobspec/servicediscovery.html.md rename to website/source/docs/service-discovery/index.html.md index a7278eebf..1ca61c831 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/service-discovery/index.html.md @@ -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 --- diff --git a/website/source/intro/getting-started/jobs.html.md b/website/source/intro/getting-started/jobs.html.md index 027fb45c9..738941468 100644 --- a/website/source/intro/getting-started/jobs.html.md +++ b/website/source/intro/getting-started/jobs.html.md @@ -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" diff --git a/website/source/layouts/_header.erb b/website/source/layouts/_header.erb index 746df5a89..e8e27e91f 100644 --- a/website/source/layouts/_header.erb +++ b/website/source/layouts/_header.erb @@ -6,7 +6,7 @@
    - by<%= partial "layouts/svg/svg-by-hashicorp" %><%= partial "layouts/svg/svg-hashicorp-logo" %>Hashicorp + by<%= partial "layouts/svg/svg-by-hashicorp" %><%= partial "layouts/svg/svg-hashicorp-logo" %>HashiCorp
    <% end %>