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.
The syntax for interpreting variables is ${variable}
. An example and a
comprehensive list of interpretable fields can be seen below:
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 |
${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 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.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-type} | Instance type 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 |
Here are some examples of using node attributes and properties in a job file:
Environment Variables
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.
Dots in Variables
Starting in Nomad 0.9, task configuration interpolation requires variables to be valid identifiers. While this does not affect default variables or common custom variables, it is possible to define a variable that is not a valid identifier:
The environment variable invalid...name
cannot be interpolated using the
standard "${invalid...name}"
syntax. The dots will be interpreted as object
notation so multiple consecutive dots are invalid.
To continue supporting all user environment variables Nomad 0.9 added a new
env
variable which allows accessing any environment variable through index
syntax:
Variable | Description |
---|---|
NOMAD_ALLOC_DIR | The path to the shared alloc/ directory. Seehere for more information. |
NOMAD_TASK_DIR | The path to the task local/ directory. Seehere for more information. |
NOMAD_SECRETS_DIR | Path to the task's secrets directory. Seehere for more information. |
NOMAD_MEMORY_LIMIT | Memory limit in MB for the task |
NOMAD_CPU_LIMIT | CPU limit in MHz for the task |
NOMAD_ALLOC_ID | Allocation ID of the task |
NOMAD_ALLOC_NAME | Allocation name of the task |
NOMAD_ALLOC_INDEX | Allocation index; useful to distinguish instances of task groups. From 0 to (count - 1). The index is unique within a given version of a job, but canaries or failed tasks in a deployment may reuse the index. |
NOMAD_TASK_NAME | Task's name |
NOMAD_GROUP_NAME | Group's name |
NOMAD_JOB_NAME | Job's name |
NOMAD_DC | Datacenter in which the allocation is running |
NOMAD_NAMESPACE | Namespace in which the allocation is running |
NOMAD_REGION | Region in which the allocation is running |
NOMAD_META_<key> | The metadata value given by key on the task's metadata. Note that this is different from${meta.<key>} which are keys in the node's metadata. |
VAULT_TOKEN | The task's Vault token. SeeVault Integrationfor more details |
Network-related Variables | |
NOMAD_IP_<label> | Host IP for the given port label . Seehere for more information. |
NOMAD_PORT_<label> | Port for the given port label . Driver-specified port when a port map is used, otherwise the host's static or dynamic port allocation. Services should bind to this port. Seehere for more information. |
NOMAD_ADDR_<label> | Host IP:Port pair for the given port label . |
NOMAD_HOST_PORT_<label> | Port on the host for the port label . Seehere for more information. |
NOMAD_IP_<task>_<label> | Host IP for the given port label and task for tasks in the same task group. |
NOMAD_PORT_<task>_<label> | Port for the given port label and task for tasks in the same task group. Driver-specified port when a port map is used, otherwise the host's static or dynamic port allocation. Services should bind to this port. |
NOMAD_ADDR_<task>_<label> | Host IP:Port pair for the given port label andtask for tasks in the same task group. |
NOMAD_HOST_PORT_<task>_<label> | Port on the host for the port label and task for tasks in the same task group. |
NOMAD_UPSTREAM_IP_<service> | IP for the given service when defined as a Consul Connectupstream. |
NOMAD_UPSTREAM_PORT_<service> | Port for the given service when defined as a Consul Connectupstream. |
NOMAD_UPSTREAM_ADDR_<service> | Host IP:Port for the given service when defined as a Consul Connectupstream. |
NOMAD_ENVOY_ADMIN_ADDR_<service> | Local address localhost:Port for the admin port of the envoy sidecar for the given service when defined as a Consul Connect enabled service. |