240 lines
6.7 KiB
Plaintext
240 lines
6.7 KiB
Plaintext
---
|
|
layout: "docs"
|
|
page_title: "Variable Interpolation"
|
|
sidebar_current: "docs-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. There 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 <a id="interpreted_node_vars"></a>
|
|
|
|
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 class="table table-bordered table-striped">
|
|
<tr>
|
|
<th>Variable</th>
|
|
<th>Description</th>
|
|
<th>Example Value</th>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${node.unique.id}</tt></td>
|
|
<td>36 character unique client identifier</td>
|
|
<td><tt>9afa5da1-8f39-25a2-48dc-ba31fd7c0023</tt></td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${node.datacenter}</tt></td>
|
|
<td>Client's datacenter</td>
|
|
<td><tt>dc1</tt></td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${node.unique.name}</tt></td>
|
|
<td>Client's name</td>
|
|
<td><tt>nomad-client-10-1-2-4</tt></td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${node.class}</tt></td>
|
|
<td>Client's class</td>
|
|
<td><tt>linux-64bit</tt></td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.<property>}</tt></td>
|
|
<td>Property given by <tt>property</tt> on the client</td>
|
|
<td><tt>${attr.cpu.arch} => amd64</tt></td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${meta.<key>}</tt></td>
|
|
<td>Metadata value given by <tt>key</tt> on the client</td>
|
|
<td><tt>${meta.foo} => bar</tt></td>
|
|
</tr>
|
|
</table>
|
|
|
|
Below is a table documenting common node properties:
|
|
|
|
<table class="table table-bordered table-striped">
|
|
<tr>
|
|
<th>Property</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.cpu.arch}</tt></td>
|
|
<td>CPU architecture of the client (e.g. <tt>amd64</tt>, <tt>386</tt>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.cpu.numcores}</tt></td>
|
|
<td>Number of CPU cores on the client</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.cpu.totalcompute}</tt></td>
|
|
<td>
|
|
<tt>cpu.frequency × cpu.numcores</tt> but may be overridden by <tt>client.cpu_total_compute</tt>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.consul.datacenter}</tt></td>
|
|
<td>The Consul datacenter of the client (if Consul is found)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.driver.<property>}</tt></td>
|
|
<td>See the [task drivers](/docs/drivers/index.html) for property documentation</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.unique.hostname}</tt></td>
|
|
<td>Hostname of the client</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.unique.network.ip-address}</tt></td>
|
|
<td>The IP address fingerprinted by the client and from which task ports are allocated</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.kernel.name}</tt></td>
|
|
<td>Kernel of the client (e.g. <tt>linux</tt>, <tt>darwin</tt>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.kernel.version}</tt></td>
|
|
<td>Version of the client kernel (e.g. <tt>3.19.0-25-generic</tt>, <tt>15.0.0</tt>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.platform.aws.ami-id}</tt></td>
|
|
<td>AMI ID of the client (if on AWS EC2)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.platform.aws.instance-type}</tt></td>
|
|
<td>Instance type of the client (if on AWS EC2)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.os.name}</tt></td>
|
|
<td>Operating system of the client (e.g. <tt>ubuntu</tt>, <tt>windows</tt>, <tt>darwin</tt>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><tt>${attr.os.version}</tt></td>
|
|
<td>Version of the client OS</td>
|
|
</tr>
|
|
</table>
|
|
|
|
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 <a id="interpreted_env_vars"></a>
|
|
|
|
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 <a id="dots_in_vars"></a>
|
|
|
|
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"]}"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
<%= partial "envvars.html.md" %>
|