diff --git a/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx b/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx index e374af650..7d208ab6b 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx @@ -1,13 +1,16 @@ --- description: > - The hcp_packer_registry allows operators the ability to customize the metadata sent to HCP Packer Registry. - It configures the base details of an image that is created or updated within HCP Packer. -page_title: hcp_packer_registry - build - Blocks + The `hcp_packer_registry` block configures details new or updated images in the HCP Packer registry. Learn how to configure the `hcp_packer_registry` block. +page_title: hcp_packer_registry block reference --- -# The `hcp_packer_registry` block +# `hcp_packer_registry` block -The `hcp_packer_registry` block lets you customize the metadata Packer sends to HCP Packer Registry. It configures the details of an image that is created or updated within the HCP Packer registry. +This topic provides reference information about the `hcp_packer_registry` block. + +## Description + +The `hcp_packer_registry` block configures details about an image Packer creates or updates in the HCP Packer registry. Use the `hcp_packer_registry` block to customize the metadata Packer sends to HCP Packer Registry. To get started with HCP Packer, refer to the [HCP Packer documentation](/hcp/docs/packer) or try the [Get Started with HCP Packer tutorials](/packer/tutorials/hcp-get-started). diff --git a/website/content/docs/templates/hcl_templates/blocks/build/index.mdx b/website/content/docs/templates/hcl_templates/blocks/build/index.mdx index 1ddef67ce..494d1d2c3 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/index.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/index.mdx @@ -1,15 +1,18 @@ --- description: | - The source block defines what builders are started. -page_title: build - Blocks + The `build` block contains instructions for Packer to follow during a build. Learn how to configure the `build` block in your Packer templates. +page_title: build block reference --- -# The `build` block +# `build` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `build` block. -The `build` block defines what builders are started, how to `provision` them -and if necessary what to do with their artifacts using `post-process`. + +## Description + +The `build` block specifies which builders Packer should run, how to provision them, +and any post-processing actions Packer should perform on the resulting artifacts. To use builders in a `build` block you can either: diff --git a/website/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx b/website/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx index 9f7e981c5..d3d0fc7ba 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx @@ -1,12 +1,14 @@ --- description: | - The post-processor block defines how a post-processor is configured. -page_title: post-processor - build - Blocks + The `post-processor` block defines post-processor behavior after a `packer build` command. Learn how to configure `post-processor` blocks in your Packer templates. +page_title: post-processor block reference --- -# The `post-processor` block +# `post-processor` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `post-processor` block. + +## Description The `post-processor` block defines how a post-processor is configured. diff --git a/website/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx b/website/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx index 181ac03a1..9ec491b3b 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx @@ -1,17 +1,16 @@ --- description: > - The post-processors block allows to define lists of post-processors to apply - to an artifact. -page_title: post-processors - build - Blocks + Add the `post-processors` block to a `build` block to define a list of post-processors to apply to an artifact. Learn how to configure nested `post-processors` blocks. +page_title: post-processors block reference --- -# The `post-processors` block +# `post-processors` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `post-processors` block. -The `post-processors` block allows to define lists of -[`post-processors`](/packer/docs/templates/hcl_templates/blocks/build/post-processor), that will run -from the artifact of each build. +## Description + +Add a `post-processors` block to your `build` block to include a list of [post-processor](/packer/docs/templates/hcl_templates/blocks/build/post-processor) configurations. Packer runs the post-processors for the artifact of each build. ```hcl # builds.pkr.hcl diff --git a/website/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx b/website/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx index fdf364830..7c19c1767 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx @@ -1,14 +1,20 @@ --- description: | - The provisioner block defines how a provisioner is configured. -page_title: provisioner - build - Blocks + The `provisioner` block defines how to configure a provisioner. Learn how to configure `provisioner` blocks in your templates. +page_title: provisioner block reference --- -# The `provisioner` block +# `provisioner` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic providers reference information about the `provisioner` block. -The `provisioner` block defines how a provisioner is configured. +## Description + +The `provisioner` block defines how to configure a provisioner. 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](/packer/docs/provisioners) section. ```hcl # builds.pkr.hcl @@ -23,12 +29,6 @@ build { } ``` -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](/packer/docs/provisioners) section. - ## Run on Specific Sources You can use the `only` or `except` configurations to run a provisioner only diff --git a/website/content/docs/templates/hcl_templates/blocks/build/source.mdx b/website/content/docs/templates/hcl_templates/blocks/build/source.mdx index 07663f8e3..e006dc924 100644 --- a/website/content/docs/templates/hcl_templates/blocks/build/source.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/build/source.mdx @@ -1,25 +1,25 @@ --- description: > - A source block nested in a build block allows you to use an already defined - source and to set specific fields which aren't already set in the top-level - source block. -page_title: source - build - Blocks + A `source` block nested in a `build` block reuses a builder defined + elsewhere in the configuration. Learn how to configure a nested `source` block. +page_title: source block reference --- -# The `source` block +# `source` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about `source` blocks nested in a `build` block. -A `source` block nested in a `build` block allows you to use an already defined -source and to "fill in" those fields _which aren't already set in the top-level -source block_. +## Description + +Add a `source` block to your `build` block to reuse a builder defined elsewhere in the configuration. Packer fills in the source fields that are not already set in the top-level `source` block. Build-level source blocks are implemented by merging their contents with the -corresponding top-level source block, and a packer build will fail when it +corresponding top-level source block, and a `packer build` command fails when it encounters the ambiguity that arises when a source parameter is defined twice. -For example, in the below example, if the top-level "lxd.arch" source block -also defined an `output_image` field (or if one of the build-level source blocks -redefined and image field), Packer would error. + +For example, in the below example, if the top-level `lxd.arch` source block +also defined an `output_image` field or if one of the build-level source blocks +redefined and image field, Packer would error. ```hcl # file: builds.pkr.hcl diff --git a/website/content/docs/templates/hcl_templates/blocks/data.mdx b/website/content/docs/templates/hcl_templates/blocks/data.mdx index b5a8e0f89..f503a5a9c 100644 --- a/website/content/docs/templates/hcl_templates/blocks/data.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/data.mdx @@ -1,16 +1,13 @@ --- description: > - The data block defines data sources within your Packer configuration. -page_title: data - Blocks + The `data` block defines data sources within your Packer configuration. Learn how to configure `data` blocks. +page_title: data block referenece --- -# The `data` block +# `data` block -The `data` block defines data sources within your Packer configuration. +The `data` block defines data sources within your Packer configuration. The following example instructs Packer to query the `amazon-ami` data source for information to use in the template. `@include 'from-1.5/datasources/example-block.mdx'` -# More on data sources - -- Read the [full Data Sources](/packer/docs/templates/hcl_templates/datasources) description for a more - thorough read. +Refer to [Data Sources](/packer/docs/templates/hcl_templates/datasources) for instructions about using the `data` block in your configuration. diff --git a/website/content/docs/templates/hcl_templates/blocks/index.mdx b/website/content/docs/templates/hcl_templates/blocks/index.mdx index 9d2cb2fae..3be0371c6 100644 --- a/website/content/docs/templates/hcl_templates/blocks/index.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/index.mdx @@ -1,16 +1,15 @@ --- -page_title: Blocks - Configuration Language -description: The HCL language has a number of blocks that can be used to configure builds. +page_title: Built-in blocks overview +description: A block is a container for configuration in a Packer template. Learn about the types of configration blocks built into HCL for Packer. --- -# Built-in Blocks +# Built-in blocks overview -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides an overview of the configuration blocks built into the Packer language that you can use to write Packer templates in HCL2. -The Packer - HCL2 language includes a number of built-in blocks that you can -use to configure builds. A block is a container for configuration. +## Introduction -The most important blocks can be broken into a couple of major types: +A block is a container for configuration. You can use the following types of blocks in your Packer templates: - `build` blocks contain configuration for a specific combination of builders, provisioners, and post-processors used to create a specific image artifact. @@ -29,8 +28,8 @@ The most important blocks can be broken into a couple of major types: The documentation contains information for each block type. -Other blocks, such as the "packer" block, provide information to the Packer core -about what version it is allowed to run. The "required_plugins" block helps the +Other blocks, such as the `packer` block, provide information to the Packer core +about what version it is allowed to run. The `required_plugins` block helps the Packer core Blocks can be defined in multiple files and `packer build folder` will build @@ -39,7 +38,7 @@ using solely the files from a directory named `folder`. Packer does not support user-defined blocks and so only the blocks built in to the language are available for use. The documentation includes all of the available built-in HCL2 blocks. -## Config example: +## Configuration examples `@include 'from-1.5/variables/foo-block.mdx'` diff --git a/website/content/docs/templates/hcl_templates/blocks/locals.mdx b/website/content/docs/templates/hcl_templates/blocks/locals.mdx index be45efb7e..07fecf813 100644 --- a/website/content/docs/templates/hcl_templates/blocks/locals.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/locals.mdx @@ -1,21 +1,22 @@ --- description: > - The locals block also called the local-variable block defines locals within - your Packer configuration. -page_title: locals - Blocks + The `locals` and `local-variable` blocks declare local variables in + your Packer configuration. Learn how to use these blocks to declare local variables in your template. +page_title: locals block reference --- -# The `locals` block +# `locals` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `locals` block. -The `locals` block, also called the `local-variable` block, defines locals within +## Description + +The `locals` and `local-variable` blocks declare local variables in your Packer configuration. `@include 'from-1.5/locals/example-block.mdx'` -# More on variables +Refer to the following topics for additional information about using the `locals` and `local-variable` blocks: -- Read the [full locals](/packer/docs/templates/hcl_templates/locals) description for a more - thorough read. -- Read the [variables guide](/packer/guides/hcl/variables) for more examples. +- [Local Variables](/packer/docs/templates/hcl_templates/locals) +- [Input Variables and local variables](/packer/guides/hcl/variables) diff --git a/website/content/docs/templates/hcl_templates/blocks/packer.mdx b/website/content/docs/templates/hcl_templates/blocks/packer.mdx index 27fbec5d0..fd5c7eb1f 100644 --- a/website/content/docs/templates/hcl_templates/blocks/packer.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/packer.mdx @@ -1,18 +1,16 @@ --- page_title: packer block reference description: |- - Configuration reference for the `packer` block in Packer templates written in HCL. + The `packer` block configures Packer behavior. Learn how to configure the `packer` in Packer templates written in HCL. --- -# Packer Settings +# `packer` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `packer` block. --> **Note:** The `packer` block is only available in Packer v1.6.5 and later. +## Description -The `packer` configuration block type is used to configure some -behaviors of Packer itself, such as the minimum required Packer version needed to -apply your configuration. +The `packer` block configures Packer version requirements and specifies which plugins to install upon initialization. ## Packer Block Syntax diff --git a/website/content/docs/templates/hcl_templates/blocks/source.mdx b/website/content/docs/templates/hcl_templates/blocks/source.mdx index d4b107080..d74254997 100644 --- a/website/content/docs/templates/hcl_templates/blocks/source.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/source.mdx @@ -1,24 +1,26 @@ --- description: | - The top-level source block defines reusable builder configuration blocks -page_title: source - Blocks + The `source` block defines reusable builder configuration blocks. Learn how to define reusable builders using the `source` block. +page_title: source block reference --- -# The `source` block +# `source` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic providers reference information about the `source` block. -The top-level `source` block defines reusable builder configuration blocks: +## Description + +The `source` block defines reusable builder configuration blocks. Builders are commonly used in custom plugins. + +## Example + +The following example defines a source for a builder type called `happycloud` with the name `foo`: `@include 'from-1.5/sources/example-block.mdx'` -The first label — `happycloud` here — is the builder type. The second label is -the unique name or identifier you want to give to the source. There can be only one -`source.happycloud.foo` top-level source block; but it can be used more than -once. Builders are usually found in plugins, except for the `file` and the -`null` builders that will remain in Packer core. +There is only one `source.happycloud.foo` top-level source block, but it can be used more than once. -You can start builders by referring to those source blocks from a [`build` +You can start builders by referring to `source` blocks from a [`build` block](/packer/docs/templates/hcl_templates/blocks/build) : ```hcl diff --git a/website/content/docs/templates/hcl_templates/blocks/variable.mdx b/website/content/docs/templates/hcl_templates/blocks/variable.mdx index 38b21aae6..8815035b1 100644 --- a/website/content/docs/templates/hcl_templates/blocks/variable.mdx +++ b/website/content/docs/templates/hcl_templates/blocks/variable.mdx @@ -1,17 +1,17 @@ --- description: > - The variable block, also called the input-variable block, defines variables - within your Packer configuration. -page_title: variable - Blocks + The `variable` and `input-variable` blocks define variables in your Packer configuration. Learn how to use these blocks to declare variables in your template. +page_title: variable block reference --- -# The `variable` block +# `variable` block -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `variable` block. -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](/packer/docs/templates/hcl_templates/blocks/locals) for that instead. +## Description + +The `variable` and `input-variable` blocks define variables +within your Packer configuration. You cannot use the `input-variable` block in another `input-variable` block. We recommend using the [`locals`](/packer/docs/templates/hcl_templates/blocks/locals) to nest variables instead. `@include 'from-1.5/variables/foo-block.mdx'`