From 6627d28bff6ecc1c8638346ab91a057dc68c2e09 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Tue, 25 Jul 2017 10:13:28 -0700 Subject: [PATCH 1/2] Mention templates & env vars in configuring tasks --- .../source/docs/job-specification/env.html.md | 5 +- .../operating-a-job/configuring-tasks.html.md | 126 ++++++++++++++---- 2 files changed, 102 insertions(+), 29 deletions(-) diff --git a/website/source/docs/job-specification/env.html.md b/website/source/docs/job-specification/env.html.md index ddd8ae251..8079788a8 100644 --- a/website/source/docs/job-specification/env.html.md +++ b/website/source/docs/job-specification/env.html.md @@ -26,7 +26,7 @@ job "docs" { group "example" { task "server" { env { - my-key = "my-value" + my_key = "my-value" } } } @@ -37,7 +37,8 @@ job "docs" { The "parameters" for the `env` stanza can be any key-value. The keys and values are both of type `string`, but they can be specified as other types. They will -automatically be converted to strings. +automatically be converted to strings. Invalid characters such as dashes (`-`) +will be converted to underscores. ## `env` Examples diff --git a/website/source/docs/operating-a-job/configuring-tasks.html.md b/website/source/docs/operating-a-job/configuring-tasks.html.md index 3023385d9..dd60ca9d6 100644 --- a/website/source/docs/operating-a-job/configuring-tasks.html.md +++ b/website/source/docs/operating-a-job/configuring-tasks.html.md @@ -3,28 +3,28 @@ layout: "docs" page_title: "Configuring Tasks - Operating a Job" sidebar_current: "docs-operating-a-job-configuring-tasks" description: |- - Most applications require some kind of configuration. Whether this - configuration is provided via the command line or via a configuration file, - Nomad has built-in functionality for configuration. This section details two - common patterns for configuring tasks. + Most applications require some kind of configuration. Whether the + configuration is provided via the command line, environment variables, or a + configuration file, Nomad has built-in functionality for configuration. This + section details three common patterns for configuring tasks. --- # Configuring Tasks -Most applications require some kind of configuration. The simplest way is via -command-line arguments, but often times tasks consume complex configurations via -config files. This section explores how to configure Nomad jobs to support many -common configuration use cases. +Most applications require some kind of local configuration. While command line +arguments are the simplest method, many applications require more complex +configurations provided via environment variables or configuration files. This +section explores how to configure Nomad jobs to support many common +configuration use cases. ## Command-line Arguments -Many tasks accept configuration via command-line arguments that do not change -over time. +Many tasks accept configuration via command-line arguments. For example, +consider the [http-echo](https://github.com/hashicorp/http-echo) server which +is a small go binary that renders the provided text as a webpage. The binary +accepts two parameters: -For example, consider the [http-echo](https://github.com/hashicorp/http-echo) -server which is a small go binary that renders the provided text as a webpage. The binary accepts two parameters: - -* `-listen` - the address:port to listen on +* `-listen` - the `address:port` to listen on * `-text` - the text to render as the HTML page Outside of Nomad, the server is started like this: @@ -64,13 +64,15 @@ job "docs" { } ``` -~> **This assumes** the http-echo binary is already installed and available in the system path. Nomad can also optionally fetch the binary using the artifact resource. +~> **This assumes** the http-echo binary is already installed and + available in the system path. Nomad can also optionally fetch the binary + using the artifact resource. Nomad has many [drivers](/docs/drivers/index.html), and most support passing -arguments to their tasks via the `args` parameter. This option also optionally -accepts [Nomad interpolation](/docs/runtime/interpolation.html). For example, if -you wanted Nomad to dynamically allocate a high port to bind the service on -instead of relying on a static port for the previous job: +arguments to their tasks via the `args` parameter. This parameter also supports +[Nomad interpolation](/docs/runtime/interpolation.html). For example, if you +wanted Nomad to dynamically allocate a high port to bind the service on instead +of relying on a static port for the previous job: ```hcl job "docs" { @@ -99,15 +101,76 @@ job "docs" { } ``` +## Environment Variables + +Some applications can be configured via environment variables. [The +Twelve-Factor App](https://12factor.net/config) document suggests configuring +applications through environment variables. Nomad supports custom environment +variables in two ways: + +* Interpolation in an `env` stanza +* Templated in the a `template` stanza + +### `env` stanza + +Each task may have an `env` stanza which specifies environment variables: + +```hcl +task "server" { + env { + my_key = "my-value" + } +} +``` + +The `env` stanza also supports +[interpolation](/docs/runtime/interpolation.html): + +```hcl +task "server" { + env { + LISTEN_PORT = "${NOMAD_PORT_http}" + } +} +``` + +See the [`env`](/docs/job-specification/env.html.md) docs for details. + + +### Environment Templates + +Nomad's [`template`][template] stanza can be used +to generate environment variables. Environment variables may be templated with +the contents of files on disk, Consul keys, or secrets from Vault: + +```hcl +template { + data = < Date: Tue, 25 Jul 2017 16:53:10 -0700 Subject: [PATCH 2/2] Mention node attrs --- website/source/docs/job-specification/template.html.md | 1 + .../source/docs/operating-a-job/configuring-tasks.html.md | 7 +++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index 433b5afc8..ce2a52e87 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -119,6 +119,7 @@ template { --- bind_port: {{ env "NOMAD_PORT_db" }} scratch_dir: {{ env "NOMAD_TASK_DIR" }} + node_id: {{ env "node.unique.id" }} service_key: {{ key "service/my-key" }} EOH diff --git a/website/source/docs/operating-a-job/configuring-tasks.html.md b/website/source/docs/operating-a-job/configuring-tasks.html.md index dd60ca9d6..679cf53d3 100644 --- a/website/source/docs/operating-a-job/configuring-tasks.html.md +++ b/website/source/docs/operating-a-job/configuring-tasks.html.md @@ -141,7 +141,8 @@ See the [`env`](/docs/job-specification/env.html.md) docs for details. Nomad's [`template`][template] stanza can be used to generate environment variables. Environment variables may be templated with -the contents of files on disk, Consul keys, or secrets from Vault: +[Node attributes and metadata][nodevars], the contents of files on disk, Consul +keys, or secrets from Vault: ```hcl template { @@ -149,6 +150,7 @@ template { LOG_LEVEL="{{key "service/geo-api/log-verbosity"}}" API_KEY="{{with secret "secret/geo-api-key"}}{{.Data.key}}{{end}}" CERT={{ file "path/to/cert.pem" | to JSON }} +NODE_ID="{{ env "node.unique.id" }}" EOH destination = "secrets/config.env" @@ -204,5 +206,6 @@ job "docs" { For more information on the artifact resource, please see the [artifact documentation](/docs/job-specification/artifact.html). -[template]: /docs/job-specification/template.html "Nomad template Job Specification" [artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification" +[nodevars]: /docs/runtime/interpolation.html#interpreted_node_vars "Nomad Node Variables" +[template]: /docs/job-specification/template.html "Nomad template Job Specification"