Accessing Variables from tasks
In this tutorial you'll access Nomad Variables from tasks via the
template block. Tasks have implicit ACL policies that allow them to access
their own variables, and you can add job, group, and task fields to ACL policies
to extend these permissions.
Note
You should always protect access to variables with Access Control Lists (ACLs). Writing ACL policies for variables is covered in the Nomad Variables Access Control tutorial
For complete documentation on the Nomad Variables feature and related concepts, see the Variables reference documentation, the Key Management documentation, and the Workload Identity documentation
Automatic access
The workload identity for each task grants it automatic read and list access
to variables found at Nomad-owned paths with the prefix nomad/jobs/, followed
by the job ID, task group name, and task name.
If you've completed the Nomad Variables Access Control tutorial, you will have a "prod" namespace and a token associated with the "prod-ops" policy. If not, you can use a management token for this section and create the "prod" namespace.
$ nomad namespace apply -description "production environment" prodSuccessfully applied namespace "prod"!In this tutorial you'll be working in the "prod" namespace. Set the
NOMAD_NAMESPACE variable so that the command line writes all variables to that
namespace.
export NOMAD_NAMESPACE=prodCreate the following variables to see how different jobs, groups, and tasks can access them.
nomad var put nomad/jobs password=passw0rd1nomad var put nomad/jobs/example person_to_greet=alicenomad var put nomad/jobs/example/web foo=1 bar=2 baz=3nomad var put nomad/jobs/example/web/httpd port=8001nomad var put nomad/jobs/example/web/sidecar password=passw0rd2Create the following job specification. This job example has one group web
with two tasks, httpd and sidecar. It includes templates that access all the
variables you wrote earlier.
job "example" { datacenters = ["dc1"] group "web" { network { port "www" { to = 8001 } } task "httpd" { driver = "docker" config { image = "busybox:1" command = "httpd" args = ["-v", "-f", "-p", "0.0.0.0:${PORT}", "-h", "${NOMAD_ALLOC_DIR}/data"] ports = ["www"] } template { destination = "${NOMAD_SECRETS_DIR}/env.txt" env = true data = <<EOTPORT={{ with nomadVar "nomad/jobs/example/web/httpd" }}{{ .port }}{{ end }}EOT } template { destination = "${NOMAD_ALLOC_DIR}/data/index.html" change_mode = "noop" data = <<EOT<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Index</title></head> <body> <p>Hello, {{ with nomadVar "nomad/jobs/example" }}{{ .person_to_greet }}{{ end }}!</p> <p>Here is the group variable:</p> <ul> {{- with nomadVar "nomad/jobs/example/web" -}} {{- range $k, $v := . }} <li>{{ $k }}={{ $v }}</li> {{- end }} {{- end }} </ul> <p><a href="/sidecar.html">View the output from the sidecar task.</a></p> </body></html>EOT } } task "sidecar" { driver = "docker" config { image = "busybox:1" command = "sleep" args = ["300"] } template { destination = "${NOMAD_ALLOC_DIR}/data/sidecar.html" change_mode = "noop" data = <<EOT<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Sidecar</title></head> <body> <p>The task has access to the following variables:</p> <ul> {{- range nomadVarList "nomad" }} <li>{{ .Path }}</li> {{- end }} </ul> <p><a href="/">View the index page.</a></p> </body></html>EOT } } }}Run this job and wait for the deployment to complete and note the allocation
short ID. In this example, the allocation short ID is ec6dc2e4.
$ nomad job run ./example.nomad.hcl==> 2022-09-19T11:42:20-04:00: Monitoring evaluation "0d8a7587" 2022-09-19T11:42:20-04:00: Evaluation triggered by job "example" 2022-09-19T11:42:20-04:00: Evaluation within deployment: "b58da4d8" 2022-09-19T11:42:20-04:00: Allocation "ec6dc2e4" created: node "9063a25f", group "web" 2022-09-19T11:42:20-04:00: Evaluation status changed: "pending" -> "complete"==> 2022-09-19T11:42:20-04:00: Evaluation "0d8a7587" finished with status "complete"==> 2022-09-19T11:42:20-04:00: Monitoring deployment "b58da4d8" ✓ Deployment "b58da4d8" successful 2022-09-19T11:42:32-04:00 ID = b58da4d8 Job ID = example Job Version = 0 Status = successful Description = Deployment completed successfully Deployed Task Group Desired Placed Healthy Unhealthy Progress Deadline web 1 1 1 0 2022-09-19T15:52:31ZFirst, use nomad alloc exec to enter the httpd task and show the command
line arguments for the processes running in the container.
$ nomad alloc exec -task httpd ec6dc2e4 ps -efPID USER TIME COMMAND 1 root 0:00 httpd -v -f -p 0.0.0.0:8001 -h /alloc/data 8 root 0:00 ps -efNote that the port number has been interpolated with environment variable that
you rendered in the following template by using the env field:
template { destination = "${NOMAD_SECRETS_DIR}/env.txt" env = true data = <<EOTPORT={{ with nomadVar "nomad/jobs/example/web/httpd" }}{{ .port }}{{ end }}EOT }Visit the web page being served by the httpd task at port 8001. If you are
running Nomad on macOS and are using Docker for Mac to run Docker tasks, you can
reach the webpage at your localhost address.
If you are deploying to a remote Linux host or Vagrant box, you can use the IP
address found when you run nomad alloc status:
$ nomad alloc status ec6dc2e4...Allocation Addresses (mode = "bridge"):Label Dynamic Address*www yes 127.0.0.1:21976 -> 8001You can also use curl:
$ curl 127.0.0.1:21976<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Index</title></head> <body> <p>Hello, alice!</p> <p>Here is the group variable:</p> <ul> <li>bar=2</li> <li>baz=3</li> <li>foo=1</li> </ul> <p><a href="/sidecar.html">View the output from the sidecar task.</a></p> </body></html>This corresponds to this template block that reads the variable accessible to
the job "example" at nomad/jobs/example and the variable accessible to the
group "web" within the job "example" at nomad/jobs/example/web.
template { destination = "${NOMAD_ALLOC_DIR}/data/index.html" change_mode = "noop" data = <<EOT<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Index</title></head> <body> <p>Hello, {{ with nomadVar "nomad/jobs/example" }}{{ .person_to_greet }}{{ end }}!</p> <p>Here is the group variable:</p> <ul> {{- with nomadVar "nomad/jobs/example/web" -}} {{- range $k, $v := . }} <li>{{ $k }}={{ $v }}</li> {{- end }} {{- end }} </ul> <p><a href="/sidecar.html">View the output from the sidecar task.</a></p> </body></html>EOTVisit the webpage rendered by the sidecar task:
curl -s http://127.0.0.1:21976/sidecar.html<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Sidecar</title></head> <body> <p>The task has access to the following variables:</p> <ul> <li>nomad/jobs</li> <li>nomad/jobs/example</li> <li>nomad/jobs/example/web</li> <li>nomad/jobs/example/web/sidecar</li> </ul> <p><a href="/">View the index page.</a></p> </body></html>This corresponds to the following template block, which lists all the variables this task has access to in its own namespace:
template { destination = "${NOMAD_ALLOC_DIR}/data/sidecar.html" change_mode = "noop" data = <<EOT<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Sidecar</title></head> <body> <p>The task has access to the following variables:</p> <ul> {{- range nomadVarList "nomad" }} <li>{{ .Path }}</li> {{- end }} </ul> <p><a href="/">View the index page.</a></p> </body></html>EOT }Note that nomad/jobs/example/httpd does not appear in the list. If you added a
variable to nomad/jobs/another-example it would also not appear in the
list. If you added nomad/jobs/example/sidecar to a different namespace, it
would not appear in the list.
Workload associated ACL policies
You may need to give tasks access to variables that are on paths shared by many jobs. For example, all jobs in your cluster may need a shared API key for a third-party monitoring vendor. You can provide access to these variables secrets by creating policies associated with the task's workload identity. See Workload Associated ACL Policies for full documentation.
Create a new namespace named shared.
$ nomad namespace apply sharedSuccessfully applied namespace "shared"!Create a variable named vendor/foo/bar in the shared namespace.
nomad var put -namespace shared vendor/foo/bar user=me password=passw0rd1To give the task you wrote earlier access to all secrets in the shared
namespace, you can create the following policy file shared-policy.hcl.
namespace "shared" { variables { path "*" { capabilities = ["read"] } }}Now, create the policy and associate it with the httpd task in the web group
of the example job, specifying the appropriate flags on the nomad acl policy
apply command.
nomad acl policy apply \ -namespace prod -job example -group web -task httpd \ shared-policy ./shared-policy.hclYou can view the policy to see that it's associated with the workload.
$ nomad acl policy info shared-policyName = shared-policyDescription = <none>CreateIndex = 390ModifyIndex = 390 Associated WorkloadNamespace = prodJobID = exampleGroup = webTask = httpd Rules namespace "shared" { variables { path "*" { capabilities = ["read"] } }}Change the template for the httpd task.
template { destination = "alloc/index.html" data = <<EOT<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Index</title></head> <body> <p>Hello, {{ with nomadVar "nomad/jobs/example" }}{{ .person_to_greet }}{{ end }}!</p> <p>Here is the shared variable:</p> <ul> {{- with nomadVar "vendor/foo/bar@shared" }} {{- range $k, $v := . }} <li>{{ $k }}={{ $v }}</li> {{- end }} {{- end }} </ul> </body></html>EOTUpdate the job and wait for the deployment to complete.
nomad job run ./example.nomad.hclVisit the webpage served by the httpd task.
curl -s http://127.0.0.1:8001/index.html<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Index</title></head> <body> <p>Hello, alice!</p> <p>Here is the shared variable:</p> <ul> <li>password=passw0rd1</li> <li>user=me</li> </ul> </body></html>Updating task variables
You can update the value of a variable and it will be updated in the templates that read that value.
Update the shared variable so that the "password" field changes.
nomad var put -namespace shared -force vendor/foo/bar user=me password=passw0rd2After a few moments, the value will be updated on the template.
curl -s http://127.0.0.1:8001/index.html<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><title>Hello Variables - Index</title></head> <body> <p>Hello, alice!</p> <p>Here is the shared variable:</p> <ul> <li>password=passw0rd2</li> <li>user=me</li> </ul> </body></html>You can use the template
change_mode
to specify Nomad's behavior when a value changes.
Next steps
Because Nomad Variables use functions in the template block to emit data to Nomad jobs, consider learning more about templates in Nomad with the Templates collection.