github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/runtime/interpolation.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: Variable Interpolation
     4  description: Learn about the Nomad's interpolation and interpreted variables.
     5  ---
     6  
     7  # Variable Interpolation
     8  
     9  Nomad supports interpreting two classes of variables: node attributes and
    10  runtime environment variables. Node attributes are interpretable in constraints,
    11  task environment variables, and certain driver fields. Runtime environment
    12  variables are not interpretable in constraints because they are only defined
    13  once the scheduler has placed them on a particular node.
    14  
    15  The syntax for interpreting variables is `${variable}`. An example and a
    16  comprehensive list of interpretable fields can be seen below:
    17  
    18  ```hcl
    19  task "docs" {
    20    driver = "docker"
    21  
    22    # Drivers support interpreting node attributes and runtime environment
    23    # variables
    24    config {
    25      image = "my-app"
    26  
    27      # Interpret runtime variables to inject the address to bind to and the
    28      # location to write logs to.
    29      args = [
    30        "--bind", "${NOMAD_ADDR_RPC}",
    31        "--logs", "${NOMAD_ALLOC_DIR}/logs",
    32      ]
    33  
    34      port_map {
    35        RPC = 6379
    36      }
    37    }
    38  
    39    # Constraints only support node attributes as runtime environment variables
    40    # are only defined after the task is placed on a node.
    41    constraint {
    42      attribute = "${attr.kernel.name}"
    43      value     = "linux"
    44    }
    45  
    46    # Environment variables are interpreted and can contain both runtime and
    47    # node attributes. These environment variables are passed into the task.
    48    env {
    49      DC      = "Running on datacenter ${node.datacenter}"
    50      VERSION = "Version ${NOMAD_META_VERSION}"
    51    }
    52  
    53    # Meta keys are also interpretable.
    54    meta {
    55      VERSION = "v0.3"
    56    }
    57  }
    58  ```
    59  
    60  ## Node Variables ((#interpreted_node_vars, #node-variables-))
    61  
    62  Below is a full listing of node attributes that are interpretable. These
    63  attributes are interpreted by **both** constraints and within the task and
    64  driver.
    65  
    66  | Variable                  | Description                                 | Example Value                          |
    67  | ------------------------- | ------------------------------------------- | -------------------------------------- |
    68  | `${node.unique.id}`   | 36 character unique client identifier       | `9afa5da1-8f39-25a2-48dc-ba31fd7c0023` |
    69  | `${node.region}`      | Client's region                             | `global`                               |
    70  | `${node.datacenter}`  | Client's datacenter                         | `dc1`                                  |
    71  | `${node.unique.name}` | Client's name                               | `nomad-client-10-1-2-4`                |
    72  | `${node.class}`       | Client's class                              | `linux-64bit`                          |
    73  | `${attr.<property>}`        | Property given by `property` on the client  | `${attr.cpu.arch} => amd64`        |
    74  | `${meta.<key>}`        | Metadata value given by `key` on the client | `${meta.foo} => bar`               |
    75  
    76  Below is a table documenting common node properties:
    77  
    78  | Property                                               | Description                                                                                                                                            |
    79  | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
    80  | `${attr.cpu.arch}`                                 | CPU architecture of the client (e.g. `amd64`, `386`)                                                                                              |
    81  | `${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`. |
    82  | `${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.          |
    83  | `${attr.cpu.totalcompute}`                         | `cpu.frequency × cpu.numcores` but may be overridden by `client.cpu_total_compute`                                                                |
    84  | `${attr.consul.datacenter}`                        | The Consul datacenter of the client (if Consul is found)                                                                                               |
    85  | `${attr.driver.<property>}`                              | See the [task drivers](/docs/drivers) for property documentation                                                                                       |
    86  | `${attr.unique.hostname}`                          | Hostname of the client                                                                                                                                 |
    87  | `${attr.unique.network.ip-address}`                | The IP address fingerprinted by the client and from which task ports are allocated                                                                     |
    88  | `${attr.kernel.arch}`                              | Kernel architecture of the client (e.g. `x86_64`, `aarch64`)                                                                                           |
    89  | `${attr.kernel.name}`                              | Kernel of the client (e.g. `linux`, `darwin`)                                                                                                          |
    90  | `${attr.kernel.version}`                           | Version of the client kernel (e.g. `3.19.0-25-generic`, `15.0.0`)                                                                                 |
    91  | `${attr.platform.aws.ami-id}`                      | AMI ID of the client (if on AWS EC2)                                                                                                                   |
    92  | `${attr.platform.aws.instance-life-cycle}`         | Instance lifecycle (e.g. spot, on-demand) of the client (if on AWS EC2)                                                                                |
    93  | `${attr.platform.aws.instance-type}`               | Instance type of the client (if on AWS EC2)                                                                                                            |
    94  | `${attr.platform.aws.placement.availability-zone}` | Availability Zone of the client (if on AWS EC2)                                                                                                        |
    95  | `${attr.os.name}`                                  | Operating system of the client (e.g. `ubuntu`, `windows`, `darwin`)                                                                               |
    96  | `${attr.os.version}`                               | Version of the client OS                                                                                                                               |
    97  
    98  The full list of node attributes can be obtained by running `nomad node status -verbose [node]`.
    99  
   100  Here are some examples of using node attributes and properties in a job file:
   101  
   102  ```hcl
   103  job "docs" {
   104    # This will constrain this job to only run on 64-bit clients.
   105    constraint {
   106      attribute = "${attr.cpu.arch}"
   107      value     = "amd64"
   108    }
   109  
   110    # This will restrict the job to only run on clients with 4 or more cores.
   111    # Note: you may also declare a resource requirement for CPU for a task.
   112    constraint {
   113      attribute = "${cpu.numcores}"
   114      operator  = ">="
   115      value     = "4"
   116    }
   117  
   118    # Only run this job on a memory-optimized AWS EC2 instance.
   119    constraint {
   120      attribute = "${attr.platform.aws.instance-type}"
   121      value     = "m4.xlarge"
   122    }
   123  }
   124  ```
   125  
   126  ## Environment Variables ((#interpreted_env_vars))
   127  
   128  The following are runtime environment variables that describe the environment
   129  the task is running in. These are only defined once the task has been placed on
   130  a particular node and as such can not be used in constraints.
   131  
   132  Environment variables should be enclosed in brackets `${...}` for
   133  interpolation.
   134  
   135  ### Dots in Variables ((#dots_in_vars))
   136  
   137  Starting in Nomad 0.9, task configuration interpolation requires variables to
   138  be valid identifiers. While this does not affect default variables or common
   139  custom variables, it is possible to define a variable that is not a valid
   140  identifier:
   141  
   142  ```hcl
   143  env {
   144    "valid.name"     = "ok"
   145    "invalid...name" = "not a valid identifier"
   146  }
   147  ```
   148  
   149  The environment variable `invalid...name` cannot be interpolated using the
   150  standard `"${invalid...name}"` syntax. The dots will be interpreted as object
   151  notation so multiple consecutive dots are invalid.
   152  
   153  To continue supporting all user environment variables Nomad 0.9 added a new
   154  `env` variable which allows accessing any environment variable through index
   155  syntax:
   156  
   157  ```hcl
   158  task "redis" {
   159    driver = "docker"
   160    config {
   161      image  = "redis:7"
   162      labels {
   163        label1 = "${env["invalid...name"]}"
   164        label2 = "${env["valid.name"]}"
   165      }
   166    }
   167  }
   168  ```
   169  
   170  @include 'envvars.mdx'