96 lines
3 KiB
Plaintext
96 lines
3 KiB
Plaintext
|
---
|
||
|
|
layout: docs
|
||
|
|
page_title: HCL2
|
||
|
|
sidebar_title: HCL2 <sup>Beta</sup>
|
||
|
|
description: Learn about the Job specification HCL2 used to submit jobs to Nomad.
|
||
|
|
---
|
||
|
|
|
||
|
|
# HCL2 <sup>Beta</sup>
|
||
|
|
|
||
|
|
~> **NOTE:** This page is about Nomad 1.0 Beta. Details are subject to change before final release.
|
||
|
|
|
||
|
|
Nomad 1.0 adopts
|
||
|
|
[HCL2](https://github.com/hashicorp/hcl2/blob/master/README.md), 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](https://www.packer.io/docs/from-1.5/functions).
|
||
|
|
|
||
|
|
The following snippet illustrates the power of expressions and built-in functions:
|
||
|
|
|
||
|
|
```hcl
|
||
|
|
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:
|
||
|
|
|
||
|
|
```hcl
|
||
|
|
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:
|
||
|
|
|
||
|
|
```hcl
|
||
|
|
meta {
|
||
|
|
team = "..."
|
||
|
|
organization = "..."
|
||
|
|
}
|
||
|
|
```
|