github.com/smintz/nomad@v0.8.3/website/source/guides/operating-a-job/configuring-tasks.html.md (about) 1 --- 2 layout: "guides" 3 page_title: "Configuring Tasks - Operating a Job" 4 sidebar_current: "guides-operating-a-job-configuring-tasks" 5 description: |- 6 Most applications require some kind of configuration. Whether the 7 configuration is provided via the command line, environment variables, or a 8 configuration file, Nomad has built-in functionality for configuration. This 9 section details three common patterns for configuring tasks. 10 --- 11 12 # Configuring Tasks 13 14 Most applications require some kind of local configuration. While command line 15 arguments are the simplest method, many applications require more complex 16 configurations provided via environment variables or configuration files. This 17 section explores how to configure Nomad jobs to support many common 18 configuration use cases. 19 20 ## Command-line Arguments 21 22 Many tasks accept configuration via command-line arguments. For example, 23 consider the [http-echo](https://github.com/hashicorp/http-echo) server which 24 is a small go binary that renders the provided text as a webpage. The binary 25 accepts two parameters: 26 27 * `-listen` - the `address:port` to listen on 28 * `-text` - the text to render as the HTML page 29 30 Outside of Nomad, the server is started like this: 31 32 ```shell 33 $ http-echo -listen=":5678" -text="hello world" 34 ``` 35 36 The Nomad equivalent job file might look something like this: 37 38 ```hcl 39 job "docs" { 40 datacenters = ["dc1"] 41 42 group "example" { 43 task "server" { 44 driver = "exec" 45 46 config { 47 command = "/bin/http-echo" 48 args = [ 49 "-listen", ":5678", 50 "-text", "hello world", 51 ] 52 } 53 54 resources { 55 network { 56 mbits = 10 57 port "http" { 58 static = "5678" 59 } 60 } 61 } 62 } 63 } 64 } 65 ``` 66 67 ~> **This assumes** the <tt>http-echo</tt> binary is already installed and 68 available in the system path. Nomad can also optionally fetch the binary 69 using the <tt>artifact</tt> resource. 70 71 Nomad has many [drivers](/docs/drivers/index.html), and most support passing 72 arguments to their tasks via the `args` parameter. This parameter also supports 73 [Nomad interpolation](/docs/runtime/interpolation.html). For example, if you 74 wanted Nomad to dynamically allocate a high port to bind the service on instead 75 of relying on a static port for the previous job: 76 77 ```hcl 78 job "docs" { 79 datacenters = ["dc1"] 80 81 group "example" { 82 task "server" { 83 driver = "exec" 84 85 config { 86 command = "/bin/http-echo" 87 args = [ 88 "-listen", ":${NOMAD_PORT_http}", 89 "-text", "hello world", 90 ] 91 } 92 93 resources { 94 network { 95 mbits = 10 96 port "http" {} 97 } 98 } 99 } 100 } 101 } 102 ``` 103 104 ## Environment Variables 105 106 Some applications can be configured via environment variables. [The 107 Twelve-Factor App](https://12factor.net/config) document suggests configuring 108 applications through environment variables. Nomad supports custom environment 109 variables in two ways: 110 111 * Interpolation in an `env` stanza 112 * Templated in the a `template` stanza 113 114 ### `env` stanza 115 116 Each task may have an `env` stanza which specifies environment variables: 117 118 ```hcl 119 task "server" { 120 env { 121 my_key = "my-value" 122 } 123 } 124 ``` 125 126 The `env` stanza also supports 127 [interpolation](/docs/runtime/interpolation.html): 128 129 ```hcl 130 task "server" { 131 env { 132 LISTEN_PORT = "${NOMAD_PORT_http}" 133 } 134 } 135 ``` 136 137 See the [`env`](/docs/job-specification/env.html) docs for details. 138 139 140 ### Environment Templates 141 142 Nomad's [`template`][template] stanza can be used 143 to generate environment variables. Environment variables may be templated with 144 [Node attributes and metadata][nodevars], the contents of files on disk, Consul 145 keys, or secrets from Vault: 146 147 ```hcl 148 template { 149 data = <<EOH 150 LOG_LEVEL="{{key "service/geo-api/log-verbosity"}}" 151 API_KEY="{{with secret "secret/geo-api-key"}}{{.Data.key}}{{end}}" 152 CERT={{ file "path/to/cert.pem" | to JSON }} 153 NODE_ID="{{ env "node.unique.id" }}" 154 EOH 155 156 destination = "secrets/config.env" 157 env = true 158 } 159 ``` 160 161 The template will be written to disk and then read as environment variables 162 before your task is launched. 163 164 ## Configuration Files 165 166 Sometimes applications accept their configurations using files to support 167 complex data structures. Nomad supports downloading 168 [artifacts][artifact] and 169 [templating][template] them prior to launching 170 tasks. 171 This allows shipping of configuration files and other assets that the task 172 needs to run properly. 173 174 Here is an example job which pulls down a configuration file as an artifact and 175 templates it: 176 177 ```hcl 178 job "docs" { 179 datacenters = ["dc1"] 180 181 group "example" { 182 task "server" { 183 driver = "exec" 184 185 artifact { 186 source = "http://example.com/config.hcl.tmpl" 187 destination = "local/config.hcl.tmpl" 188 } 189 190 template { 191 source = "local/config.hcl.tmpl" 192 destination = "local/config.hcl" 193 } 194 195 config { 196 command = "my-app" 197 args = [ 198 "-config", "local/config.hcl", 199 ] 200 } 201 } 202 } 203 } 204 ``` 205 206 For more information on the artifact resource, please see the [artifact 207 documentation](/docs/job-specification/artifact.html). 208 209 [artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification" 210 [nodevars]: /docs/runtime/interpolation.html#interpreted_node_vars "Nomad Node Variables" 211 [template]: /docs/job-specification/template.html "Nomad template Job Specification"