342 lines
8.1 KiB
Plaintext
342 lines
8.1 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Variable Interpolation
|
|
sidebar_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.
|
|
|
|
The syntax for interpreting variables is `${variable}`. An example and a
|
|
comprehensive list of interpretable fields 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"
|
|
}
|
|
|
|
# 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 Variables ((#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.
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Variable</th>
|
|
<th>Description</th>
|
|
<th>Example Value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<code>{'${node.unique.id}'}</code>
|
|
</td>
|
|
<td>36 character unique client identifier</td>
|
|
<td>
|
|
<code>9afa5da1-8f39-25a2-48dc-ba31fd7c0023</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${node.region}'}</code>
|
|
</td>
|
|
<td>Client's region</td>
|
|
<td>
|
|
<code>global</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${node.datacenter}'}</code>
|
|
</td>
|
|
<td>Client's datacenter</td>
|
|
<td>
|
|
<code>dc1</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${node.unique.name}'}</code>
|
|
</td>
|
|
<td>Client's name</td>
|
|
<td>
|
|
<code>nomad-client-10-1-2-4</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${node.class}'}</code>
|
|
</td>
|
|
<td>Client's class</td>
|
|
<td>
|
|
<code>linux-64bit</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>
|
|
${'{'}attr.<property>{'}'}
|
|
</code>
|
|
</td>
|
|
<td>
|
|
Property given by <code>property</code> on the client
|
|
</td>
|
|
<td>
|
|
<code>{'${attr.cpu.arch} => amd64'}</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>
|
|
${'{'}meta.<key>{'}'}
|
|
</code>
|
|
</td>
|
|
<td>
|
|
Metadata value given by <code>key</code> on the client
|
|
</td>
|
|
<td>
|
|
<code>{'${meta.foo} => bar'}</code>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
Below is a table documenting common node properties:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Property</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.cpu.arch}'}</code>
|
|
</td>
|
|
<td>
|
|
CPU architecture of the client (e.g. <code>amd64</code>,{' '}
|
|
<code>386</code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.cpu.numcores}'}</code>
|
|
</td>
|
|
<td>Number of CPU cores on the client</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.cpu.totalcompute}'}</code>
|
|
</td>
|
|
<td>
|
|
<code>cpu.frequency × cpu.numcores</code> but may be overridden by{' '}
|
|
<code>client.cpu_total_compute</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.consul.datacenter}'}</code>
|
|
</td>
|
|
<td>The Consul datacenter of the client (if Consul is found)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>
|
|
${'{'}attr.driver.<property>{'}'}
|
|
</code>
|
|
</td>
|
|
<td>
|
|
See the <a href="/docs/drivers">task drivers</a> for property
|
|
documentation
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.unique.hostname}'}</code>
|
|
</td>
|
|
<td>Hostname of the client</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.unique.network.ip-address}'}</code>
|
|
</td>
|
|
<td>
|
|
The IP address fingerprinted by the client and from which task ports are
|
|
allocated
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.kernel.name}'}</code>
|
|
</td>
|
|
<td>
|
|
Kernel of the client (e.g. <code>linux</code>, <code>darwin</code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.kernel.version}'}</code>
|
|
</td>
|
|
<td>
|
|
Version of the client kernel (e.g. <code>3.19.0-25-generic</code>,{' '}
|
|
<code>15.0.0</code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.platform.aws.ami-id}'}</code>
|
|
</td>
|
|
<td>AMI ID of the client (if on AWS EC2)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.platform.aws.instance-type}'}</code>
|
|
</td>
|
|
<td>Instance type of the client (if on AWS EC2)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.platform.aws.placement.availability-zone}'}</code>
|
|
</td>
|
|
<td>Availability Zone of the client (if on AWS EC2)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.os.name}'}</code>
|
|
</td>
|
|
<td>
|
|
Operating system of the client (e.g. <code>ubuntu</code>,{' '}
|
|
<code>windows</code>, <code>darwin</code>)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>{'${attr.os.version}'}</code>
|
|
</td>
|
|
<td>Version of the client OS</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
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.
|
|
|
|
### Dots in Variables ((#dots_in_vars))
|
|
|
|
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:
|
|
|
|
```hcl
|
|
env {
|
|
"valid.name" = "ok"
|
|
"invalid...name" = "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:
|
|
|
|
```hcl
|
|
task "redis" {
|
|
driver = "docker"
|
|
config {
|
|
image = "redis:3.2"
|
|
labels {
|
|
label1 = "${env["invalid...name"]}"
|
|
label2 = "${env["valid.name"]}"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
@include 'envvars.mdx'
|