»HCL2 Beta

Nomad 1.0 adopts HCL2, the second generation of HashiCorp Configuration Language. HCL2 extends the HCL language by adding expressions and input variables support to improve job spec reusability and readability. Also, the new HCL2 parser improves the error messages for invalid jobs.

»Expressions

Nomad 1.0 supports expressions and built-in functions, allowing for a more concise job spec. HCL2 allows use of the following expressions:

  • value literals: e.g. 42, "hello", true
  • arithmetic expression: 5*100
  • for-each expressions: [for s in [3, 4, 5]: s+1] (which evaluates to [4, 5, 6])
  • invocation of function calls: upper("FOO").

For a full list of available functions, see the function reference.

The following snippet illustrates the power of expressions and built-in functions:

template {
  # `file` function can load external files without embedding them in the jobspec file
  data        = file("scripts.sh")
  destination = "local/scripts.sh"
}

template {
  # jsonencode eases maintaining json field
  data        = jsonencode({ regions = { tokyo = 4, mumbai = 2, us_east = 3 }})
  destination = "local/region_mapping.json"
}

resources {
  # arithmetics can make values more obvious
  memory = 2 * 1014
}

»Input Variables

Input variables serve as parameters for Nomad jobs, allowing reuse of the job spec to target multiple environments or contexts without altering the job spec source.

Input variables don't need to be explicitly declared, and can be referenced within expressions as vars.<NAME>. You can set the variable in the CLI by passing -var <NAME>=<VALUE>.

For example, to repurpose the job spec to target different environments (e.g. staging vs production), you can use vars.environment in the job spec, and pass --var environment=production.

»Backward Compatibilities

HCL2 syntax closely mirrors HCL1, but has some minor changes. Most existing Nomad job specifications will not require any changes.

When you run nomad job run or nomad job plan, the CLI will report any required changes. Also, you can activate a backwards compatibility mode by passing -hcl1 to use Nomad's HCL1 parser instead.

»Blocks

Nomad 0.12 and earlier allowed a few variations for defining blocks. For example, the following variations of meta were accepted:

meta {
  # meta attributes can be quoted or not
  "team"       = "..."
  organization = "..."
}

# meta can be an assignment to a map
meta = { "team" = "...", organization = "..." }

Starting with Nomad 1.0 and the HCL2 parser, only the block syntax with unquoted attributes is accepted:

meta {
  team         = "..."
  organization = "..."
}