diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 9afe6a4aa..3b29ceaa9 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -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: [ diff --git a/website/pages/docs/from-1.5/blocks/build/index.mdx b/website/pages/docs/from-1.5/blocks/build/index.mdx new file mode 100644 index 000000000..3ea9fe004 --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/build/index.mdx @@ -0,0 +1,27 @@ +--- +description: > + Something + + Something +layout: docs +page_title: build - Blocks +sidebar_title: build +--- + +# 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). \ No newline at end of file diff --git a/website/pages/docs/from-1.5/blocks/build/post-processor.mdx b/website/pages/docs/from-1.5/blocks/build/post-processor.mdx new file mode 100644 index 000000000..8586d28ca --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/build/post-processor.mdx @@ -0,0 +1,31 @@ +--- +description: > + Something + + Something +layout: docs +page_title: post-processor - build - Blocks +sidebar_title: post-processor +--- + +# 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. \ No newline at end of file diff --git a/website/pages/docs/from-1.5/blocks/build/provisioner.mdx b/website/pages/docs/from-1.5/blocks/build/provisioner.mdx new file mode 100644 index 000000000..940cfd405 --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/build/provisioner.mdx @@ -0,0 +1,35 @@ +--- +description: > + Something + + Something +layout: docs +page_title: provisioner - build - Blocks +sidebar_title: provisioner +--- + +# 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. \ No newline at end of file diff --git a/website/pages/docs/from-1.5/blocks/build/source.mdx b/website/pages/docs/from-1.5/blocks/build/source.mdx new file mode 100644 index 000000000..9d2b04f39 --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/build/source.mdx @@ -0,0 +1,30 @@ +--- +description: > + Something + + Something +layout: docs +page_title: source - build - Blocks +sidebar_title: source +--- + +# 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. \ No newline at end of file diff --git a/website/pages/docs/from-1.5/blocks/index.mdx b/website/pages/docs/from-1.5/blocks/index.mdx new file mode 100644 index 000000000..5b936b89c --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/index.mdx @@ -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'` + diff --git a/website/pages/docs/from-1.5/blocks/locals.mdx b/website/pages/docs/from-1.5/blocks/locals.mdx new file mode 100644 index 000000000..43d8027a8 --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/locals.mdx @@ -0,0 +1,19 @@ +--- +description: > + Something + + Something +layout: docs +page_title: locals - Blocks +sidebar_title: locals +--- + +# 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'` + diff --git a/website/pages/docs/from-1.5/blocks/source.mdx b/website/pages/docs/from-1.5/blocks/source.mdx new file mode 100644 index 000000000..dd599cfc5 --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/source.mdx @@ -0,0 +1,34 @@ +--- +description: > + Something + + Something +layout: docs +page_title: source - Blocks +sidebar_title: source +--- + +# 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. \ No newline at end of file diff --git a/website/pages/docs/from-1.5/blocks/variable.mdx b/website/pages/docs/from-1.5/blocks/variable.mdx new file mode 100644 index 000000000..d311a9441 --- /dev/null +++ b/website/pages/docs/from-1.5/blocks/variable.mdx @@ -0,0 +1,38 @@ +--- +description: > + Something + + Something +layout: docs +page_title: variable - Blocks +sidebar_title: variable +--- + +# 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. \ No newline at end of file diff --git a/website/pages/docs/from-1.5/expressions.mdx b/website/pages/docs/from-1.5/expressions.mdx index b7ecdf8d4..cd3ef307d 100644 --- a/website/pages/docs/from-1.5/expressions.mdx +++ b/website/pages/docs/from-1.5/expressions.mdx @@ -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 diff --git a/website/pages/docs/from-1.5/functions/index.mdx b/website/pages/docs/from-1.5/functions/index.mdx index 525f15fd2..acfa04087 100644 --- a/website/pages/docs/from-1.5/functions/index.mdx +++ b/website/pages/docs/from-1.5/functions/index.mdx @@ -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 diff --git a/website/pages/docs/from-1.5/index.mdx b/website/pages/docs/from-1.5/index.mdx index d2d218d37..e5fb91b29 100644 --- a/website/pages/docs/from-1.5/index.mdx +++ b/website/pages/docs/from-1.5/index.mdx @@ -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 diff --git a/website/pages/docs/from-1.5/locals.mdx b/website/pages/docs/from-1.5/locals.mdx index 2d2f45a3d..f482be743 100644 --- a/website/pages/docs/from-1.5/locals.mdx +++ b/website/pages/docs/from-1.5/locals.mdx @@ -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. diff --git a/website/pages/docs/from-1.5/syntax-json.mdx b/website/pages/docs/from-1.5/syntax-json.mdx index 0c43f668c..6232f6626 100644 --- a/website/pages/docs/from-1.5/syntax-json.mdx +++ b/website/pages/docs/from-1.5/syntax-json.mdx @@ -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 diff --git a/website/pages/docs/from-1.5/syntax.mdx b/website/pages/docs/from-1.5/syntax.mdx index 4f2eb8580..4465b389f 100644 --- a/website/pages/docs/from-1.5/syntax.mdx +++ b/website/pages/docs/from-1.5/syntax.mdx @@ -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 diff --git a/website/pages/docs/from-1.5/variables.mdx b/website/pages/docs/from-1.5/variables.mdx index 60f6214e8..f8ee0752f 100644 --- a/website/pages/docs/from-1.5/variables.mdx +++ b/website/pages/docs/from-1.5/variables.mdx @@ -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`
var.foo | yz | yz | yz | -| `-var foo=yz`
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: diff --git a/website/pages/partials/builders/community_builders.mdx b/website/pages/partials/builders/community_builders.mdx index ffd7c068c..79598629b 100644 --- a/website/pages/partials/builders/community_builders.mdx +++ b/website/pages/partials/builders/community_builders.mdx @@ -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. diff --git a/website/pages/partials/from-1.5/beta-hcl2-note.mdx b/website/pages/partials/from-1.5/beta-hcl2-note.mdx new file mode 100644 index 000000000..c9f996646 --- /dev/null +++ b/website/pages/partials/from-1.5/beta-hcl2-note.mdx @@ -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). \ No newline at end of file diff --git a/website/pages/partials/from-1.5/builds/example-block.mdx b/website/pages/partials/from-1.5/builds/example-block.mdx new file mode 100644 index 000000000..44824583a --- /dev/null +++ b/website/pages/partials/from-1.5/builds/example-block.mdx @@ -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"] + } +} +``` \ No newline at end of file diff --git a/website/pages/partials/from-1.5/locals/example-block.mdx b/website/pages/partials/from-1.5/locals/example-block.mdx new file mode 100644 index 000000000..6fb024088 --- /dev/null +++ b/website/pages/partials/from-1.5/locals/example-block.mdx @@ -0,0 +1,7 @@ +```hcl +# locals.pkr.hcl +locals { + baz = "Foo is '${var.foo}'" + wee = local.baz +} +``` \ No newline at end of file diff --git a/website/pages/partials/from-1.5/sources/example-block.mdx b/website/pages/partials/from-1.5/sources/example-block.mdx new file mode 100644 index 000000000..05b2c5012 --- /dev/null +++ b/website/pages/partials/from-1.5/sources/example-block.mdx @@ -0,0 +1,6 @@ +```hcl +# sources.pkr.hcl +source "amazon-ebs" "example" { + // ... +} +``` \ No newline at end of file diff --git a/website/pages/partials/from-1.5/variables/assignment.mdx b/website/pages/partials/from-1.5/variables/assignment.mdx new file mode 100644 index 000000000..2c3ef9048 --- /dev/null +++ b/website/pages/partials/from-1.5/variables/assignment.mdx @@ -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` \ No newline at end of file diff --git a/website/pages/partials/from-1.5/variables/foo-block.mdx b/website/pages/partials/from-1.5/variables/foo-block.mdx new file mode 100644 index 000000000..ca6601526 --- /dev/null +++ b/website/pages/partials/from-1.5/variables/foo-block.mdx @@ -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" +} +``` \ No newline at end of file diff --git a/website/pages/partials/from-1.5/variables/foo-pkrvar.mdx b/website/pages/partials/from-1.5/variables/foo-pkrvar.mdx new file mode 100644 index 000000000..04f44e1be --- /dev/null +++ b/website/pages/partials/from-1.5/variables/foo-pkrvar.mdx @@ -0,0 +1,4 @@ +```hcl +# foo.pkrvars.hcl +foo = "value" +``` diff --git a/website/pages/partials/from-1.5/variables/must-be-set.mdx b/website/pages/partials/from-1.5/variables/must-be-set.mdx new file mode 100644 index 000000000..1413aeab2 --- /dev/null +++ b/website/pages/partials/from-1.5/variables/must-be-set.mdx @@ -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`
var.foo | yz | yz | yz | +| `-var foo=yz`
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. \ No newline at end of file