• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Nomad
  • Install
  • Intro
  • Tutorials
  • Documentation
  • API
  • Tools
  • Plugins
  • Sign up
Nomad Home

Documentation

Skip to main content
  • Documentation


  • Schedulers
    • Overview
    • Runtime Environment
    • Variable Interpolation

  • Nomad Ecosystem
  • Nomad Partnerships
  • Who Uses Nomad
  • FAQ

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Nomad
  3. Documentation
  4. Runtime
  5. Variable Interpolation
  • Nomad
  • v1.3.x
  • v1.2.x
  • v1.1.x
  • v1.0.x
  • v0.12.x
  • v0.11.x

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

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. May differ from how many cores are available for reservation due to OS or configuration. See cpu.reservablecores.
${attr.cpu.reservablecores}Number of CPU cores on the client avaible for scheduling. Number of cores used by the scheduler when placing work with resources.cores set.
${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.arch}Kernel architecture of the client (e.g. x86_64, aarch64)
${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-life-cycle}Instance lifecycle (e.g. spot, on-demand) 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"
  }
}

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

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:7"
    labels {
      label1 = "${env["invalid...name"]}"
      label2 = "${env["valid.name"]}"
    }
  }
}

Job-related variables

VariableDescription
NOMAD_ALLOC_DIRThe path to the shared alloc/ directory. See here for more information.
NOMAD_TASK_DIRThe path to the task local/ directory. See here for more information.
NOMAD_SECRETS_DIRPath to the task's secrets directory. See here 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_CPU_CORESThe specific CPU cores reserved for the task in cpuset list notation. Omitted if the task does not request cpu cores. E.g. 0-2,7,12-14
NOMAD_ALLOC_IDAllocation ID of the task
NOMAD_SHORT_ALLOC_IDThe first 8 characters of the allocation 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_PARENT_CGROUPThe parent cgroup used to contain task cgroups (Linux only)
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. See Vault Integration for more details

Network-related Variables

VariableDescription
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_UPSTREAM_IP_<service>IP for the given service when defined as a Consul Connect upstream.
NOMAD_UPSTREAM_PORT_<service>Port for the given service when defined as a Consul Connect upstream.
NOMAD_UPSTREAM_ADDR_<service>Host IP:Port for the given service when defined as a Consul Connect upstream.
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.

Note: Port labels and task names will have any non-alphanumeric or underscore characters in their names replaced by underscores _ when they're used in environment variable names such as NOMAD_ADDR_<task>_<label>.

Consul-related Variables

This variables are only set for Connect native tasks.

VariableDescription
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_ssl option.
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_ssl option.
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_ssl option.
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.
Edit this page on GitHub

On this page

  1. Variable Interpolation
  2. Node Variables
  3. Environment Variables
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)