From c405291d396c000cfeefa7d6d3f7657586649f2d Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 20:36:27 -0400 Subject: [PATCH 01/31] Be consistent --- .../docs/job-specification/group.html.md | 10 ++-- .../source/docs/job-specification/job.html.md | 53 +++++++++++++++++-- .../docs/job-specification/logs.html.md | 2 +- .../docs/job-specification/task.html.md | 4 +- 4 files changed, 57 insertions(+), 12 deletions(-) diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md index f45652c50..a7e275ec2 100644 --- a/website/source/docs/job-specification/group.html.md +++ b/website/source/docs/job-specification/group.html.md @@ -99,8 +99,8 @@ group "example" { } ``` -[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" +[task]: /docs/job-specification/task.html "Nomad task Job Specification" +[job]: /docs/job-specification/job.html "Nomad job Job Specification" +[constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" +[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" +[restart]: /docs/job-specification/restart.html "Nomad restart Job Specification" diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index e7659b79c..f1b50e354 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -33,6 +33,10 @@ job "docs" { "my-key" = "my-value" } + periodic { + # ... + } + priority = 100 region = "north-america" @@ -45,9 +49,7 @@ job "docs" { # ... } - periodic { - # ... - } + vault_token = "a3594cbc-dee6-40cb-a9e9-59dd5abf8985" } ``` @@ -87,6 +89,11 @@ job "docs" { - `update` ([Update][update]: nil) - Specifies the task's update strategy. When omitted, rolling updates are disabled. +- `vault_token` `(string: "")` - Specifies the Vault token that proves the + submitter of the job has access to the specified policies in the + [`vault`][vault] stanza. This field is only used to transfer the token and is + not stored after Job submission. + ## `job` Examples ### Docker Container @@ -138,7 +145,44 @@ job "docs" { } resources { - cpu = 10 + cpu = 20 + } + } + } +} +``` + +### Secrets Job + +This example shows a job which retrieves secrets from Vault and writes those +secrets to a file on disk, which the application then consumes. Nomad handles +all interactions with Vault. + +```hcl +job "docs" { + datacenters = ["default"] + + vault_token = "a3594cbc-dee6-40cb-a9e9-59dd5abf8985" + + group "example" { + task "uptime" { + driver = "exec" + + config { + command = "cat local/secrets.txt" + } + + template { + data = "{{ secret \"secret/data\" }}" + destination = "local/secrets.txt" + } + + vault { + policies = ["secret-readonly"] + } + + resources { + cpu = 20 } } } @@ -151,5 +195,6 @@ job "docs" { [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" +[vault]: /docs/job-specification/vault.html "Nomad vault 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 index d8e1d4a1e..c138d077f 100644 --- a/website/source/docs/job-specification/logs.html.md +++ b/website/source/docs/job-specification/logs.html.md @@ -79,4 +79,4 @@ logs { } ``` -[logs-command]: /docs/commands/logs.html "nomad logs command" +[logs-command]: /docs/commands/logs.html "Nomad logs command" diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md index f241c31d4..330ab84d8 100644 --- a/website/source/docs/job-specification/task.html.md +++ b/website/source/docs/job-specification/task.html.md @@ -111,7 +111,7 @@ task "server" { } resources { - cpu = 10 + cpu = 20 } } ``` @@ -140,7 +140,7 @@ task "server" { } resources { - cpu = 10 + cpu = 20 } } ``` From d059531ab2768eeb28f933853f12e0e5e2baed14 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 20:41:03 -0400 Subject: [PATCH 02/31] Remove duplicate sentence --- website/source/docs/job-specification/artifact.html.md | 3 +-- website/source/docs/job-specification/constraint.html.md | 3 +-- website/source/docs/job-specification/env.html.md | 4 ++-- website/source/docs/job-specification/group.html.md | 4 ++-- website/source/docs/job-specification/job.html.md | 3 +++ website/source/docs/job-specification/logs.html.md | 3 +-- website/source/docs/job-specification/meta.html.md | 4 ++-- website/source/docs/job-specification/network.html.md | 3 +-- website/source/docs/job-specification/periodic.html.md | 3 +-- website/source/docs/job-specification/resources.html.md | 3 +-- website/source/docs/job-specification/task.html.md | 3 +++ website/source/docs/job-specification/update.html.md | 3 +-- 12 files changed, 19 insertions(+), 20 deletions(-) diff --git a/website/source/docs/job-specification/artifact.html.md b/website/source/docs/job-specification/artifact.html.md index cc83b9d59..f5bd3ffa0 100644 --- a/website/source/docs/job-specification/artifact.html.md +++ b/website/source/docs/job-specification/artifact.html.md @@ -61,8 +61,7 @@ before the starting the task. ## `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. +`artifact` stanza is only valid in the placements listed above. ### Download File diff --git a/website/source/docs/job-specification/constraint.html.md b/website/source/docs/job-specification/constraint.html.md index eb69343ba..eb7c87014 100644 --- a/website/source/docs/job-specification/constraint.html.md +++ b/website/source/docs/job-specification/constraint.html.md @@ -157,8 +157,7 @@ constraint { ## `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. +`constraint` stanza is only valid in the placements listed above. ### Kernel Data diff --git a/website/source/docs/job-specification/env.html.md b/website/source/docs/job-specification/env.html.md index dad61d658..ddd8ae251 100644 --- a/website/source/docs/job-specification/env.html.md +++ b/website/source/docs/job-specification/env.html.md @@ -41,8 +41,8 @@ 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. +The following examples only show the `env` stanzas. Remember that the +`env` stanza is only valid in the placements listed above. ### Coercion diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md index a7e275ec2..3ea89ad54 100644 --- a/website/source/docs/job-specification/group.html.md +++ b/website/source/docs/job-specification/group.html.md @@ -51,8 +51,8 @@ job "docs" { ## `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. +The following examples only show the `group` stanzas. Remember that the +`group` stanza is only valid in the placements listed above. ### Specifying Count diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index f1b50e354..6750657c5 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -96,6 +96,9 @@ job "docs" { ## `job` Examples +The following examples only show the `job` stanzas. Remember that the +`job` stanza is only valid in the placements listed above. + ### Docker Container This example job starts a Docker container which runs as a service. Even though diff --git a/website/source/docs/job-specification/logs.html.md b/website/source/docs/job-specification/logs.html.md index c138d077f..a429e28cd 100644 --- a/website/source/docs/job-specification/logs.html.md +++ b/website/source/docs/job-specification/logs.html.md @@ -54,8 +54,7 @@ For information on how to interact with logs after they have been configured, pl ## `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. +`logs` stanza is only valid in the placements listed above. ### Configure Defaults diff --git a/website/source/docs/job-specification/meta.html.md b/website/source/docs/job-specification/meta.html.md index 9cd9aaffc..e147d4083 100644 --- a/website/source/docs/job-specification/meta.html.md +++ b/website/source/docs/job-specification/meta.html.md @@ -56,8 +56,8 @@ 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. +The following examples only show the `meta` stanzas. Remember that the +`meta` stanza is only valid in the placements listed above. ### Coercion diff --git a/website/source/docs/job-specification/network.html.md b/website/source/docs/job-specification/network.html.md index a0b71b643..2f8acb0da 100644 --- a/website/source/docs/job-specification/network.html.md +++ b/website/source/docs/job-specification/network.html.md @@ -81,8 +81,7 @@ 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. +`network` stanza is only valid in the placements listed above. ### Bandwidth diff --git a/website/source/docs/job-specification/periodic.html.md b/website/source/docs/job-specification/periodic.html.md index 665d7dc0d..f7fb42a46 100644 --- a/website/source/docs/job-specification/periodic.html.md +++ b/website/source/docs/job-specification/periodic.html.md @@ -48,8 +48,7 @@ consistent evaluation when Nomad spans multiple time zones. ## `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. +`periodic` stanza is only valid in the placements listed above. ### Run Daily diff --git a/website/source/docs/job-specification/resources.html.md b/website/source/docs/job-specification/resources.html.md index 37b90e1c6..8f67663c9 100644 --- a/website/source/docs/job-specification/resources.html.md +++ b/website/source/docs/job-specification/resources.html.md @@ -60,8 +60,7 @@ job "docs" { ## `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. +`resources` stanza is only valid in the placements listed above. ### Disk Space diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md index 330ab84d8..45a78f66a 100644 --- a/website/source/docs/job-specification/task.html.md +++ b/website/source/docs/job-specification/task.html.md @@ -68,6 +68,9 @@ job "docs" { ## `task` Examples +The following examples only show the `task` stanzas. Remember that the +`task` stanza is only valid in the placements listed above. + ### Docker Container This example defines a task that starts a Docker container as a service. Docker diff --git a/website/source/docs/job-specification/update.html.md b/website/source/docs/job-specification/update.html.md index c42b30f7d..9da829b39 100644 --- a/website/source/docs/job-specification/update.html.md +++ b/website/source/docs/job-specification/update.html.md @@ -43,8 +43,7 @@ job "docs" { ## `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. +`update` stanza is only valid in the placements listed above. ### Serial Upgrades From cf000c2621d33549b3ca42b7e4c3b6023dca59c3 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:19:19 -0400 Subject: [PATCH 03/31] Add template example to init command --- command/init.go | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/command/init.go b/command/init.go index ea7977c55..b7cc06015 100644 --- a/command/init.go +++ b/command/init.go @@ -168,7 +168,7 @@ job "example" { } } - # The artifact block can be specified one or more times to download + # The artifact stanza can be specified one or more times to download # artifacts prior to the task being started. This is convenient for # shipping configs or data needed by the task. # artifact { @@ -178,6 +178,22 @@ job "example" { # } # } + # The "template" stanza instructs Nomad to manage a template, such as + # a configuration file or script. This template can optionally pull data + # from Consul or Vault to populate runtime configuration data. + # + # For more information and examples on the "template" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/template.html + # + # template { + # data = "---\nkey: {{ key \"service/my-key\" }}" + # destination = "local/file.yml" + # change_mode = "signal" + # change_signal = "SIGHUP" + # } + # Specify configuration related to log rotation # logs { # max_files = 10 From 7c441e6d3cfacb818a0bc21c02fa0546efd2829e Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:25:08 -0400 Subject: [PATCH 04/31] Add vault example to init command --- command/init.go | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/command/init.go b/command/init.go index b7cc06015..ab317f2a8 100644 --- a/command/init.go +++ b/command/init.go @@ -194,6 +194,24 @@ job "example" { # change_signal = "SIGHUP" # } + # The "vault" stnaza instructs the Nomad client to acquire a token from + # a HashiCorp Vault server. The Nomad servers must be configured and + # authorized to communicate with Vault. By default, Nomad will inject + # The token into the job via an environment variable and make the token + # available to the "template" stanza. The Nomad client handles the renewal + # and revocation of the Vault token. + # + # For more information and examples on the "vault" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/vault.html + # + # vault { + # policies = ["cdn", "frontend"] + # change_mode = "signal" + # change_signal = "SIGHUP" + # } + # Specify configuration related to log rotation # logs { # max_files = 10 From 2f050a535d0c52de780b2f27b6faf284b77c1864 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:27:25 -0400 Subject: [PATCH 05/31] Update artifact example in init command --- command/init.go | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/command/init.go b/command/init.go index ab317f2a8..775ad7f4f 100644 --- a/command/init.go +++ b/command/init.go @@ -168,9 +168,17 @@ job "example" { } } - # The artifact stanza can be specified one or more times to download - # artifacts prior to the task being started. This is convenient for - # shipping configs or data needed by the task. + # The "artifact" stanza instructs Nomad to download an artifact from a + # remote source prior to starting the task. This provides a convenient + # mechanism for downloading configuration files or data needed to run the + # task. It is possible to specify the "artifact" stanza multiple times to + # download multiple artifacts. + # + # For more information and examples on the "artifact" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/artifact.html + # # artifact { # source = "http://foo.com/artifact.tar.gz" # options { From 3e3ffcb9eca3417aa48335700d21343d3eead497 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:29:53 -0400 Subject: [PATCH 06/31] Update logs example in init --- command/init.go | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/command/init.go b/command/init.go index 775ad7f4f..ed10cbdfc 100644 --- a/command/init.go +++ b/command/init.go @@ -220,7 +220,16 @@ job "example" { # change_signal = "SIGHUP" # } - # Specify configuration related to log rotation + # The "logs" stana instructs the Nomad client on how many log files and + # the maximum size of those logs files to retain. Logging is enabled by + # default, but the "logs" stanza allows for finer-grained control over + # the log rotation and storage configuration. + # + # For more information and examples on the "logs" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/logs.html + # # logs { # max_files = 10 # max_file_size = 15 From 434db4de28433ef0dd69fb11aed95c039873a98e Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:30:13 -0400 Subject: [PATCH 07/31] Move logs configuration up in init command --- command/init.go | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/command/init.go b/command/init.go index ed10cbdfc..d4fe742d3 100644 --- a/command/init.go +++ b/command/init.go @@ -186,6 +186,21 @@ job "example" { # } # } + # The "logs" stana instructs the Nomad client on how many log files and + # the maximum size of those logs files to retain. Logging is enabled by + # default, but the "logs" stanza allows for finer-grained control over + # the log rotation and storage configuration. + # + # For more information and examples on the "logs" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/logs.html + # + # logs { + # max_files = 10 + # max_file_size = 15 + # } + # The "template" stanza instructs Nomad to manage a template, such as # a configuration file or script. This template can optionally pull data # from Consul or Vault to populate runtime configuration data. @@ -220,21 +235,6 @@ job "example" { # change_signal = "SIGHUP" # } - # The "logs" stana instructs the Nomad client on how many log files and - # the maximum size of those logs files to retain. Logging is enabled by - # default, but the "logs" stanza allows for finer-grained control over - # the log rotation and storage configuration. - # - # For more information and examples on the "logs" stanza, please see - # the online documentation at: - # - # https://www.nomadproject.io/docs/job-specification/logs.html - # - # logs { - # max_files = 10 - # max_file_size = 15 - # } - # Controls the timeout between signalling a task it will be killed # and killing the task. If not set a default is used. # kill_timeout = "20s" From aa8f1374504d892cbcb65ddf2c569a1a2ac18092 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:32:08 -0400 Subject: [PATCH 08/31] Update resources example in init command --- command/init.go | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/command/init.go b/command/init.go index d4fe742d3..383e53069 100644 --- a/command/init.go +++ b/command/init.go @@ -157,8 +157,16 @@ job "example" { } } - # We must specify the resources required for this task to ensure - # it runs on a machine with enough capacity. + # The "resources" stanza describes the requirements a task needs to + # execute. Resource requirements include memory, disk space, network, + # cpu, and more. This ensures the task will execute on a machine that + # contains enough resource capacity. + # + # For more information and examples on the "resources" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/resources.html + # resources { cpu = 500 # 500 MHz memory = 256 # 256MB From 082ba5a3c80a8e4120467556538d9359c17513f2 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Sun, 30 Oct 2016 21:33:10 -0400 Subject: [PATCH 09/31] Move resources alphabetical --- command/init.go | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/command/init.go b/command/init.go index 383e53069..07006b5fa 100644 --- a/command/init.go +++ b/command/init.go @@ -157,25 +157,6 @@ job "example" { } } - # The "resources" stanza describes the requirements a task needs to - # execute. Resource requirements include memory, disk space, network, - # cpu, and more. This ensures the task will execute on a machine that - # contains enough resource capacity. - # - # For more information and examples on the "resources" stanza, please see - # the online documentation at: - # - # https://www.nomadproject.io/docs/job-specification/resources.html - # - resources { - cpu = 500 # 500 MHz - memory = 256 # 256MB - network { - mbits = 10 - port "db" {} - } - } - # The "artifact" stanza instructs Nomad to download an artifact from a # remote source prior to starting the task. This provides a convenient # mechanism for downloading configuration files or data needed to run the @@ -209,6 +190,25 @@ job "example" { # max_file_size = 15 # } + # The "resources" stanza describes the requirements a task needs to + # execute. Resource requirements include memory, disk space, network, + # cpu, and more. This ensures the task will execute on a machine that + # contains enough resource capacity. + # + # For more information and examples on the "resources" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/resources.html + # + resources { + cpu = 500 # 500 MHz + memory = 256 # 256MB + network { + mbits = 10 + port "db" {} + } + } + # The "template" stanza instructs Nomad to manage a template, such as # a configuration file or script. This template can optionally pull data # from Consul or Vault to populate runtime configuration data. From 77416c85b9909c819fd69c0dcd6d3e1f07b2165e Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 00:00:35 -0400 Subject: [PATCH 10/31] Give service its own configuration --- .../docs/job-specification/service.html.md | 273 ++++++++++++++++++ .../docs/service-discovery/index.html.md | 128 +------- website/source/layouts/docs.erb | 3 + 3 files changed, 292 insertions(+), 112 deletions(-) create mode 100644 website/source/docs/job-specification/service.html.md diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md new file mode 100644 index 000000000..7a54b8e58 --- /dev/null +++ b/website/source/docs/job-specification/service.html.md @@ -0,0 +1,273 @@ +--- +layout: "docs" +page_title: "service Stanza - Job Specification" +sidebar_current: "docs-job-specification-service" +description: |- + TODO +--- + +# `service` Stanza + + + + + + +
Placement + job -> group -> task -> **service** +
+ +The `service` stanza instructs Nomad to register the task as a service in the +service discovery integration. This section of the documentation will discus the +configuration, but please also read the +[Nomad service discovery documentation][service-discovery] for more detailed +information about the integration. + +```hcl +job "docs" { + group "example" { + task "server" { + service { + tags = ["leader", "mysql"] + + check { + type = "tcp" + port = "db" + interval = "10s" + timeout = "2s" + } + + check { + type = "script" + name = "check_table" + command = "/usr/local/bin/check_mysql_table_status" + args = ["--verbose"] + interval = "60s" + timeout = "5s" + } + } + } + } +} +``` + +This section of the documentation only covers the job file options for +configuring service discovery. For more information on the setup and +configuration to integrate Nomad with service discovery, please see the +[Nomad service discovery documentation][service-discovery]. There are steps you +must take to configure Nomad. Simply adding this configuration to your job file +does not automatically enable service discovery. + +## `service` Parameters + +- `check` ([Check](#check-parameters): nil) - Specifies a health check associated with the service. This can be + specified multiple times to define multiple checks for the service. At this + time, Nomad supports the `script`1, `http` and `tcp` + checks. + +- `name` `(string: "--")` - Specifies the name of this + service. If not supplied, this will default to the name of the job, group, and + task concatenated together with a dash, like `"docs-example-server"`. Each + service must have a unique name within the cluster. Names must adhere to + [RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited + to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64 + characters in length. + + In addition to the standard [Nomad interpolation][interpolation], the + following keys are also available: + + - `${JOB}` - the name of the job + - `${GROUP}` - the name of the group + - `${TASK}` - the name of the task + - `${BASE}` - shorthand for `${JOB}-${GROUP}-${TASK}` + +- `port` `(string: required)` - Specifies the label of the port on which this + service is running. Note this is the _label_ of the port and not the port + number. The port label must match one defined in the [`network`][network] + stanza. + +- `tags` `(array: [])` - Specifies the list of tags to associate with + this service. If this is not supplied, no tags will be assigned to the service + when it is registered. + +### `check` Parameters + +- `args` `(array: [])` - Specifies additional arguments to the + `command`. This only applies to script-based health checks. + +- `command` `(string: )` - Specifies the command to run for performing + the health check. The script must exit: 0 for passing, 1 for warning, or any + other value for a failing health check. This is required for script-based + health checks. + + ~> **Caveat:** The command must be the path to the command on disk, and no + shell exists by default. That means operators like `||` or `&&` are not + available. Additionally, all arguments must be supplied via the `args` + parameter. The achieve the behavior of shell operators, specify the command + as a shell, like `/bin/bash` and then use `args` to run the check. + +- `initial_status` `(string: )` - Specifies the originating status of the + service. Valid options are the empty string, `passing`, `warning`, and + `critical`. + +- `interval` `(string: )` - Specifies the frequency of the health checks + that Consul will perform. This is specified using a label suffix like "30s" + or "1h". This must be greater than or equal to "1s" + +- `name` `(string: "service: check")` - Specifies the name of the health + check. + +- `path` `(string: )` - Specifies the path of the http endpoint which + Consul will query to query the health of a service. Nomad will automatically + add the IP of the service and the port, so this is just the relative URL to + the health check endpoint. This is required for http-based health checks. + +- `port` `(string: )` - Specifies the label of the port on which the + check will be performed. Note this is the _label_ of the port and not the port + number. The port label must match one defined in the [`network`][network] + stanza. If a port value was declared on the `service`, this will inherit from + that value if not supplied. If supplied, this value takes precedence over the + `service.port` value. This is useful for services which operate on multiple + ports. + +- `protocol` `(string: "http")` - Specifies the protocol for the http-based + health checks. Valid options are `http` and `https`. + +- `timeout` `(string: )` - Specifies how long Consul will wait for a + health check query to succeed. This is specified using a label suffix like + "30s" or "1h". This must be greater than or equal to "1s" + +- `type` `(string: )` - This indicates the check types supported by + Nomad. Valid options are `script`, `http`, and `tcp`. + + +## `service` Examples + +The following examples only show the `service` stanzas. Remember that the +`service` stanza is only valid in the placements listed above. + +### Basic Service + +This example registers a service named "load-balancer" with no health checks. + +```hcl +service { + name = "load-balancer" + port = "lb" +} +``` + +This example must be accompanied by a [`network`][network] stanza which defines +a static or dynamic port labeled "lb". For example: + +```hcl +resources { + network { + mbits = 10 + port "lb" {} + } +} +``` + +### Check with Bash-isms + +This example shows a common mistake and correct behavior for custom checks. +Suppose a health check like this: + +```shell +$ test -f /tmp/file.txt +``` + +In this example `test` is not actually a command (binary) on the system; it is a +built-in shell function to bash. Thus, the following **would not work**: + +```hcl +service { + check { + type = "script" + command = "test -f /tmp/file.txt" # THIS IS NOT CORRECT + } +} +``` + +Nomad will attempt to find an executable named `test` on your system, but it +does not exist. It is actually just a function of bash. Additionally, it is not +possible to specify the arguments in a single string. Here is the correct +solution: + +```hcl +service { + check { + type = "script" + command = "/bin/bash" + args = ["test", "-f", "/tmp/file.txt"] + } +} +``` + +The `command` is actually `/bin/bash`, since that is the actual process we are +running. The arguments to that command are the script itself, which each +argument provided as a value to the `args` array. + +### HTTP Health Check + +This example shows a service with an HTTP health check. This will query the +service on the IP and port registered with Nomad at `/_healthz` every 5 seconds, +giving the service a maximum of 2 seconds to return a response. Any non-2xx code +is considered a failure. + +```hcl +service { + check { + type = "http" + port = "lb" + path = "/_healthz" + interval = "5s" + timeout = "2s" + } +} +``` + +### Multiple Health Checks + +This example shows a service with multiple health checks defined. All health +checks must be passing in order for the service to register as healthy. + +```hcl +service { + check { + type = "http" + port = "lb" + path = "/_healthz" + interval = "5s" + timeout = "2s" + } + + check { + type = "https" + port = "lb" + path = "/_healthz" + interval = "5s" + timeout = "2s" + } + + check { + type = "script" + command = "/usr/local/bin/pg-tools" + args = ["verify", "database" "prod", "up"] + interval = "5s" + timeout = "2s" + } +} +``` + +- - - + +1 Script checks are not supported for the +[qemu driver][qemu] since the Nomad client does not have access to the file +system of a task for that driver. + +[service-discovery]: /docs/service-discovery/index.html "Nomad Service Discovery" +[interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation" +[network]: /docs/job-specification/network.html "Nomad network Job Specification" +[qemu]: /docs/drivers/qemu.html "Nomad qemu Driver" diff --git a/website/source/docs/service-discovery/index.html.md b/website/source/docs/service-discovery/index.html.md index 1ca61c831..ba6b652ca 100644 --- a/website/source/docs/service-discovery/index.html.md +++ b/website/source/docs/service-discovery/index.html.md @@ -11,8 +11,8 @@ description: |- Nomad schedules workloads of various types across a cluster of generic hosts. Because of this, placement is not known in advance and you will need to use service discovery to connect tasks to other services deployed across your -cluster. Nomad integrates with [Consul](https://www.consul.io) to provide -service discovery and monitoring. +cluster. Nomad integrates with [Consul][] to provide service discovery and +monitoring. Note that in order to use Consul with Nomad, you will need to configure and install Consul on your nodes alongside Nomad, or schedule it as a system job. @@ -20,128 +20,29 @@ Nomad does not currently run Consul for you. ## Configuration -To configure Consul integration please see the Agent's configuration -[here](/docs/agent/config.html#consul_options). +To enable Consul integration, please see the +[Nomad agent Consul integration](/docs/agent/config.html#consul_options) +configuration. + ## Service Definition Syntax -The service block in a task definition defines a service which Nomad will -register with Consul. Multiple service blocks are allowed in a task definition, -which allow registering multiple services for a task that exposes multiple -ports. - -### Example - -A brief example of a service definition in a task - -```hcl -group "database" { - task "mysql" { - driver = "docker" - - service { - tags = ["master", "mysql"] - - port = "db" - - check { - type = "tcp" - interval = "10s" - timeout = "2s" - } - - check { - type = "script" - name = "check_table" - command = "/usr/local/bin/check_mysql_table_status" - args = ["--verbose"] - interval = "60s" - timeout = "5s" - } - } - - resources { - cpu = 500 - memory = 1024 - - network { - mbits = 10 - port "db" {} - } - } - } -} -``` - -* `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, - `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task, - respectively. `${BASE}` expands to the equivalent of - `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service. - Each service defined for a given task must have a distinct name, so if - a task has multiple services only one of them can use the default name - and the others must be explicitly named. Names must adhere to - [RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are - limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be - less than 64 characters in length. - -* `tags`: A list of tags associated with this Service. String interpolation is - supported in tags. - -* `port`: `port` is optional and is used to associate a port with the service. - If specified, the port label must match one defined in the resources block. - This could be a label of either a dynamic or a static port. - -* `check`: A check block defines a health check associated with the service. - Multiple check blocks are allowed for a service. Nomad supports the `script`, - `http` and `tcp` Consul Checks. Script checks are not supported for the qemu - driver since the Nomad client doesn't have access to the file system of a - task using the Qemu driver. - -### Check Syntax - -* `type`: This indicates the check types supported by Nomad. Valid options are - currently `script`, `http` and `tcp`. - -* `name`: The name of the health check. - -* `interval`: This indicates the frequency of the health checks that Consul will - perform. - -* `timeout`: This indicates how long Consul will wait for a health check query - to succeed. - -* `path`: The path of the http endpoint which Consul will query to query the - health of a service if the type of the check is `http`. Nomad will add the IP - of the service and the port, users are only required to add the relative URL - of the health check endpoint. - -* `protocol`: This indicates the protocol for the http checks. Valid options - are `http` and `https`. We default it to `http`. - -* `port`: The label of the port on which the check will be performed. The label - specified here has to be defined in the resource block of the task. - -* `command`: This is the command that the Nomad client runs for doing script based - health check. - -* `args`: Additional arguments to the `command` for script based health checks. - -* `initial_status`: An optional parameter to set the initial status of the check - Valid options are the empty string, `passing`, `warning`, and `critical`. +To configure a job to register with service discovery, please see the +[`service` job specification documentation][service]. ## Assumptions -* Consul 0.6.4 or later is needed for using the Script checks. +- Consul 0.6.4 or later is needed for using the Script checks. -* Consul 0.6.0 or later is needed for using the TCP checks. +- Consul 0.6.0 or later is needed for using the TCP checks. -* The service discovery feature in Nomad depends on operators making sure that +- The service discovery feature in Nomad depends on operators making sure that the Nomad client can reach the Consul agent. -* Nomad assumes that it controls the life cycle of all the externally +- Nomad assumes that it controls the life cycle of all the externally discoverable services running on a host. -* Tasks running inside Nomad also need to reach out to the Consul agent if +- Tasks running inside Nomad also need to reach out to the Consul agent if they want to use any of the Consul APIs. Ex: A task running inside a docker container in the bridge mode won't be able to talk to a Consul Agent running on the loopback interface of the host since the container in the bridge mode @@ -149,3 +50,6 @@ group "database" { network namespace of the host. There are a couple of ways to solve this, one way is to run the container in the host networking mode, or make the Consul agent listen on an interface in the network namespace of the container. + +[consul]: https://www.consul.io/ "Consul by HashiCorp" +[service]: /docs/job-specification/service.html "Nomad service Job Specification" diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index d0dd836ae..a18dac5da 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -75,6 +75,9 @@ > restart + > + service + > task From 8dadd1659b13cc34abd1ef8986d47f8c7c638399 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 00:02:43 -0400 Subject: [PATCH 11/31] Update service example in init command --- command/init.go | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/command/init.go b/command/init.go index 07006b5fa..5fad41cff 100644 --- a/command/init.go +++ b/command/init.go @@ -144,9 +144,18 @@ job "example" { } } + # The "service" stanza instructs Nomad to register this task as a service + # in the service discovery engine, which is currently Consul. This will + # make the service addressable after Nomad has placed it on a host and + # port. + # + # For more information and examples on the "service" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/service.html + # service { - # ${TASKGROUP} is filled in automatically by Nomad - name = "${TASKGROUP}-redis" + name = "global-redis-check" tags = ["global", "cache"] port = "db" check { From f318dc2ba9beedb338147231b9219a38dded4262 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 00:03:03 -0400 Subject: [PATCH 12/31] Alphabetize services --- command/init.go | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/command/init.go b/command/init.go index 5fad41cff..358fda8e9 100644 --- a/command/init.go +++ b/command/init.go @@ -144,28 +144,6 @@ job "example" { } } - # The "service" stanza instructs Nomad to register this task as a service - # in the service discovery engine, which is currently Consul. This will - # make the service addressable after Nomad has placed it on a host and - # port. - # - # For more information and examples on the "service" stanza, please see - # the online documentation at: - # - # https://www.nomadproject.io/docs/job-specification/service.html - # - service { - name = "global-redis-check" - tags = ["global", "cache"] - port = "db" - check { - name = "alive" - type = "tcp" - interval = "10s" - timeout = "2s" - } - } - # The "artifact" stanza instructs Nomad to download an artifact from a # remote source prior to starting the task. This provides a convenient # mechanism for downloading configuration files or data needed to run the @@ -218,6 +196,28 @@ job "example" { } } + # The "service" stanza instructs Nomad to register this task as a service + # in the service discovery engine, which is currently Consul. This will + # make the service addressable after Nomad has placed it on a host and + # port. + # + # For more information and examples on the "service" stanza, please see + # the online documentation at: + # + # https://www.nomadproject.io/docs/job-specification/service.html + # + service { + name = "global-redis-check" + tags = ["global", "cache"] + port = "db" + check { + name = "alive" + type = "tcp" + interval = "10s" + timeout = "2s" + } + } + # The "template" stanza instructs Nomad to manage a template, such as # a configuration file or script. This template can optionally pull data # from Consul or Vault to populate runtime configuration data. From c6603cddee9710c7cbec59fc15ba9fde316ed30d Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 00:05:05 -0400 Subject: [PATCH 13/31] Add template example --- .../docs/job-specification/template.html.md | 108 ++++++++++++++++++ website/source/layouts/docs.erb | 3 + 2 files changed, 111 insertions(+) create mode 100644 website/source/docs/job-specification/template.html.md diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md new file mode 100644 index 000000000..cddc42214 --- /dev/null +++ b/website/source/docs/job-specification/template.html.md @@ -0,0 +1,108 @@ +--- +layout: "docs" +page_title: "template Stanza - Job Specification" +sidebar_current: "docs-job-specification-template" +description: |- + The "template" block instantiates an instance of a template renderer. This + creates a convenient way to ship configuration files that are populated from + Consul data, Vault secrets, or just general configurations within a Nomad + task. +--- + +# `template` Stanza + + + + + + +
Placement + job -> group -> task -> **template** +
+ +The `template` block instantiates an instance of a template renderer. This +creates a convenient way to ship configuration files that are populated from +Consul data, Vault secrets, or just general configurations within a Nomad task. + +```hcl +job "docs" { + group "example" { + task "server" { + template { + source = "local/redis.conf.tpl" + destination = "local/redis.conf" + change_mode = "signal" + change_signal = "SIGNINT" + } + } + } +} +``` + +Nomad is utilizes a tool called [Consul Template][ct]. For a full list of the +API template functions, please see the [Consul Template README][ct]. + +## `template` Parameters + +- `source` `(string: "")` - Specifies the path to the template to be rendered. + One of `source` or `data` must be specified, but not both. This source can + optionally be fetched using an [`artifact`][artifact] resource. + +- `destination` `(string: required)` - Specifies the location where the resulting template should be rendered, relative to the task directory. + +- `data` `(string: "")` - Specifies the raw template to execute. One of `source` + or `data` must be specified, but not both. This is useful for smaller + templates, but we recommend using `source` for larger templates. + +- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take if the Vault token changes. The possible values are: + + - `"noop"` - take no action (continue running the task) + - `"restart"` - restart the task as per the task's [restart policy][restart] + - `"signal"` - send a configurable signal to the task + +- `change_signal` `(string: "")` - Specifies the signal to send to the task as a + string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the + `change_mode` is `signal`. + +- `splay` `(string: "5s")` - Specifies a random amount of time to wait between + 0ms and the given splay value before invoking the change mode. This is + specified using a label suffix like "30s" or "1h", and is often used to + prevent a thundering herd problem where all task instances restart at the same + time. + +## `template` Examples + +The following examples only show the `template` stanzas. Remember that the +`template` stanza is only valid in the placements listed above. + +### Inline Template + +This example uses an inline template to render a controlled file to disk. This +file watches various keys in Consul for changes: + +```hcl +template { + data = "---\nkey: {{ key \"service/my-key\" }}" + destination = "local/file.yml" +} +``` + +### Remote Template + +This example uses an [`artifact`][artifact] stanza to download an input template +before passing it to the template engine: + +```hcl +artifact { + source = "https://example.com/file.yml.tpl" + destination = "local/file.yml.tpl" +} + +template { + source = "local/file.yml.tpl" + destination = "local/file.yml" +} +``` + +[ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp" +[artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification" diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a18dac5da..390b0b852 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -81,6 +81,9 @@ > task + > + template + > update From 59fea443acfc398ef0eb191b8c57c745d1ae2125 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 00:05:08 -0400 Subject: [PATCH 14/31] Add vault example --- .../docs/job-specification/vault.html.md | 95 +++++++++++++++++++ website/source/layouts/docs.erb | 3 + 2 files changed, 98 insertions(+) create mode 100644 website/source/docs/job-specification/vault.html.md diff --git a/website/source/docs/job-specification/vault.html.md b/website/source/docs/job-specification/vault.html.md new file mode 100644 index 000000000..2ee29c0a8 --- /dev/null +++ b/website/source/docs/job-specification/vault.html.md @@ -0,0 +1,95 @@ +--- +layout: "docs" +page_title: "vault Stanza - Job Specification" +sidebar_current: "docs-job-specification-vault" +description: |- + The "vault" stanza allows the task to specify that it requires a token from a + HashiCorp Vault server. Nomad will automatically retrieve a Vault token for + the task and handle token renewal for the task. +--- + +# `vault` Stanza + + + + + + +
Placement + job -> group -> task -> **vault** +
+ +The `vault` stanza allows the task to specify that it requires a token from a +[HashiCorp Vault][vault] server. Nomad will automatically retrieve a +Vault token for the task and handle token renewal for the task. + +```hcl +job "docs" { + group "example" { + task "server" { + vault { + policies = ["cdn", "frontend"] + + change_mode = "signal" + change_signal = "SIGUSR1" + } + } + } +} +``` + +If a `vault` stanza is specified, the [`template`][template] stanza can interact +with Vault as well. + +## `vault` Parameters + +- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take if the Vault token changes. The possible values are: + + - `"noop"` - take no action (continue running the task) + - `"restart"` - restart the task as per the task's [restart policy][restart] + - `"signal"` - send a configurable signal to the task + +- `change_signal` `(string: "")` - Specifies the signal to send to the task as a + string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the + `change_mode` is `signal`. + +- `env` `(bool: true)` - Specifies if the `VAULT_TOKEN` environment variable + should be set when starting the task. + +- `policies` `(array: [])` - Specifies the set of Vault policies that + the task requires. The Nomad client will generate a a Vault token that is + limited to those policies. + +## `vault` Examples + +The following examples only show the `vault` stanzas. Remember that the +`vault` stanza is only valid in the placements listed above. + +### Retrieve Token + +This example tells the Nomad client to retrieve a Vault token. The token is +available to the task via the canonical environment variable `VAULT_TOKEN`. The +resulting token will have the "frontend" Vault policy attached. + +```hcl +vault { + policies = ["frontend"] +} +``` + +### Signal Task + +This example shows signaling the task instead of restarting it. + +```hcl +vault { + policies = ["frontend"] + + change_mode = "signal" + change_signal = "SIGINT" +} +``` + +[restart]: /docs/job-specification/restart.html "Nomad restart Job Specification" +[template]: /docs/job-specification/template.html "Nomad template Job Specification" +[vault]: https://www.vaultproject.io/ "Vault by HashiCorp" diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 390b0b852..4a90493b5 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -87,6 +87,9 @@ > update + > + vault + From 613d1d685bb3abedd1bcfa74618d65b7ca43d1ca Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 00:05:16 -0400 Subject: [PATCH 15/31] Add service SEO description --- website/source/docs/job-specification/service.html.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 7a54b8e58..792235438 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -3,7 +3,8 @@ layout: "docs" page_title: "service Stanza - Job Specification" sidebar_current: "docs-job-specification-service" description: |- - TODO + The "service" stanza instructs Nomad to register the task as a service in the + service discovery integration. --- # `service` Stanza From 358aa6a26002128254ec22f5b57bda5a5fe75f3d Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 08:45:55 -0400 Subject: [PATCH 16/31] Fix typo --- command/init.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/command/init.go b/command/init.go index 358fda8e9..8883ca0f8 100644 --- a/command/init.go +++ b/command/init.go @@ -234,7 +234,7 @@ job "example" { # change_signal = "SIGHUP" # } - # The "vault" stnaza instructs the Nomad client to acquire a token from + # The "vault" stanza instructs the Nomad client to acquire a token from # a HashiCorp Vault server. The Nomad servers must be configured and # authorized to communicate with Vault. By default, Nomad will inject # The token into the job via an environment variable and make the token From 693baf2525160d35896131b5c29f8a64b2a95a2e Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 10:43:29 -0400 Subject: [PATCH 17/31] Fix job example --- website/source/docs/job-specification/job.html.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index 6750657c5..8c3972140 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -172,7 +172,8 @@ job "docs" { driver = "exec" config { - command = "cat local/secrets.txt" + command = "cat" + args = ["local/secrets.txt"] } template { From e3be0e6509506d01d1d2d04d7b44afb091562ecc Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:39:06 -0400 Subject: [PATCH 18/31] Clarify templates must pre-exist and cannot come from the container --- website/source/docs/job-specification/template.html.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index cddc42214..4163f72a8 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -46,7 +46,9 @@ API template functions, please see the [Consul Template README][ct]. - `source` `(string: "")` - Specifies the path to the template to be rendered. One of `source` or `data` must be specified, but not both. This source can - optionally be fetched using an [`artifact`][artifact] resource. + optionally be fetched using an [`artifact`][artifact] resource. This template + must exist on the machine prior to starting the task; it is not possible to + reference a template inside of a Docker container, for example. - `destination` `(string: required)` - Specifies the location where the resulting template should be rendered, relative to the task directory. From 3edbf620629cbaf8320fbd7def1b59db7614f129 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:43:25 -0400 Subject: [PATCH 19/31] Discourage setting vault_token directly in job file --- website/source/docs/job-specification/job.html.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index 8c3972140..9be86de90 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -48,8 +48,6 @@ job "docs" { update { # ... } - - vault_token = "a3594cbc-dee6-40cb-a9e9-59dd5abf8985" } ``` @@ -92,7 +90,12 @@ job "docs" { - `vault_token` `(string: "")` - Specifies the Vault token that proves the submitter of the job has access to the specified policies in the [`vault`][vault] stanza. This field is only used to transfer the token and is - not stored after Job submission. + not stored after job submission. + + !> It is **strongly discouraged** to place the token as a configuration + parameter like this, since the token could be checked into source control + accidentally. Users should set the `VAULT_TOKEN` environment variable when + running the job instead. ## `job` Examples From 9022998cf71588fd18f3ad08c39140907e9307f1 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:43:53 -0400 Subject: [PATCH 20/31] Consuming Secrets --- website/source/docs/job-specification/job.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index 9be86de90..4f2843880 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -158,7 +158,7 @@ job "docs" { } ``` -### Secrets Job +### Consuming Secrets This example shows a job which retrieves secrets from Vault and writes those secrets to a file on disk, which the application then consumes. Nomad handles From 356e19c530d2df8235fd6cc1a5103742135d6bcb Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:44:54 -0400 Subject: [PATCH 21/31] Remove hard vault_token and change task name --- website/source/docs/job-specification/job.html.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index 4f2843880..3ee3b65d8 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -168,10 +168,8 @@ all interactions with Vault. job "docs" { datacenters = ["default"] - vault_token = "a3594cbc-dee6-40cb-a9e9-59dd5abf8985" - group "example" { - task "uptime" { + task "cat" { driver = "exec" config { @@ -196,6 +194,12 @@ job "docs" { } ``` +When submitting this job, you would run: + +``` +$ VAULT_TOKEN="..." nomad run example.nomad +``` + [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" From abda6cc8cff04b69d28238a630fea0231658d74c Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:46:08 -0400 Subject: [PATCH 22/31] Update service description --- website/source/docs/job-specification/service.html.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 792235438..7b64ef00e 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -3,8 +3,8 @@ layout: "docs" page_title: "service Stanza - Job Specification" sidebar_current: "docs-job-specification-service" description: |- - The "service" stanza instructs Nomad to register the task as a service in the - service discovery integration. + The "service" stanza instructs Nomad to register the task as a service using + the service discovery integration. --- # `service` Stanza @@ -18,7 +18,7 @@ description: |- -The `service` stanza instructs Nomad to register the task as a service in the +The `service` stanza instructs Nomad to register the task as a service using the service discovery integration. This section of the documentation will discus the configuration, but please also read the [Nomad service discovery documentation][service-discovery] for more detailed From 907572c37aed42d1faea7684dde36d8a015f57cc Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:46:53 -0400 Subject: [PATCH 23/31] To discus and discuss we will begin discussion --- website/source/docs/job-specification/service.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 7b64ef00e..89b4b633a 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -19,7 +19,7 @@ description: |- The `service` stanza instructs Nomad to register the task as a service using the -service discovery integration. This section of the documentation will discus the +service discovery integration. This section of the documentation will discuss the configuration, but please also read the [Nomad service discovery documentation][service-discovery] for more detailed information about the integration. From 348d5ec92c14e8319f1acff256b42d503121172d Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:47:08 -0400 Subject: [PATCH 24/31] Add port to service --- website/source/docs/job-specification/service.html.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 89b4b633a..8d60a2b5d 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -31,6 +31,8 @@ job "docs" { service { tags = ["leader", "mysql"] + port = "db" + check { type = "tcp" port = "db" From 12c8f3e9f3a6faa24ddc82f4b9991dfe37141159 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:47:57 -0400 Subject: [PATCH 25/31] Wrap line --- website/source/docs/job-specification/service.html.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 8d60a2b5d..e64b554e5 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -63,10 +63,10 @@ does not automatically enable service discovery. ## `service` Parameters -- `check` ([Check](#check-parameters): nil) - Specifies a health check associated with the service. This can be - specified multiple times to define multiple checks for the service. At this - time, Nomad supports the `script`1, `http` and `tcp` - checks. +- `check` ([Check](#check-parameters): nil) - Specifies a health + check associated with the service. This can be specified multiple times to + define multiple checks for the service. At this time, Nomad supports the + `script`1, `http` and `tcp` checks. - `name` `(string: "--")` - Specifies the name of this service. If not supplied, this will default to the name of the job, group, and From 7cf2ab7f58434b825b288ed0364b986337b17f18 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:48:04 -0400 Subject: [PATCH 26/31] Capital HTTP --- website/source/docs/job-specification/service.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index e64b554e5..9aa29fbf2 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -120,7 +120,7 @@ does not automatically enable service discovery. - `name` `(string: "service: check")` - Specifies the name of the health check. -- `path` `(string: )` - Specifies the path of the http endpoint which +- `path` `(string: )` - Specifies the path of the HTTP endpoint which Consul will query to query the health of a service. Nomad will automatically add the IP of the service and the port, so this is just the relative URL to the health check endpoint. This is required for http-based health checks. From 375211d4c9caa42fb6be71945db4f18217c75b8f Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:49:08 -0400 Subject: [PATCH 27/31] Fix example --- website/source/docs/job-specification/service.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 9aa29fbf2..ce94cc1da 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -203,7 +203,7 @@ service { check { type = "script" command = "/bin/bash" - args = ["test", "-f", "/tmp/file.txt"] + args = ["-c", "test -f /tmp/file.txt"] } } ``` From 26526d8ce77fe132512bf9df4168815348a22f30 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:50:03 -0400 Subject: [PATCH 28/31] Fix multiline --- website/source/docs/job-specification/template.html.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index 4163f72a8..c16a4b47c 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -50,13 +50,15 @@ API template functions, please see the [Consul Template README][ct]. must exist on the machine prior to starting the task; it is not possible to reference a template inside of a Docker container, for example. -- `destination` `(string: required)` - Specifies the location where the resulting template should be rendered, relative to the task directory. +- `destination` `(string: required)` - Specifies the location where the + resulting template should be rendered, relative to the task directory. - `data` `(string: "")` - Specifies the raw template to execute. One of `source` or `data` must be specified, but not both. This is useful for smaller templates, but we recommend using `source` for larger templates. -- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take if the Vault token changes. The possible values are: +- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take + if the Vault token changes. The possible values are: - `"noop"` - take no action (continue running the task) - `"restart"` - restart the task as per the task's [restart policy][restart] From 291c247183493da57abb0b1f1754774b4c83dbcb Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:51:06 -0400 Subject: [PATCH 29/31] Add multiline string template example --- .../docs/job-specification/template.html.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index c16a4b47c..b60cf8f63 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -81,8 +81,8 @@ The following examples only show the `template` stanzas. Remember that the ### Inline Template -This example uses an inline template to render a controlled file to disk. This -file watches various keys in Consul for changes: +This example uses an inline template to render a file to disk. This file watches +various keys in Consul for changes: ```hcl template { @@ -91,6 +91,19 @@ template { } ``` +It is also possible to use heredocs for multi-line templates, like: + +```hcl +template { + data = < Date: Mon, 31 Oct 2016 16:52:28 -0400 Subject: [PATCH 30/31] Fix long lines --- website/source/docs/job-specification/vault.html.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/source/docs/job-specification/vault.html.md b/website/source/docs/job-specification/vault.html.md index 2ee29c0a8..3c1e509e3 100644 --- a/website/source/docs/job-specification/vault.html.md +++ b/website/source/docs/job-specification/vault.html.md @@ -43,7 +43,8 @@ with Vault as well. ## `vault` Parameters -- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take if the Vault token changes. The possible values are: +- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take + if the Vault token changes. The possible values are: - `"noop"` - take no action (continue running the task) - `"restart"` - restart the task as per the task's [restart policy][restart] From c13a9de21348ab272b8493d693f1b3ac887bb506 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 31 Oct 2016 16:52:41 -0400 Subject: [PATCH 31/31] Specify restart policy is not the same as restart behavior --- website/source/docs/job-specification/template.html.md | 2 +- website/source/docs/job-specification/vault.html.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index b60cf8f63..2b936be42 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -61,7 +61,7 @@ API template functions, please see the [Consul Template README][ct]. if the Vault token changes. The possible values are: - `"noop"` - take no action (continue running the task) - - `"restart"` - restart the task as per the task's [restart policy][restart] + - `"restart"` - restart the task - `"signal"` - send a configurable signal to the task - `change_signal` `(string: "")` - Specifies the signal to send to the task as a diff --git a/website/source/docs/job-specification/vault.html.md b/website/source/docs/job-specification/vault.html.md index 3c1e509e3..da7ff246f 100644 --- a/website/source/docs/job-specification/vault.html.md +++ b/website/source/docs/job-specification/vault.html.md @@ -47,7 +47,7 @@ with Vault as well. if the Vault token changes. The possible values are: - `"noop"` - take no action (continue running the task) - - `"restart"` - restart the task as per the task's [restart policy][restart] + - `"restart"` - restart the task - `"signal"` - send a configurable signal to the task - `change_signal` `(string: "")` - Specifies the signal to send to the task as a