open-nomad/website/content/docs/job-specification/hcl2/variables.mdx

---
layout: docs
page_title: Input Variables - HCL Configuration Language
description: |-
  Input variables are parameters for Nomad jobs.
  This page covers configuration syntax for variables.
---

# Input Variables

Input variables serve as parameters for a Nomad job, allowing aspects of the
job to be customized without altering the job's own source code.

When you declare variables in the same file as the job specification, you
can set their values using CLI options and environment variables.

-> **Note:** For brevity, input variables are often referred to as just
"variables" or "Nomad variables" when it is clear from context what sort of
variable is being discussed. Other kinds of variables in Nomad include
_environment variables_ (set by the shell where Nomad runs) and _expression
variables_ (used to indirectly represent a value in an
[expression](/docs/job-specification/hcl2/expressions)).

## Declaring an Input Variable

Each input variable accepted by a job must be declared using a `variable`
block :

```hcl
variable "image_id" {
  type = string
}

variable "availability_zone_names" {
  type    = list(string)
  default = ["us-west-1a"]
}

variable "docker_ports" {
  type = list(object({
    internal = number
    external = number
    protocol = string
  }))
  default = [
    {
      internal = 8300
      external = 8300
      protocol = "tcp"
    }
  ]
}
```

Or a less precise variables block:

```hcl
variables {
  foo       = "value"
  my_secret = "foo"
}
```

The label after the `variable` keyword or a label of a `variables` block is a
name for the variable, which must be unique among all variables in the same
job. This name is used to assign a value to the variable from outside and to
reference the variable's value from within the job.

The `variable` block can optionally include a `type` argument to specify what
value types are accepted for the variable, as described in the following
section.

The `variable` declaration can also include a `default` argument. If present,
the variable is considered to be _optional_ and the default value will be used
if no value is set when calling the job or running Nomad. The `default`
argument requires a literal value and cannot reference other objects in the
configuration.

## Using Input Variable Values

Within the job that declared a variable, its value can be accessed from within
[expressions](/docs/job-specification/hcl2/expressions) as `var.<NAME>`, where
`<NAME>` matches the label given in the declaration block:

```hcl
config {
  image = var.task_image
  label = var.task_labels
}
```

The value assigned to a variable can be accessed only from expressions within
the folder where it was declared. Note that a block label (such as the job ID
or task group name) is not an expression and so can't be interpolated with a
variable or local.

## Type Constraints

