116 lines
3.3 KiB
Plaintext
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.
|