From 5ced51383c1884d9777808fdb1a33bf5e232ac7f Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 20:35:41 -0400 Subject: [PATCH 01/10] Upgrade docs generator --- website/Gemfile | 2 +- website/Gemfile.lock | 8 ++++---- website/Makefile | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) 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..." From 0d3811ef8d9db9f41d112285c217bfa0632f8ada Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 20:35:49 -0400 Subject: [PATCH 02/10] Add helpers for generating titles and stuff --- website/config.rb | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) 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 From aefc1207ba83fbfdaeb2afd376c88658bd5c5cd5 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 20:36:00 -0400 Subject: [PATCH 03/10] Capital C --- website/source/layouts/_header.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 %> From 21073c1f0431b6f4d4bf55c2cb33f201ac40ec3d Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 20:46:20 -0400 Subject: [PATCH 06/10] Use a partial instead --- website/helpers/command_helpers.rb | 15 --------------- .../source/docs/commands/_general_options.html.md | 8 ++++++++ .../source/docs/commands/agent-info.html.md.erb | 2 +- .../source/docs/commands/alloc-status.html.md.erb | 2 +- .../docs/commands/client-config.html.md.erb | 2 +- .../source/docs/commands/eval-status.html.md.erb | 2 +- website/source/docs/commands/fs.html.md.erb | 2 +- .../commands/{init.html.md => init.html.md.erb} | 0 website/source/docs/commands/inspect.html.md.erb | 2 +- website/source/docs/commands/logs.html.md.erb | 2 +- .../source/docs/commands/node-drain.html.md.erb | 2 +- .../source/docs/commands/node-status.html.md.erb | 2 +- website/source/docs/commands/plan.html.md.erb | 2 +- website/source/docs/commands/run.html.md.erb | 2 +- .../docs/commands/server-force-leave.html.md.erb | 2 +- .../source/docs/commands/server-join.html.md.erb | 2 +- .../docs/commands/server-members.html.md.erb | 2 +- website/source/docs/commands/status.html.md.erb | 2 +- website/source/docs/commands/stop.html.md.erb | 2 +- 19 files changed, 24 insertions(+), 31 deletions(-) delete mode 100644 website/helpers/command_helpers.rb create mode 100644 website/source/docs/commands/_general_options.html.md rename website/source/docs/commands/{init.html.md => init.html.md.erb} (100%) 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/docs/commands/_general_options.html.md b/website/source/docs/commands/_general_options.html.md new file mode 100644 index 000000000..45c7fff88 --- /dev/null +++ b/website/source/docs/commands/_general_options.html.md @@ -0,0 +1,8 @@ +- `-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. 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 b/website/source/docs/commands/init.html.md.erb similarity index 100% rename from website/source/docs/commands/init.html.md rename to website/source/docs/commands/init.html.md.erb 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 aefb79aaf..c00fd94c9 100644 --- a/website/source/docs/commands/plan.html.md.erb +++ b/website/source/docs/commands/plan.html.md.erb @@ -53,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 789cbc4b4..a72cade59 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -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 From 30b79471807391a87c5a274448d9b0b7fa75a403 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 20:55:55 -0400 Subject: [PATCH 07/10] Fix broken links --- website/source/docs/drivers/rkt.html.md | 4 ++-- website/source/docs/http/jobs.html.md | 2 +- website/source/docs/job-specification/constraint.html.md | 2 +- website/source/docs/job-specification/logs.html.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/source/docs/drivers/rkt.html.md b/website/source/docs/drivers/rkt.html.md index bedea65e9..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: @@ -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/jobs.html.md b/website/source/docs/http/jobs.html.md index befbb1ec2..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/http/json.html). + by the [job specification](/docs/http/json-jobs.html). diff --git a/website/source/docs/job-specification/constraint.html.md b/website/source/docs/job-specification/constraint.html.md index c4b2f2042..12ee643eb 100644 --- a/website/source/docs/job-specification/constraint.html.md +++ b/website/source/docs/job-specification/constraint.html.md @@ -205,7 +205,7 @@ constraint { 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). +utilizing node [metadata][meta]. ```hcl constraint { diff --git a/website/source/docs/job-specification/logs.html.md b/website/source/docs/job-specification/logs.html.md index 695d6d8cf..cfd2de6f3 100644 --- a/website/source/docs/job-specification/logs.html.md +++ b/website/source/docs/job-specification/logs.html.md @@ -80,4 +80,4 @@ logs { } ``` -[logs-command]: "/docs/commands/logs.html" "nomad logs command" +[logs-command]: /docs/commands/logs.html "nomad logs command" From 9ec30a77b720844cf940bd9fe10eabeaba3ff5f1 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 20:59:45 -0400 Subject: [PATCH 08/10] Remove orphan list --- website/source/docs/job-specification/constraint.html.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/constraint.html.md b/website/source/docs/job-specification/constraint.html.md index 12ee643eb..d9d6b7116 100644 --- a/website/source/docs/job-specification/constraint.html.md +++ b/website/source/docs/job-specification/constraint.html.md @@ -156,7 +156,9 @@ constraint { ## `constraint` Examples -- Constrain to kernel data +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 From a9e79a16d61e3036828405971af043a27e437fc7 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 22:50:02 -0400 Subject: [PATCH 09/10] jobfile -> job file --- website/source/docs/commands/plan.html.md.erb | 4 ++-- website/source/docs/commands/run.html.md.erb | 6 +++--- website/source/docs/commands/validate.html.md.erb | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/website/source/docs/commands/plan.html.md.erb b/website/source/docs/commands/plan.html.md.erb index c00fd94c9..3470aac31 100644 --- a/website/source/docs/commands/plan.html.md.erb +++ b/website/source/docs/commands/plan.html.md.erb @@ -22,9 +22,9 @@ nomad plan [options] The plan command requires a single argument, specifying the path to a 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 +Nomad downloads the job file using [`go-getter`](https://github.com/hashicorp/go-getter) and supports `go-getter` syntax. diff --git a/website/source/docs/commands/run.html.md.erb b/website/source/docs/commands/run.html.md.erb index a72cade59..5ba1a93de 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -15,15 +15,15 @@ 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/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 diff --git a/website/source/docs/commands/validate.html.md.erb b/website/source/docs/commands/validate.html.md.erb index ec0ac6434..7383e8552 100644 --- a/website/source/docs/commands/validate.html.md.erb +++ b/website/source/docs/commands/validate.html.md.erb @@ -20,9 +20,9 @@ nomad validate The validate command requires a single argument, specifying the path to a 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 From eda4834f4a792f2edfb6a50fbc17142275f0e74c Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 27 Oct 2016 23:01:11 -0400 Subject: [PATCH 10/10] Address feedback --- .../docs/commands/_general_options.html.md | 20 ++++++++ website/source/docs/commands/plan.html.md.erb | 2 +- website/source/docs/drivers/index.html.md | 2 +- website/source/docs/http/json-jobs.html.md | 8 ++-- .../docs/job-specification/artifact.html.md | 4 +- .../docs/job-specification/constraint.html.md | 8 ++-- .../docs/job-specification/group.html.md | 25 +++++----- .../source/docs/job-specification/job.html.md | 6 +-- .../docs/job-specification/logs.html.md | 1 - .../docs/job-specification/network.html.md | 2 +- .../docs/job-specification/resources.html.md | 2 +- .../docs/job-specification/restart.html.md | 6 +-- .../docs/job-specification/task.html.md | 46 ++++++++++--------- 13 files changed, 78 insertions(+), 54 deletions(-) diff --git a/website/source/docs/commands/_general_options.html.md b/website/source/docs/commands/_general_options.html.md index 45c7fff88..a3d95dfb6 100644 --- a/website/source/docs/commands/_general_options.html.md +++ b/website/source/docs/commands/_general_options.html.md @@ -6,3 +6,23 @@ 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/plan.html.md.erb b/website/source/docs/commands/plan.html.md.erb index 3470aac31..389905ec8 100644 --- a/website/source/docs/commands/plan.html.md.erb +++ b/website/source/docs/commands/plan.html.md.erb @@ -21,7 +21,7 @@ nomad plan [options] The plan command requires a single argument, specifying the path to a 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 +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 job file using diff --git a/website/source/docs/drivers/index.html.md b/website/source/docs/drivers/index.html.md index 337788217..36168452c 100644 --- a/website/source/docs/drivers/index.html.md +++ b/website/source/docs/drivers/index.html.md @@ -15,7 +15,7 @@ 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/job-specification/index.html), the environments it -can be used in, and the resource isolation mechanisms available. +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 diff --git a/website/source/docs/http/json-jobs.html.md b/website/source/docs/http/json-jobs.html.md index a18f19d38..f6551fd6a 100644 --- a/website/source/docs/http/json-jobs.html.md +++ b/website/source/docs/http/json-jobs.html.md @@ -3,15 +3,15 @@ layout: "http" page_title: "HTTP API: JSON Job Specification" sidebar_current: "docs-http-json-jobs" description: |- - The job specification is also accepted via 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 diff --git a/website/source/docs/job-specification/artifact.html.md b/website/source/docs/job-specification/artifact.html.md index c7a226db4..fbd335878 100644 --- a/website/source/docs/job-specification/artifact.html.md +++ b/website/source/docs/job-specification/artifact.html.md @@ -46,12 +46,12 @@ before the starting the task. ## `artifact` Parameters -- `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. - - `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` diff --git a/website/source/docs/job-specification/constraint.html.md b/website/source/docs/job-specification/constraint.html.md index d9d6b7116..eb69343ba 100644 --- a/website/source/docs/job-specification/constraint.html.md +++ b/website/source/docs/job-specification/constraint.html.md @@ -3,9 +3,9 @@ layout: "docs" page_title: "constraint Stanza - Job Specification" sidebar_current: "docs-job-specification-constraint" description: |- - The "constraint" stanza specifies non-resource requirements. Constraints may - filter on attributes or metadata. Additionally constraints may be specified - at the job, group, or task levels for ultimate flexibility. + 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 @@ -23,7 +23,7 @@ description: |- -The `constraint` stanza specifies non-resource requirements. Constraints may +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. diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md index 900cd6f96..f45652c50 100644 --- a/website/source/docs/job-specification/group.html.md +++ b/website/source/docs/job-specification/group.html.md @@ -32,23 +32,23 @@ job "docs" { ## `group` Parameters -- `count` `(int: 1)` - Specifies the number of the task groups that should - be running under this group. This value must be non-negative. - - `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. + 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. -- `meta` ([Meta][]: nil) - Specifies a key-value map that annotates - with user-defined metadata. - ## `group` Examples The following examples only show the `group` stanzas. Remember that the `group` @@ -65,11 +65,10 @@ group "example" { } ``` -### Task with Constraint +### Tasks with Constraint -This example shows an abbreviated task with a constraint in the group. This will -restrict the task (and any other tasks in this group) to 64-bit operating -systems. +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" { @@ -78,6 +77,10 @@ group "example" { value = "amd64" } + task "cache" { + # ... + } + task "server" { # ... } diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index 7f2b83753..e7659b79c 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -72,6 +72,9 @@ job "docs" { - `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. @@ -84,9 +87,6 @@ job "docs" { - `update` ([Update][update]: nil) - Specifies the task's update strategy. When omitted, rolling updates are disabled. -- `periodic` ([Periodic][]: nil) - Allows the job to be scheduled - at fixed times, dates or intervals. - ## `job` Examples ### Docker Container diff --git a/website/source/docs/job-specification/logs.html.md b/website/source/docs/job-specification/logs.html.md index cfd2de6f3..d8e1d4a1e 100644 --- a/website/source/docs/job-specification/logs.html.md +++ b/website/source/docs/job-specification/logs.html.md @@ -51,7 +51,6 @@ For information on how to interact with logs after they have been configured, pl 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 diff --git a/website/source/docs/job-specification/network.html.md b/website/source/docs/job-specification/network.html.md index 5f9050582..a0b71b643 100644 --- a/website/source/docs/job-specification/network.html.md +++ b/website/source/docs/job-specification/network.html.md @@ -37,7 +37,7 @@ job "docs" { task "server" { resources { network { - mbits = 1000 + mbits = 200 port "http" {} port "https" {} port "lb" { diff --git a/website/source/docs/job-specification/resources.html.md b/website/source/docs/job-specification/resources.html.md index 6cd1dd790..37b90e1c6 100644 --- a/website/source/docs/job-specification/resources.html.md +++ b/website/source/docs/job-specification/resources.html.md @@ -50,7 +50,7 @@ job "docs" { - `disk` `(int: 200)` - Specifies the disk space required in MB. - `iops` `(int: 0)` - Specifies the number of IOPS required given as a weight - between 10-1000. + between 0-1000. - `memory` `(int: 300)` - Specifies the memory required in MB diff --git a/website/source/docs/job-specification/restart.html.md b/website/source/docs/job-specification/restart.html.md index e4fc6f314..09230cf73 100644 --- a/website/source/docs/job-specification/restart.html.md +++ b/website/source/docs/job-specification/restart.html.md @@ -46,9 +46,9 @@ job "docs" { 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). - +- `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 diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md index 138b46d73..f241c31d4 100644 --- a/website/source/docs/job-specification/task.html.md +++ b/website/source/docs/job-specification/task.html.md @@ -24,38 +24,26 @@ job "docs" { ## `task` Parameters -- `artifact` ([Artifact][]: nil) - Defines an artifact to download before running the task. This may be specified multiple times to download multiple artifacts. - -- `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` `(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. - -- `constraint` ([Constraint][]: nil) - Specifies user-defined - constraints on the task. This can be provided multiple times to define - additional constraints. +- `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. -- `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. +- `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. -- `resources` ([Resources][]: required) - Specifies the minimum - resource requirements such as RAM, CPU, disk, and network. - -- `meta` ([Meta][]: nil) - Specifies a key-value map that annotates - with user-defined metadata. - - `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 @@ -64,6 +52,20 @@ job "docs" { - `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