• Overview
    • Batch Processing Workloads
    • Edge Workload Management
    • Non-Containerized Application Orchestration
    • Simple Container Orchestration
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Plugins
  • Tools
  • Community
GitHub—Stars on GitHub
Download
    • v1.3.x (latest)
    • v1.2.x
    • v1.1.x
    • v1.0.x
    • v0.12.x
    • v0.11.x
    • Overview
    • Quickstart
      • Overview
      • Requirements
      • Reference Architecture
      • Deployment Guide
    • Windows Service
    • Overview
    • Specific Version Details
    • Overview
    • Consul
    • Consul Service Mesh
    • Vault Integration

    • Overview
    • Architecture
      • Overview
      • Base
      • Task Drivers
      • Devices
      • Storage
      • Overview
      • Concepts
      • Preemption
    • Consensus Protocol
    • Filesystem
    • Gossip Protocol
    • Security Model
    • Overview
    • acl
    • audit
    • autopilot
    • client
    • consul
    • plugin
    • sentinel
    • search
    • server
    • server_join
    • telemetry
    • tls
    • ui
    • vault
    • Overview
      • Overview
      • bootstrap
      • policy apply
      • policy delete
      • policy info
      • policy list
      • token create
      • token delete
      • token info
      • token list
      • token self
      • token update
    • agent
    • agent-info
      • Overview
      • exec
      • fs
      • logs
      • restart
      • signal
      • status
      • stop
      • Overview
      • validate
      • Overview
      • fail
      • list
      • pause
      • promote
      • resume
      • status
      • unblock
      • Overview
      • delete
      • list
      • status
      • Overview
      • allocs
      • deployments
      • dispatch
      • eval
      • history
      • init
      • inspect
      • plan
      • periodic force
      • promote
      • revert
      • run
      • scale
      • scaling-events
      • status
      • stop
      • validate
      • Overview
      • get
    • monitor
      • Overview
      • apply
      • delete
      • inspect
      • list
      • status
      • Overview
      • config
      • drain
      • eligibility
      • status
      • Overview
      • api
        • get-config
        • set-config
      • debug
      • keygen
      • keyring
      • metrics
        • info
        • list-peers
        • logs
        • remove-peer
        • state
        • get-config
        • set-config
        • agent
        • inspect
        • restore
        • save
        • state
      • Overview
      • status
      • Overview
      • apply
      • delete
      • init
      • inspect
      • list
      • status
      • Overview
      • apply
      • dismiss
      • info
      • list
      • Overview
      • policy info
      • policy list
      • Overview
      • apply
      • delete
      • list
      • read
      • Overview
      • force-leave
      • join
      • members
      • Overview
      • service delete
      • service info
      • service list
    • status
      • Overview
      • gc
      • reconcile summaries
    • ui
    • version
      • Overview
      • create
      • delete
      • deregister
      • detach
      • init
      • register
      • snapshot create
      • snapshot delete
      • snapshot list
      • status

    • Overview
      • Overview
      • Expressions
        • Overview
          • chunklist
          • coalesce
          • coalescelist
          • compact
          • concat
          • contains
          • distinct
          • element
          • flatten
          • index
          • keys
          • length
          • lookup
          • merge
          • range
          • reverse
          • setintersection
          • setproduct
          • setunion
          • slice
          • sort
          • values
          • zipmap
          • can
          • convert
          • try
          • bcrypt
          • md5
          • rsadecrypt
          • sha1
          • sha256
          • sha512
          • formatdate
          • timeadd
          • base64decode
          • base64encode
          • csvdecode
          • jsondecode
          • jsonencode
          • urlencode
          • yamldecode
          • yamlencode
          • abspath
          • basename
          • dirname
          • file
          • filebase64
          • fileexists
          • fileset
          • pathexpand
          • cidrhost
          • cidrnetmask
          • cidrsubnet
          • cidrsubnets
          • abs
          • ceil
          • floor
          • log
          • max
          • min
          • parseint
          • pow
          • signum
          • chomp
          • format
          • formatlist
          • indent
          • join
          • lower
          • regex_replace
          • replace
          • split
          • strrev
          • substr
          • title
          • trim
          • trimprefix
          • trimspace
          • trimsuffix
          • upper
          • uuidv4
          • uuidv5
      • Locals
      • Syntax
      • Variables
    • artifact
    • affinity
    • check
    • check_restart
    • connect
    • constraint
    • csi_plugin
    • device
    • dispatch_payload
    • env
    • ephemeral_disk
    • expose
    • gateway
    • group
    • job
    • lifecycle
    • logs
    • meta
    • migrate
    • multiregion
    • network
    • parameterized
    • periodic
    • proxy
    • reschedule
    • resources
    • restart
    • scaling
    • service
    • sidecar_service
    • sidecar_task
    • spread
    • task
    • template
    • update
    • upstreams
    • vault
    • volume
    • volume_mount
    • Overview
    • ACL Policy
      • Overview
      • capability
      • mount_options
      • topology_request
    • Overview
    • Docker
    • Isolated Fork/Exec
    • Java
    • Podman
    • QEMU
    • Raw Fork/Exec
      • Overview
      • containerd
      • Firecracker driver
      • Jailtask driver
      • Lightrun
      • LXC
      • Pot
      • Rkt Deprecated
      • Rookout
      • Singularity
      • systemd-nspawn
      • Windows IIS
      • Overview
      • ECS
    • Overview
      • Overview
      • Nvidia
      • USB Beta
  • Schedulers
    • Overview
    • Runtime Environment
    • Variable Interpolation
    • Overview
      • Overview
      • apm
      • dynamic_application_sizing
      • http
      • nomad
      • policy
      • policy_eval
      • source
      • strategy
      • target
      • telemetry
    • API
    • CLI
    • Policy
    • Telemetry
      • Overview
        • Overview
        • Datadog
        • Nomad API
        • Prometheus
        • Overview
        • Dynamic Application Sizing Average
        • Dynamic Application Sizing Max
        • Dynamic Application Sizing Percentile
        • Fixed Value
        • Pass-Through
        • Target Value
        • Threshold
        • Overview
        • Amazon Web Services Autoscaling Group
        • Azure Virtual Machine Scale Set
        • Dynamic Application Sizing
        • Google Cloud Engine Managed Instance Group
        • Nomad Task Group
      • Community
      • Overview
      • Checks
      • Node Selector Strategy
        • Overview
        • Base
        • APM
        • Strategy
        • Target
    • Overview
    • Operating Nomad Agents
    • Monitoring Nomad
    • Metrics Reference
    • Cluster Management
    • Transport Security
    • Access Control

    • Overview
    • Alternative to Kubernetes
    • Supplement to Kubernetes
  • Nomad Ecosystem
  • Nomad Partnerships
  • Who Uses Nomad
    • Overview
      • Overview
      • FAQ
  • FAQ
Type '/' to Search

»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.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"
  }
}
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:7"
    labels {
      label1 = "${env["invalid...name"]}"
      label2 = "${env["valid.name"]}"
    }
  }
}
task "redis" {
  driver = "docker"
  config {
    image  = "redis:7"
    labels {
      label1 = "${env["invalid...name"]}"
      label2 = "${env["valid.name"]}"
    }
  }
}
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 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
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>Deprecated. Host IP for the given port labeland task for tasks in the same task group. Only available when setting ports via the task resource network port mapping.
NOMAD_PORT_<task>_<label>Deprecated. Port for the given port label andtask 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. Only available when setting ports via the task resource network port mapping.
NOMAD_ADDR_<task>_<label>Deprecated. Host IP:Port pair for the given portlabel and task for tasks in the same task group. Only available when setting ports via the task resource network port mapping.
NOMAD_HOST_PORT_<task>_<label>Deprecated. Port on the host for the port label andtask for tasks in the same task group. Only available when setting ports via the task resource network port mapping.
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.
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.
github logoEdit this page
DocsAPIResourcesPrivacySecurityPress KitConsent Manager