The `type` argument in a `variable` block allows you to restrict the [type of
value](/docs/job-specification/hcl2/expressions#types-and-values) that will be
accepted as the value for a variable. If no type constraint is set then a
value of any type is accepted.

While type constraints are optional, we recommend specifying them; they serve
as easy reminders for users of the job, and allow Nomad to return a helpful
error message if the wrong type is used.

Type constraints are created from a mixture of type keywords and type
constructors. The supported type keywords are:

- `string`
- `number`
- `bool`

The type constructors allow you to specify complex types such as collections:

- `list(<TYPE>)`
- `set(<TYPE>)`
- `map(<TYPE>)`
- `object({<ATTR NAME> = <TYPE>, ... })`
- `tuple([<TYPE>, ...])`

The keyword `any` may be used to indicate that any type is acceptable. For more
information on the meaning and behavior of these different types, as well as
detailed information about automatic conversion of complex types, see [Type
Constraints](https://www.terraform.io/docs/configuration/types.html).

If both the `type` and `default` arguments are specified, the given default
value must be convertible to the specified type.

If only `default` is specified, the type of the default value will be used.

When the `type` and `default` are both _not_ specified and you try to set a
variable [from env vars](#environment-variables) or [from the command
line](#variables-on-the-command-line), the variable will always be interpreted
as a string.

## Input Variable Documentation

Because the input variables of a job are part of its user interface, you can
briefly describe the purpose of each variable using the optional `description`
argument:

```hcl
variable "image_id" {
  type        = string
  description = "The docker image used for task."
}
```

The description should concisely explain the purpose of the variable and what
kind of value is expected. This description string might be included in
documentation about the job, and so it should be written from the perspective
of the user of the job rather than its maintainer. For commentary for job
maintainers, use comments.

## Input Variable Custom Validation Rules

Input variables support specifying arbitrary custom validation rules for a particular
variable using a `validation` block nested within the corresponding `variable` block:

```hcl
variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."

  validation {
    condition     = substr(var.image_id, 0, 4) == "ami-"
    error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"."
  }
}
```

The condition argument is an expression that must use the value of the variable to
return true if the value is valid, or false if it is invalid. The expression can
refer only to the variable that the condition applies to, and _must_ not produce errors.

If condition evaluates to false, Nomad will produce an error message that includes
the sentences given in `error_message`. The error message string should be at least
one full sentence explaining the constraint that failed, starting with an uppercase
letter ( if the alphabet permits it ) and ending with a period or question mark.

Multiple validation blocks can be declared in which case error messages will be
returned for all failed conditions.

## Assigning Values to job Variables

Once a variable is declared in your configuration, you can set it:

- Individually, with the `-var foo=bar` command line option.
- In variable definitions files specified on the command line (with `-var-file=input.vars`).
- As environment variables, for example: `NOMAD_VAR_foo=bar`

The following sections describe these options in more detail.

### Variables on the Command Line

To specify individual variables on the command line, use the `-var` option when
running the `nomad job run` command:

```shell-session
$ nomad job run -var="image_id=nginx:1.19" example.nomad
```

The `-var` option can be used any number of times in a single command.

If you plan to assign variables via the command line, we strongly recommend that
you at least set a default type instead of using empty blocks; this helps the
HCL parser understand what is being set. Otherwise, the interpreter will assume
that any variable set on the command line is a string.

### Variable Definitions Files

To set lots of variables, it is more convenient to specify their values in a
_variable definitions file_ and then specify that file on the command line with
`-var-file`:

```shell-session
$ nomad job run -var-file="testing.vars" example.nomad
```

A variable definitions file uses the same HCL basic syntax, but consists only
of variable name assignments:

```hcl
image_id = "nginx:1.19"
labels = [
  "testing",
  "internal",
]
```

Alternatively, the files can be JSON objects, with the root object properties
corresponding to variable names:

```json
{
  "image_id": "nginx:1.19",
  "labels": ["testing", "internal"]
}
```

### Environment Variables

As a fallback for the other ways of defining variables, Nomad searches the
environment of its own process for environment variables named `NOMAD_VAR_`
followed by the name of a declared variable.

This can be useful when running Nomad in automation, or when running a
sequence of Nomad commands in succession with the same variables. For example,
at a `bash` prompt on a Unix system:

```shell-session
$ export NOMAD_VAR_image_id=nginx:1.19
$ nomad job run example.nomad
...
```

On operating systems where environment variable names are case-sensitive,
Nomad matches the variable name exactly as given in configuration, and so the
required environment variable name will usually have a mix of upper and lower
case letters as in the above example.

### Complex-typed Values

When variable values are provided in a variable definitions file, Nomad's
[usual syntax](/docs/job-specification/hcl2/expressions) can be used to assign
complex-typed values, like lists and maps.

Some special rules apply to the `-var` command line option and to environment
variables. For convenience, Nomad defaults to interpreting `-var` and
environment variable values as literal strings, which do not need to be quoted:

```shell-session
$ export NOMAD_VAR_image_id=nginx:1.19
```

However, if an input variable uses a [type constraint](#type-constraints) to
require a complex value (list, set, map, object, or tuple), Nomad will instead
attempt to parse its value using the same syntax used within variable
definitions files, which requires careful attention to the string escaping
rules in your shell:

```shell-session
$ export NOMAD_VAR_availability_zone_names='["us-west-1b","us-west-1d"]'
```

For readability, and to avoid the need to worry about shell escaping, we
recommend always setting complex variable values via variable definitions
files.

### Variable Definition Precedence

The above mechanisms for setting variables can be used together in any
combination.

Nomad loads variables in the following order, with later sources taking
precedence over earlier ones:

- Environment variables (lowest priority)
- Any `-var` and `-var-file` options on the command line, in the order they are
  provided. (highest priority)

If the same variable is assigned multiple values using different mechanisms,
Nomad uses the _last_ value it finds, overriding any previous values. Note
that the same variable cannot be assigned multiple values within a single source.

~> **Important:** Variables with map and object values behave the same way as
other variables: the last value found overrides the previous values.

## A variable value must be known:

Take the following variable for example:

```hcl
variable "foo" {
  type = string
}
```

Here `foo` must have a known value but you can default it to `null` to make
this behavior optional :

|                                 |          no default          | `default = null` | `default = "xy"` |
| :-----------------------------: | :--------------------------: | :--------------: | :--------------: |
|           foo unused            | error, "foo needs to be set" |        -         |        -         |
|             var.foo             | error, "foo needs to be set" |       null       |        xy        |
| `NOMAD_VAR_foo=yz`<br />var.foo |              yz              |        yz        |        yz        |
|   `-var foo=yz`<br />var.foo    |              yz              |        yz        |        yz        |