open-nomad/website/pages/docs/job-specification/hcl2/index.mdx
2020-11-30 09:29:24 -06:00

116 lines
3.3 KiB
Plaintext

---
layout: docs
page_title: Configuration Language
sidebar_title: HCL2 <sup>Beta</sup>
description: |-
Noamd uses text files to describe infrastructure and to set variables.
These text files are called Nomad job specifications and are
written in the HCL language.
---
# HCL <sup>Beta</sup>
`@include 'beta-nomad1.0-note.mdx'`
Nomad uses the Hashicorp Configuration Language - HCL - designed to allow
concise descriptions of the required steps to get to a job file.
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.
<!---
TODO: Re-Add after guide
This page describes the features of HCL2 exhaustively, if you would like to give
a quick try to HCL2, you can also read the quicker [HCL2 getting started
guide](/guides/hcl).
--->
## Syntax
The main purpose of the HCL language in Nomad is defining jobs. All other
language features exist only to make the definition of builds more flexible and
convenient.
## Arguments, Blocks, and Expressions
The syntax of the HCL language consists of only a few basic elements:
```hcl
task "example" {
driver = "docker"
}
<BLOCK TYPE> "<BLOCK LABEL>" {
# Block body
<IDENTIFIER> = <EXPRESSION> # Argument
}
```
- _Blocks_ are containers for other content and usually represent the
configuration of some kind of object, like a task. Blocks have a
_block type,_ can have zero or more _labels,_ and have a _body_ that contains
any number of arguments and nested blocks.
- _Arguments_ assign a value to a name. They appear within blocks.
- _Expressions_ represent a value, either literally or by referencing and
combining other values. They appear as values for arguments, or within other
expressions.
For full details about Nomad's syntax, see:
- [Configuration Syntax](/docs/job-specification/hcl2/syntax)
- [Expressions](/docs/job-specification/hcl2/expressions)
## 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 = "..."
}
```
### Multiline "here doc" strings
Nomad supports multi-line string literals in the so-called "heredoc" style, inspired by Unix shell languages:
```hcl
template {
data = <<EOF
hello
world
EOF
}
```
HCL2 trims the whitespace preceding the delimiter in the last line. So in the
above example, `data` is read as `"hello\n world\n "` in HCL1, but `"hello\n
world\n"` (note lack of trailing whitespace) in HCL2.