d0495e1b56
Mainly note that block labels need to be string literals, and that decimals without a leading significant digits aren't acceptable anymore (e.g. .9 are required to be 0.9). Dynamic blocks can be used here, but feels too much of a hack, or a hammer to highlight it here, specially given the error reporting and debugging isn't so straightforward. I'd advocate internally for relaxing the restriction and allowing expressions in block labels instead. Related to https://github.com/hashicorp/nomad/issues/9522
135 lines
4.2 KiB
Plaintext
135 lines
4.2 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).
|
|
--->
|
|
|
|
## HCL Parsing Context
|
|
|
|
The [Nomad API uses JSON][jobs-api], not HCL, to represent Nomad jobs.
|
|
When running commands like `nomad job run` and `nomad job plan`, the Nomad CLI
|
|
parses HCL and ultimately converts it to JSON. Because this parsing happens locally
|
|
(i.e., where the operator is running the CLI) before job submission, there are some
|
|
limits to the capabilities that can be accessed by HCL job specifications. For
|
|
example, scheduling information is not yet available, including information about
|
|
the client. Similarly, HCL features that depend on external context will take that
|
|
context from the local environment of the CLI (e.g., files, environment variables).
|
|
|
|
[jobs-api]: /api-docs/jobs
|
|
|
|
## 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. Block labels must be string literals.
|
|
- _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.
|
|
|
|
### Decimals
|
|
|
|
Nomad 0.12 and earlier accepted small decimal values without a leading zero
|
|
(e.g. `.3`, `.59`, `.9`). In such case, Nomad 1.0 requires a leading zero (e.g.
|
|
`0.3`, `0.59`, `0.9`).
|