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

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

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.

Variable Description
NOMAD_ALLOC_DIR The path to the shared alloc/ directory. See here for more information.
NOMAD_TASK_DIR The path to the task local/ directory. See here for more information.
NOMAD_SECRETS_DIR Path to the task's secrets directory. See here 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).
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_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. See Vault Integration for more details
Network-related Variables
NOMAD_IP_<label> Host IP for the given port label. See here 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. See here 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. See here 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 and task 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.