document hcl2 blocks
This commit is contained in:
Adrien Delorme
parent
ea1e1e8b14
commit
72f76cbc8e
|
|
@ -14,6 +14,15 @@ export default [
|
|||
'syntax',
|
||||
'expressions',
|
||||
'syntax-json',
|
||||
{
|
||||
category: 'blocks',
|
||||
content: [
|
||||
{
|
||||
category: 'build',
|
||||
content: [ 'source', 'provisioner', 'post-processor' ],
|
||||
},
|
||||
'locals', 'source', 'variable' ],
|
||||
},
|
||||
{
|
||||
category: 'functions',
|
||||
content: [
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: build - Blocks
|
||||
sidebar_title: <tt>build</tt>
|
||||
---
|
||||
|
||||
# The `build` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `build` block defines what builders are started and what they will do.
|
||||
|
||||
`@include 'from-1.5/builds/example-block.mdx'`
|
||||
|
||||
The list of available builders can be found in the [builders](/docs/builders)
|
||||
section.
|
||||
|
||||
It is also possible to create and use [custom
|
||||
builders](/docs/extending/custom-builders). There is also a list of [community
|
||||
builders](/community-tools#community-builders).
|
||||
|
||||
Note that it is possible to set fields of a build block directly from the
|
||||
build block of a [`build` block](/docs/from-1.5/blocks/build).
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: post-processor - build - Blocks
|
||||
sidebar_title: <tt>post-processor</tt>
|
||||
---
|
||||
|
||||
# The `post-processor` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `post-processor` block defines how a post-processor is configured.
|
||||
|
||||
```hcl
|
||||
# builds.pkr.hcl
|
||||
build {
|
||||
# ...
|
||||
post-processor "checksum" {
|
||||
checksum_types = [ "md5", "sha512" ]
|
||||
keep_input_artifact = true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Post-processors run after the image is built by the builder and provisioned by
|
||||
the provisioner(s). Post-processors are optional, and they can be used to
|
||||
upload artifacts, re-package, or more. The list of available post-processors
|
||||
can be found in the [post-processors](/docs/post-processors) section.
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: provisioner - build - Blocks
|
||||
sidebar_title: <tt>provisioner</tt>
|
||||
---
|
||||
|
||||
# The `provisioner` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `provisioner` block defines how a provisioner is configured.
|
||||
|
||||
```hcl
|
||||
# builds.pkr.hcl
|
||||
build {
|
||||
# ...
|
||||
provisioner "shell" {
|
||||
inline = [
|
||||
"echo provisioning all the things",
|
||||
"echo the value of 'foo' is '${var.foo}'",
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Provisioners use builtin and third-party software to install and configure the
|
||||
machine image after booting. Provisioners prepare the system for use.
|
||||
|
||||
|
||||
The list of available provisioners can be found in the
|
||||
[provisioners](/docs/provisioners) section.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: source - build - Blocks
|
||||
sidebar_title: <tt>source</tt>
|
||||
---
|
||||
|
||||
# The `source` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `source` block in a `build` block allows to use an already defined source
|
||||
and to set build fields of a source.
|
||||
|
||||
```hcl
|
||||
# builds.pkr.hcl
|
||||
build {
|
||||
source "amazon-ebs.example" {
|
||||
output = "specific-value"
|
||||
}
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
-> **Note:** If any top-level attribute is re-defined with the same name an
|
||||
error will be displayed. In other words you cannot define the `output` field in
|
||||
the source declaration **and** in the source usage.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Blocks - Configuration Language
|
||||
sidebar_title: Blocks
|
||||
description: |-
|
||||
The HCL language has a number of blocks that can be used to configure builds.
|
||||
---
|
||||
|
||||
# Built-in Blocks
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The Packer - HCL2 language includes a number of built-in blocks that you can
|
||||
use. A block is a container for configuration.
|
||||
|
||||
Blocks can be defined in multiple files and `packer build folder` will build
|
||||
using solely the file from a `folder`.
|
||||
|
||||
Packer does not support user-defined blocks and so only the blocks built in to
|
||||
the language are available for use. The navigation for this section includes a
|
||||
list of all of the available built-in HCL2 blocks.
|
||||
|
||||
## Config example:
|
||||
|
||||
`@include 'from-1.5/variables/foo-block.mdx'`
|
||||
|
||||
`@include 'from-1.5/locals/example-block.mdx'`
|
||||
|
||||
`@include 'from-1.5/sources/example-block.mdx'`
|
||||
|
||||
`@include 'from-1.5/builds/example-block.mdx'`
|
||||
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: locals - Blocks
|
||||
sidebar_title: <tt>locals</tt>
|
||||
---
|
||||
|
||||
# The `locals` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `locals` block also called the local-variable block defines locals within
|
||||
your Packer configuration.
|
||||
|
||||
`@include 'from-1.5/locals/example-block.mdx'`
|
||||
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: source - Blocks
|
||||
sidebar_title: <tt>source</tt>
|
||||
---
|
||||
|
||||
# The `source` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `source` block defines reusable [builders](/docs/builders) configuration
|
||||
blocks:
|
||||
|
||||
`@include 'from-1.5/sources/example-block.mdx'`
|
||||
|
||||
The list of available builders can be found in the [builders](/docs/builders)
|
||||
section.
|
||||
|
||||
It is also possible to create and use [custom
|
||||
builders](/docs/extending/custom-builders). There is also a list of [community
|
||||
builders](/community-tools#community-builders).
|
||||
|
||||
Note that it is possible to set source fields at the moment of using them in the
|
||||
source block of a [`build` block](/docs/from-1.5/blocks/build).
|
||||
|
||||
# More on variables
|
||||
|
||||
- Read the [full variables](/docs/from-1.5/variables) description for a more
|
||||
thorough read.
|
||||
- Read the [variables guide](/guides/hcl/variables) for more examples.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
description: >
|
||||
Something
|
||||
|
||||
Something
|
||||
layout: docs
|
||||
page_title: variable - Blocks
|
||||
sidebar_title: <tt>variable</tt>
|
||||
---
|
||||
|
||||
# The `variable` block
|
||||
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The `variable` block also called the input-variable block defines variables
|
||||
within your Packer configuration. An input-variable cannot be used in another
|
||||
input variable, we recommend using [locals](/docs/from-1.5/blocks/locals) for that instead.
|
||||
|
||||
`@include 'from-1.5/variables/foo-block.mdx'`
|
||||
|
||||
## Default value
|
||||
|
||||
If a default value is set, the variable is optional. Otherwise, the variable
|
||||
**must** be set.
|
||||
|
||||
`@include 'from-1.5/variables/assignment.mdx'`
|
||||
|
||||
Example of a variable assignment from a file:
|
||||
|
||||
`@include 'from-1.5/variables/foo-pkrvar.mdx'`
|
||||
|
||||
`@include 'from-1.5/variables/must-be-set.mdx'`
|
||||
|
||||
# More on variables
|
||||
|
||||
- Read the [full variables](/docs/from-1.5/variables) description for a more
|
||||
thorough read.
|
||||
- Read the [variables guide](/guides/hcl/variables) for more examples.
|
||||
|
|
@ -9,11 +9,7 @@ description: |-
|
|||
|
||||
# Expressions
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. Please see the [Packer Issue
|
||||
Tracker](https://github.com/hashicorp/packer/issues/9176) for a list of
|
||||
supported features. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
_Expressions_ are used to refer to or compute values within a configuration.
|
||||
The simplest expressions are just literal values, like `"hello"` or `5`, but
|
||||
|
|
|
|||
|
|
@ -9,9 +9,7 @@ description: |-
|
|||
|
||||
# Built-in Functions
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
The HCL language includes a number of built-in functions that you can
|
||||
call from within expressions to transform and combine values. The general
|
||||
|
|
|
|||
|
|
@ -10,11 +10,7 @@ description: |-
|
|||
|
||||
# HCL Configuration Language
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. Please see the [Packer Issue
|
||||
Tracker](https://github.com/hashicorp/packer/issues/9176) for a list of
|
||||
supported features. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
Packer uses the Hashicorp Configuration Language - HCL - designed to allow
|
||||
concise descriptions of the required steps to get to a build file. This page
|
||||
|
|
|
|||
|
|
@ -9,11 +9,7 @@ description: >-
|
|||
|
||||
# Local Values
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. Please see the [Packer Issue
|
||||
Tracker](https://github.com/hashicorp/packer/issues/9176) for a list of
|
||||
supported features. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
Local values assign a name to an expression, that can then be used multiple
|
||||
times within a folder.
|
||||
|
|
|
|||
|
|
@ -9,11 +9,7 @@ description: |-
|
|||
|
||||
# JSON Configuration Syntax
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. Whilst HCL2
|
||||
supports JSON the JSON - JSON and the HCL2 - JSON have differents formats for
|
||||
Packer. HCL2 support for Packer is still in Beta. For the old-style stable
|
||||
configuration language see [template
|
||||
docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
Most Packer configurations are written in [the native HCL
|
||||
syntax](/docs/from-1.5/syntax), which is designed to be easy for humans to read and
|
||||
|
|
|
|||
|
|
@ -10,11 +10,7 @@ description: |-
|
|||
|
||||
# HCL Configuration Syntax
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. Please see the [Packer Issue
|
||||
Tracker](https://github.com/hashicorp/packer/issues/9176) for a list of
|
||||
supported features. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
Other pages in this section have described various configuration constructs
|
||||
that can appear in HCL. This page describes the lower-level syntax of the
|
||||
|
|
|
|||
|
|
@ -9,11 +9,7 @@ description: |-
|
|||
|
||||
# Input Variables
|
||||
|
||||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. Please see the [Packer Issue
|
||||
Tracker](https://github.com/hashicorp/packer/issues/9176) for a list of
|
||||
supported features. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
||||
|
||||
Input variables serve as parameters for a Packer build, allowing aspects of the
|
||||
build to be customized without altering the build's own source code.
|
||||
|
|
@ -155,15 +151,7 @@ documentation about the build, and so it should be written from the perspective
|
|||
of the user of the build rather than its maintainer. For commentary for build
|
||||
maintainers, use comments.
|
||||
|
||||
## Assigning Values to build Variables
|
||||
|
||||
When variables are declared in the build of your configuration, they can be set
|
||||
in a number of ways:
|
||||
|
||||
- Individually, with the `-var` command line option.
|
||||
- In variable definitions (`.pkrvars.hcl`) files, either specified on the
|
||||
command line or automatically loaded.
|
||||
- As environment variables.
|
||||
`@include 'from-1.5/variables/assignment.mdx'`
|
||||
|
||||
The following sections describe these options in more detail.
|
||||
|
||||
|
|
@ -285,40 +273,7 @@ precedence over earlier ones:
|
|||
~> **Important:** Variables with map and object values behave the same way as
|
||||
other variables: the last value found overrides the previous values.
|
||||
|
||||
### A variable value must be known:
|
||||
|
||||
Take the following variable for example:
|
||||
|
||||
```hcl
|
||||
variable "foo" {
|
||||
type = string
|
||||
```
|
||||
|
||||
Here `foo` must have a known value but you can default it to `null` to make
|
||||
this behavior optional :
|
||||
|
||||
| | no default | `default = null` | `default = "xy"` |
|
||||
| :---------------------------: | :--------------------------: | :--------------: | :--------------: |
|
||||
| foo unused | error, "foo needs to be set" | - | - |
|
||||
| var.foo | error, "foo needs to be set" | null¹ | xy |
|
||||
| `PKR_VAR_foo=yz`<br />var.foo | yz | yz | yz |
|
||||
| `-var foo=yz`<br />var.foo | yz | yz | yz |
|
||||
|
||||
1: Null is a valid value. Packer will only error when the receiving field needs
|
||||
a value, example:
|
||||
|
||||
```hcl
|
||||
variable "example" {
|
||||
type = string
|
||||
default = null
|
||||
}
|
||||
|
||||
source "example" "foo" {
|
||||
arg = var.example
|
||||
}
|
||||
```
|
||||
|
||||
In the above case, as long as "arg" is optional for an "example" source, there is no error and arg won’t be set.
|
||||
`@include 'from-1.5/variables/must-be-set.mdx'`
|
||||
|
||||
### Setting an unknown variable will not always fail:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,10 +5,6 @@
|
|||
- [packer-builder-arm-image](https://github.com/solo-io/packer-builder-arm-image) - simple builder lets you extend on existing system images.
|
||||
- [packer-builder-arm](https://github.com/mkaczanowski/packer-builder-arm) - flexible builder lets you extend or build images from scratch with variety of options (ie. custom partition table).
|
||||
|
||||
- [vSphere builder](https://github.com/jetbrains-infra/packer-builder-vsphere) -
|
||||
A builder for interacting directly with the vSphere API rather than the esx
|
||||
host directly.
|
||||
|
||||
- [Vultr builder](https://github.com/vultr/packer-builder-vultr) - A builder
|
||||
for creating [Vultr](https://www.vultr.com/) snapshots.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
-> **Note:** This page is about HCL2 in Packer 1.5 and later. HCL2 support for
|
||||
Packer is still in Beta. Please see the [Packer Issue
|
||||
Tracker](https://github.com/hashicorp/packer/issues/9176) for a list of
|
||||
supported features. For the old-style stable configuration language see
|
||||
[template docs](/docs/templates).
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
```hcl
|
||||
# build.pkr.hcl
|
||||
build {
|
||||
|
||||
sources = [
|
||||
# use the plural `sources` block to simply use sources
|
||||
# without changing any field.
|
||||
"source.amazon-ebs.example",
|
||||
]
|
||||
|
||||
source "source.amazon-ebs.example" {
|
||||
# Use the singular `source` block set
|
||||
# specific fields.
|
||||
# Note that values cannot be overwritten.
|
||||
output = "different value"
|
||||
name = var.foo
|
||||
}
|
||||
|
||||
provisioner "shell-local" {
|
||||
inline = ["echo Hello World"]
|
||||
}
|
||||
|
||||
post-processor "shell-local" {
|
||||
inline = ["echo Hello World"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
```hcl
|
||||
# locals.pkr.hcl
|
||||
locals {
|
||||
baz = "Foo is '${var.foo}'"
|
||||
wee = local.baz
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
```hcl
|
||||
# sources.pkr.hcl
|
||||
source "amazon-ebs" "example" {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
## Assigning Values to build Variables
|
||||
|
||||
When variables are declared in the build of your configuration, they can be set
|
||||
in a number of ways:
|
||||
|
||||
- Individually, with the `-var foo=bar` command line option.
|
||||
- In variable definitions (`.pkrvars.hcl`) files, either specified on the
|
||||
command line or automatically loaded.
|
||||
- As environment variables, for example: `PKR_VAR_foo=bar`
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
```hcl
|
||||
# variables.pkr.hcl
|
||||
variable "foo" {
|
||||
type = string
|
||||
default = "the default value of the `foo` variable"
|
||||
description = "description of the `foo` variable"
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
```hcl
|
||||
# foo.pkrvars.hcl
|
||||
foo = "value"
|
||||
```
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
## A variable value must be known:
|
||||
|
||||
Take the following variable for example:
|
||||
|
||||
```hcl
|
||||
variable "foo" {
|
||||
type = string
|
||||
```
|
||||
|
||||
Here `foo` must have a known value but you can default it to `null` to make
|
||||
this behavior optional :
|
||||
|
||||
| | no default | `default = null` | `default = "xy"` |
|
||||
| :---------------------------: | :--------------------------: | :--------------: | :--------------: |
|
||||
| foo unused | error, "foo needs to be set" | - | - |
|
||||
| var.foo | error, "foo needs to be set" | null¹ | xy |
|
||||
| `PKR_VAR_foo=yz`<br />var.foo | yz | yz | yz |
|
||||
| `-var foo=yz`<br />var.foo | yz | yz | yz |
|
||||
|
||||
1: Null is a valid value. Packer will only error when the receiving field needs
|
||||
a value, example:
|
||||
|
||||
```hcl
|
||||
variable "example" {
|
||||
type = string
|
||||
default = null
|
||||
}
|
||||
|
||||
source "example" "foo" {
|
||||
arg = var.example
|
||||
}
|
||||
```
|
||||
|
||||
In the above case, as long as "arg" is optional for an "example" source, there is no error and arg won’t be set.
|
||||
Loading…
Reference in New Issue