37a078ebce
* Add information about templating using `env` function to refer to environment variables.
201 lines
10 KiB
Plaintext
201 lines
10 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Variable Interpolation
|
||
description: Learn about the Nomad's interpolation and interpreted variables.
|
||
---
|
||
|
||
# Variable Interpolation
|
||
|
||
Nomad supports interpreting two classes of variables: node attributes and
|
||
runtime environment variables. Node attributes are interpretable in constraints,
|
||
task environment variables, and certain driver fields. Runtime environment
|
||
variables are not interpretable in constraints because they are only defined
|
||
once the scheduler has placed them on a particular node.
|
||
|
||
Nomad supports interpreting two classes of variables: [node attributes](#interpreted_node_vars)
|
||
and [runtime environment variables](#interpreted_env_vars). Node attributes are
|
||
interpretable in [constraints](/nomad/docs/job-specification/constraint),
|
||
[task environment variables](/nomad/docs/job-specification/env), and certain
|
||
task driver fields—for example the [`labels`](/nomad/docs/drivers/docker#labels)
|
||
attribute of the Docker [`config`](/nomad/docs/drivers/docker).
|
||
|
||
<Note>
|
||
Runtime environment variables are not defined until after the scheduler
|
||
has placed the job, so they are unavailable for use in job constraints.
|
||
</Note>
|
||
|
||
## Syntax
|
||
|
||
The syntax for interpreting variables in the Nomad job specification is
|
||
`${variable_name}`. The [`template` block](/nomad/docs/job-specification/template)
|
||
uses the `env` function to retrieve these variables from the environment, using
|
||
`{{env "variable_name"}}` instead. Examples can be seen below:
|
||
|
||
```hcl
|
||
task "docs" {
|
||
driver = "docker"
|
||
|
||
# Drivers support interpreting node attributes and runtime environment
|
||
# variables
|
||
config {
|
||
image = "my-app"
|
||
|
||
# Interpret runtime variables to inject the address to bind to and the
|
||
# location to write logs to.
|
||
args = [
|
||
"--bind", "${NOMAD_ADDR_RPC}",
|
||
"--logs", "${NOMAD_ALLOC_DIR}/logs",
|
||
]
|
||
|
||
port_map {
|
||
RPC = 6379
|
||
}
|
||
}
|
||
|
||
# Constraints only support node attributes as runtime environment variables
|
||
# are only defined after the task is placed on a node.
|
||
constraint {
|
||
attribute = "${attr.kernel.name}"
|
||
value = "linux"
|
||
}
|
||
|
||
template {
|
||
destination = "template.txt"
|
||
data = <<EOT
|
||
{{- /*
|
||
Environment variables are available to templates via the env function,
|
||
rather than the ${...} syntax.
|
||
*/ -}}
|
||
Running on {{env "attr.unique.hostname"}}.
|
||
EOT
|
||
}
|
||
|
||
# Environment variables are interpreted and can contain both runtime and
|
||
# node attributes. These environment variables are passed into the task.
|
||
env {
|
||
DC = "Running on datacenter ${node.datacenter}"
|
||
VERSION = "Version ${NOMAD_META_VERSION}"
|
||
}
|
||
|
||
# Meta keys are also interpretable.
|
||
meta {
|
||
VERSION = "v0.3"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Node Attributes ((#interpreted_node_vars, #node-variables-))
|
||
|
||
Below is a full listing of node attributes that are interpretable. These
|
||
attributes are interpreted by **both** constraints and within the task and
|
||
driver.
|
||
|
||
| Variable | Description | Example Value |
|
||
| ----------------------| ------------------------------------------- | -------------------------------------- |
|
||
| `${node.unique.id}` | 36 character unique client identifier | `9afa5da1-8f39-25a2-48dc-ba31fd7c0023` |
|
||
| `${node.region}` | Client's region | `global` |
|
||
| `${node.datacenter}` | Client's datacenter | `dc1` |
|
||
| `${node.unique.name}` | Client's name | `nomad-client-10-1-2-4` |
|
||
| `${node.class}` | Client's class | `linux-64bit` |
|
||
| `${attr.<property>}` | Property given by `property` on the client | `${attr.cpu.arch} => amd64` |
|
||
| `${meta.<key>}` | Metadata value given by `key` on the client | `${meta.foo} => bar` |
|
||
|
||
Below is a table documenting common node properties.
|
||
|
||
| Property | Description |
|
||
| ---------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `${attr.cpu.arch}` | CPU architecture of the client (e.g. `amd64`, `386`) |
|
||
| `${attr.cpu.numcores}` | Number of CPU cores on the client. May differ from how many cores are available for reservation due to OS or configuration. See `cpu.reservablecores`. |
|
||
| `${attr.cpu.reservablecores}` | Number of CPU cores on the client available for scheduling. Number of cores used by the scheduler when placing work with `resources.cores` set. |
|
||
| `${attr.cpu.totalcompute}` | `cpu.frequency × cpu.numcores` but may be overridden by `client.cpu_total_compute` |
|
||
| `${attr.consul.datacenter}` | The Consul datacenter of the client (if Consul is found) |
|
||
| `${attr.driver.<property>}` | See the [task drivers](/nomad/docs/drivers) for property documentation |
|
||
| `${attr.unique.hostname}` | Hostname of the client |
|
||
| `${attr.unique.network.ip-address}` | The IP address fingerprinted by the client and from which task ports are allocated |
|
||
| `${attr.kernel.arch}` | Kernel architecture of the client (e.g. `x86_64`, `aarch64`) |
|
||
| `${attr.kernel.name}` | Kernel of the client (e.g. `linux`, `darwin`) |
|
||
| `${attr.kernel.version}` | Version of the client kernel (e.g. `3.19.0-25-generic`, `15.0.0`) |
|
||
| `${attr.platform.aws.ami-id}` | AMI ID of the client (if on AWS EC2) |
|
||
| `${attr.platform.aws.instance-life-cycle}` | Instance lifecycle (e.g. spot, on-demand) of the client (if on AWS EC2) |
|
||
| `${attr.platform.aws.instance-type}` | Instance type of the client (if on AWS EC2) |
|
||
| `${attr.platform.aws.placement.availability-zone}` | Availability Zone of the client (if on AWS EC2) |
|
||
| `${attr.os.name}` | Operating system of the client (e.g. `ubuntu`, `windows`, `darwin`) |
|
||
| `${attr.os.version}` | Version of the client OS |
|
||
|
||
The full list of node attributes can be obtained by running `nomad node status -verbose [node]`.
|
||
|
||
Here are some examples of using node attributes and properties in a job file:
|
||
|
||
```hcl
|
||
job "docs" {
|
||
# This will constrain this job to only run on 64-bit clients.
|
||
constraint {
|
||
attribute = "${attr.cpu.arch}"
|
||
value = "amd64"
|
||
}
|
||
|
||
# This will restrict the job to only run on clients with 4 or more cores.
|
||
# Note: you may also declare a resource requirement for CPU for a task.
|
||
constraint {
|
||
attribute = "${cpu.numcores}"
|
||
operator = ">="
|
||
value = "4"
|
||
}
|
||
|
||
# Only run this job on a memory-optimized AWS EC2 instance.
|
||
constraint {
|
||
attribute = "${attr.platform.aws.instance-type}"
|
||
value = "m4.xlarge"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Environment Variables ((#interpreted_env_vars))
|
||
|
||
The following are runtime environment variables that describe the environment
|
||
the task is running in. These are only defined once the task has been placed on
|
||
a particular node and as such can not be used in constraints.
|
||
|
||
Environment variables should be enclosed in brackets `${...}` for
|
||
interpolation or accessed using the `env` function inside the template
|
||
block—`{{env "..."}}`
|
||
|
||
### Dots in Variables ((#dots_in_vars))
|
||
|
||
Nomad interprets dots in names as object notation. This causes names that have
|
||
multiple consecutive dots to be considered invalid. For example, an environment
|
||
variable named `invalid...name` cannot be interpolated using the standard
|
||
`"${invalid...name}"` syntax. If you do, the parser will return an
|
||
`Extra characters after interpolation expression` error. Nomad provides a
|
||
variable—`env`—that can access any environment variable, regardless
|
||
of its name, using index syntax.
|
||
|
||
```hcl
|
||
job "sample" {
|
||
datacenters = ["dc1"]
|
||
group "g1" {
|
||
task "redis" {
|
||
|
||
# Note: to set an environment variable with an invalid name, you must
|
||
# use the HCL2 map assignment syntax for `env`. Otherwise, the job spec
|
||
# parser will throw an `Argument or block definition required` error
|
||
env = {
|
||
"invalid...name" = "value1"
|
||
"valid.name" = "value2"
|
||
}
|
||
|
||
driver = "docker"
|
||
config {
|
||
image = "redis:7"
|
||
labels {
|
||
label1 = "${env["invalid...name"]}"
|
||
label2 = "${valid.name}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
@include 'envvars.mdx'
|