»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:

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"
  }
}
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

Below is a full listing of node attributes that are interpretable. These attributes are interpreted by both constraints and within the task and driver.

VariableDescriptionExample Value
${node.unique.id}36 character unique client identifier9afa5da1-8f39-25a2-48dc-ba31fd7c0023
${node.region}Client's regionglobal
${node.datacenter}Client's datacenterdc1
${node.unique.name}Client's namenomad-client-10-1-2-4
${node.class}Client's classlinux-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:

PropertyDescription
${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.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:

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"
  }
}
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

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:

env {
  "valid.name"     = "ok"
  "invalid...name" = "not a valid identifier"
}
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:

task "redis" {
  driver = "docker"
  config {
    image  = "redis:3.2"
    labels {
      label1 = "${env["invalid...name"]}"
      label2 = "${env["valid.name"]}"
    }
  }
}
task "redis" {  driver = "docker"  config {    image  = "redis:3.2"    labels {      label1 = "${env["invalid...name"]}"      label2 = "${env["valid.name"]}"    }  }}
VariableDescription
NOMAD_ALLOC_DIRThe path to the shared alloc/ directory. Seehere for more information.
NOMAD_TASK_DIRThe path to the task local/ directory. Seehere for more information.
NOMAD_SECRETS_DIRPath to the task's secrets directory. Seehere for more information.
NOMAD_MEMORY_LIMITMemory limit in MB for the task
NOMAD_MEMORY_MAX_LIMITThe maximum memory limit the task may use if client has excess memory capacity, in MB. Omitted if task isn't configured with memory oversubscription.
NOMAD_CPU_LIMITCPU limit in MHz for the task
NOMAD_ALLOC_IDAllocation ID of the task
NOMAD_ALLOC_NAMEAllocation name of the task
NOMAD_ALLOC_INDEXAllocation 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_NAMETask's name
NOMAD_GROUP_NAMEGroup's name
NOMAD_JOB_IDJob's ID, which is equal to the Job name when submitted through CLI but can be different when using the API
NOMAD_JOB_NAMEJob's name
NOMAD_JOB_PARENT_IDID of the Job's parent if it has one
NOMAD_DCDatacenter in which the allocation is running
NOMAD_NAMESPACENamespace in which the allocation is running
NOMAD_REGIONRegion 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_TOKENThe 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 taskfor 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 127.0.0.2:Port for the admin port of the envoy sidecar for the given service when defined as a Consul Connect enabled service. Envoy runs inside the group network namespace unless configured for host networking.
NOMAD_ENVOY_READY_ADDR_<service>Local address 127.0.0.1:Port for the ready port of the envoy sidecar for the given service when defined as a Consul Connect enabled service. Envoy runs inside the group network namespace unless configured for host networking.
Consul-related Variables (only set for connect native tasks)
CONSUL_HTTP_ADDRSpecifies the address to the local Consul agent. Will be automatically set to a unix domain socket in bridge networking mode, or a tcp address in host networking mode.
CONSUL_HTTP_TOKENSpecifies the Consul ACL token used to authorize with Consul. Will be automatically set to a generated Connect service identity token specific to the service instance if Consul ACLs are enabled.
CONSUL_HTTP_SSLSpecifies whether HTTPS should be used when communicating with consul. Will be automatically set to true if Nomad is configured to communicate with Consul using TLS.
CONSUL_HTTP_SSL_VERIFYSpecifies whether the HTTPS connection with Consul should be mutually verified. Will be automatically set to true if Nomad is configured to verify TLS certificates.
CONSUL_CACERTSpecifies the path to the CA certificate used for Consul communication. Will be automatically set if Nomad is configured with the consul.share_ssloption.
CONSUL_CLIENT_CERTSpecifies the path to the Client certificate used for Consul communication. Will be automatically set if Nomad is configured with the consul.share_ssloption.
CONSUL_CLIENT_KEYSpecifies the path to the CLient Key certificate used for Consul communication. Will be automatically set if Nomad is configured with the consul.share_ssloption.
CONSUL_TLS_SERVER_NAMESpecifies the server name to use as the SNI host for Consul communication. Will be automatically set if Consul is configured to use TLS and the task is in a group using bridge networking mode.