document hcl language & syntax
This commit is contained in:
Adrien Delorme
parent
26ceea0c36
commit
bb72a0c0ce
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Configuration Language"
|
||||
sidebar_current: "configuration"
|
||||
description: |-
|
||||
Packer uses text files to describe infrastructure and to set variables.
|
||||
These text files are called Packer _configurations_ and are
|
||||
written in the HCL language.
|
||||
---
|
||||
|
||||
# HCL Configuration Language
|
||||
|
||||
Packer uses the Hashicorp Configuration Language - HCL - designed to allow
|
||||
concise descriptions of the required steps to get to a build file.
|
||||
|
||||
## Builds
|
||||
|
||||
The main purpose of the HCL language is defining builds and sources. All other
|
||||
language features exist only to make the definition of builds more flexible and
|
||||
convenient.
|
||||
|
||||
|
||||
`packer build` takes one argument. When a directory is passed, all files in the
|
||||
folder with a name ending with ".pkr.hcl" or ".pkr.json" will be parsed using
|
||||
the HCL2 format. When a file ending with ".pkr.hcl" or ".pkr.json" is passed it
|
||||
will be parsed using the HCL2 schema. For every other case; the *JSON only* old
|
||||
packer schema will be used.
|
||||
|
||||
## Arguments, Blocks, and Expressions
|
||||
|
||||
The syntax of the HCL language consists of only a few basic elements:
|
||||
|
||||
```hcl
|
||||
source "amazon-ebs" "main" {
|
||||
ami_name = "main-ami"
|
||||
}
|
||||
|
||||
<BLOCK TYPE> "<BLOCK LABEL>" "<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 source. Blocks have a
|
||||
_block type,_ can have zero or more _labels,_ and have a _body_ that contains
|
||||
any number of arguments and nested blocks. Most of Packer's features are
|
||||
controlled by top-level blocks in a configuration file.
|
||||
- _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 Packer's syntax, see:
|
||||
|
||||
- [Configuration Syntax](./syntax.html)
|
||||
- [Expressions](./expressions.html)
|
||||
|
||||
## Code Organization
|
||||
|
||||
The HCL language uses configuration files that are named with the `.pkr.hcl`
|
||||
file extension. There is also [a JSON-based variant of the
|
||||
language](./syntax-json.html) that is named with the `.pkr.json` file
|
||||
extension.
|
||||
|
||||
Configuration files must always use UTF-8 encoding, and by convention are
|
||||
usually maintained with Unix-style line endings (LF) rather than Windows-style
|
||||
line endings (CRLF), though both are accepted.
|
||||
|
||||
## Configuration Ordering
|
||||
|
||||
The ordering of root blocks is not significant. The order of `provisioner` or
|
||||
`post-processor` blocks within a `build` is the only major feature where block
|
||||
order matters.
|
||||
|
|
@ -0,0 +1,119 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Syntax - Configuration Language"
|
||||
sidebar_current: configuration-syntax
|
||||
description: |-
|
||||
HCL has its own syntax, intended to combine declarative
|
||||
structure with expressions in a way that is easy for humans to read and
|
||||
understand.
|
||||
---
|
||||
|
||||
# HCL Configuration Syntax
|
||||
|
||||
Other pages in this section have described various configuration constructs
|
||||
that can appear in HCL. This page describes the lower-level syntax of the
|
||||
language in more detail, revealing the building blocks that those constructs
|
||||
are built from.
|
||||
|
||||
This page describes the _native syntax_ of HCL, which is a rich language
|
||||
designed to be easy for humans to read and write. The constructs in HCL can
|
||||
also be expressed in [JSON syntax](/syntax-json.html), which is harder for
|
||||
humans to read and edit but easier to generate and parse programmatically.
|
||||
|
||||
This low-level syntax of HCL is defined in terms of a syntax called _HCL_,
|
||||
which is also used by configuration languages in other applications, and in
|
||||
particular other HashiCorp products. It is not necessary to know all of the
|
||||
details of HCL in order to use Packer, and so this page summarizes the most
|
||||
important details. If you are interested, you can find a full definition of HCL
|
||||
syntax in [the HCL native syntax
|
||||
specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).
|
||||
|
||||
## Arguments and Blocks
|
||||
|
||||
HCL syntax is built around two key syntax constructs:
|
||||
arguments and blocks.
|
||||
|
||||
### Arguments
|
||||
|
||||
An _argument_ assigns a value to a particular name:
|
||||
|
||||
```hcl
|
||||
image_id = "abc123"
|
||||
```
|
||||
|
||||
The identifier before the equals sign is the _argument name_, and the expression
|
||||
after the equals sign is the argument's value.
|
||||
|
||||
The context where the argument appears determines what value types are valid
|
||||
(for example, each source type has a schema that defines the types of its
|
||||
arguments), but many arguments accept arbitrary
|
||||
[expressions](/expressions.html), which allow the value to
|
||||
either be specified literally or generated from other values programmatically.
|
||||
|
||||
### Blocks
|
||||
|
||||
A _block_ is a container for other content:
|
||||
|
||||
```hcl
|
||||
source "amazon-ebs" "example" {
|
||||
ami_name = "abc123"
|
||||
|
||||
tags {
|
||||
# ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A block has a _type_ (`source` in this example). Each block type defines
|
||||
how many _labels_ must follow the type keyword. The `source` block type
|
||||
expects two labels, which are `amazon-ebs` and `example` in the example above.
|
||||
A particular block type may have any number of required labels, or it may
|
||||
require none as with the nested `tags` block type.
|
||||
|
||||
After the block type keyword and any labels, the block _body_ is delimited
|
||||
by the `{` and `}` characters. Within the block body, further arguments
|
||||
and blocks may be nested, creating a hierarchy of blocks and their associated
|
||||
arguments.
|
||||
|
||||
HCL uses a limited number of _top-level block types,_ which
|
||||
are blocks that can appear outside of any other block in a configuration file.
|
||||
Most of Packer's features (including resources, input variables, output
|
||||
values, data sources, etc.) are implemented as top-level blocks.
|
||||
|
||||
## Identifiers
|
||||
|
||||
Argument names, block type names, and the names of most Packer-specific
|
||||
constructs like resources, input variables, etc. are all _identifiers_.
|
||||
|
||||
Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
|
||||
The first character of an identifier must not be a digit, to avoid ambiguity
|
||||
with literal numbers.
|
||||
|
||||
For complete identifier rules, Packer implements
|
||||
[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
|
||||
include the ASCII hyphen character `-`.
|
||||
|
||||
## Comments
|
||||
|
||||
HCL supports three different syntaxes for comments:
|
||||
|
||||
* `#` begins a single-line comment, ending at the end of the line.
|
||||
* `//` also begins a single-line comment, as an alternative to `#`.
|
||||
* `/*` and `*/` are start and end delimiters for a comment that might span
|
||||
over multiple lines.
|
||||
|
||||
The `#` single-line comment style is the default comment style and should be
|
||||
used in most cases. Automatic configuration formatting tools may automatically
|
||||
transform `//` comments into `#` comments, since the double-slash style is
|
||||
not idiomatic.
|
||||
|
||||
## Character Encoding and Line Endings
|
||||
|
||||
Packer configuration files must always be UTF-8 encoded. While the
|
||||
delimiters of the language are all ASCII characters, Packer accepts
|
||||
non-ASCII characters in identifiers, comments, and string values.
|
||||
|
||||
Packer accepts configuration files with either Unix-style line endings
|
||||
(LF only) or Windows-style line endings (CR then LF), but the idiomatic style
|
||||
is to use the Unix convention, and so automatic configuration formatting tools
|
||||
may automatically transform CRLF endings to LF.
|
||||
|
|
@ -2,6 +2,17 @@
|
|||
<% content_for :sidebar do %>
|
||||
<ul class="nav docs-sidenav">
|
||||
|
||||
<li<%= sidebar_current("configuration") %>>
|
||||
<a href="/docs/configuration/from-1.5/index.html">HCL</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("configuration-syntax") %>>
|
||||
<a href="/docs/configuration/from-1.5/syntax.html">Syntax</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<hr>
|
||||
|
||||
<li><a href="/docs/basics/terminology.html">Terminology</a></li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands") %>>
|
||||
|
|
|
|||
Loading…
Reference in New Issue