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..5b6fac37c 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 specifies details for 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..23b4f7fc8 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 an artifact after 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'` diff --git a/website/content/docs/templates/hcl_templates/contextual-variables.mdx b/website/content/docs/templates/hcl_templates/contextual-variables.mdx index 03c04d82c..c6a6b4878 100644 --- a/website/content/docs/templates/hcl_templates/contextual-variables.mdx +++ b/website/content/docs/templates/hcl_templates/contextual-variables.mdx @@ -1,17 +1,16 @@ --- -page_title: Contextual Variables - HCL Configuration Language +page_title: Contextual variables reference description: >- - Special variables provide connection information and basic instance state - information. - - This page covers all existing special variables. + Source variables, build variables, and other special variables are context dependent. Learn about contextual variables that return connection and instance state information. --- -`@include 'from-1.5/beta-hcl2-note.mdx'` +# Contextual variables + +This topic provides reference information about special variables that return connection and basic instance state information based on the configuration context. `@include 'from-1.5/contextual-source-variables.mdx'` -# Build Variables +## Build Variables Build variables will allow you to access connection information and basic instance state information for a builder. All special build variables are stored in the `build` variable: @@ -86,7 +85,7 @@ For builder-specific builder variables, please also refer to the builder docs: The HCL2 Special Build Variables is in beta; please report any issues or requests on the Packer issue tracker on GitHub. -# Packer Version +## Packer Version This variable is set to the Packer version currently running. @@ -130,7 +129,7 @@ Make sure to wrap your variable in single quotes in order to escape the string that is returned; if you are running a dev version of packer the parenthesis may through off your shell escaping otherwise. -# HCP Packer Iteration ID +## HCP Packer Iteration ID ~> **Note**: The `packer.iterationID` variable is now deprecated and will be removed in a future version of Packer. HCP Packer Versions should be accessed with their fingerprint instead. The `packer.versionFingerprint` variable is now exposed to be used in its stead with the new HCP Packer data sources. @@ -176,7 +175,7 @@ build { mybuild.null.example: data is 01HN3KCRPVKR5PBQ28TS6B12W0 ``` -# HCP Packer Version Fingerprint +## HCP Packer Version Fingerprint If your build is pushing metadata to the HCP Packer registry, this variable is set to the value of the Version Fingerprint associated with this run. diff --git a/website/content/docs/templates/hcl_templates/datasources.mdx b/website/content/docs/templates/hcl_templates/datasources.mdx index 3a8878ff3..794841c3e 100644 --- a/website/content/docs/templates/hcl_templates/datasources.mdx +++ b/website/content/docs/templates/hcl_templates/datasources.mdx @@ -1,20 +1,15 @@ --- page_title: Data Sources description: >- - Data sources allow data to be fetched or computed for use elsewhere in local variables and - build sources configuration. Use of data sources - allows a Builder to make use of information defined outside of Packer. + A `data` block defines a data source that instructs Packer to query data defined outside of Packer for use in builds and sources. Learn how to configure `data` blocks to define data sources. --- -# Data Sources +# Data sources reference --> **Note:** Data Sources is a feature included in Packer 1.7 and later. +This topic describes how to use the `data` block to configure data sources in your HCL Packer templates. The `data` block instructs Packer to fetch or compute data for use in [`locals` blocks](/packer/docs/templates/hcl_templates/blocks/locals) and +[`source` blocks](/packer/docs/templates/hcl_templates/blocks/source) so that builders can use of information defined outside of Packer. -Data sources allow data to be fetched or computed for use elsewhere in [locals](/packer/docs/templates/hcl_templates/blocks/locals) and -[sources](/packer/docs/templates/hcl_templates/blocks/source) configuration. -Use of data sources allows a Builder to make use of information defined outside of Packer. - -# Using Data Sources +## Using data sources A data source is declared using a data block, and the configuration looks like the following: @@ -30,8 +25,8 @@ data "amazon-ami" "example" { } ``` -A data block requests that Packer read from a given data source ("amazon-ami") and export the result under the given -local name ("example"). The name is used to refer to this data source from elsewhere in the same Packer configuration. +A `data` block requests that Packer read from a given data source (`"amazon-ami"`) and export the result under the given +local name (`"example"`). The name is used to refer to this data source from elsewhere in the same Packer configuration. The data block creates a data instance of the given _type_ (first block label) and _name_ (second block label). The combination of the type and name must be unique within a configuration. @@ -75,7 +70,7 @@ source "amazon-ebs" "basic-example" { } ``` -## Known Limitations +## Known limitations `@include 'datasources/local-dependency-limitation.mdx'` diff --git a/website/content/docs/templates/hcl_templates/expressions.mdx b/website/content/docs/templates/hcl_templates/expressions.mdx index 22b38b24f..7c737792f 100644 --- a/website/content/docs/templates/hcl_templates/expressions.mdx +++ b/website/content/docs/templates/hcl_templates/expressions.mdx @@ -1,13 +1,14 @@ --- -page_title: Expressions - Configuration Language +page_title: HCL expressions reference description: |- - HCL allows the use of expressions to access data exported - by sources and to transform and combine that data to produce other values. + HCL expresssions provide access to data exported by data sources and transforms and combines the data into other values. Learn how to use HCL expressions in Packer templates. --- -# Expressions +# HCL expressions reference -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about expressions you can use in HCL templates for Packer. + +## Introduction _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/content/docs/templates/hcl_templates/index.mdx b/website/content/docs/templates/hcl_templates/index.mdx index 72d845f8f..0bffa7622 100644 --- a/website/content/docs/templates/hcl_templates/index.mdx +++ b/website/content/docs/templates/hcl_templates/index.mdx @@ -1,20 +1,16 @@ --- -page_title: HCL Templates +page_title: HCL templates overview description: |- - Packer uses text files to describe infrastructure and to set variables. - These text files are called Packer _configurations_ and are - written in the HCL2 HashiCorp Configuration Language. + HCL templates are configuration files that describe infrastructure and set variables using HashiCorp configuration language (HCL). Learn about HCL templates for Packer. --- -# HCL Configuration Language +# HCL templates overview -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides overview information about HashiCorp configuration language (HCL) templates for Packer. -Packer uses the HashiCorp Configuration Language - HCL - designed to allow -concise descriptions of the required steps to get to a build file. 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](/packer/guides/hcl). +## Introduction + +Packer reads and applies configurations defined in HCL template files. HCL templates provide concise descriptions of the required steps to get to a build file. You can add arguments, blocks, and expressions to your HCL templates to define your build as code. Refer to [Introduction to Packer HCL2](/packer/guides/hcl) for additional information. ## Builds @@ -28,7 +24,7 @@ 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 +## Arguments, blocks, and expressions The syntax of the HCL language consists of only a few basic elements: @@ -58,7 +54,7 @@ For full details about Packer's syntax, see: - [Configuration Syntax](/packer/docs/templates/hcl_templates/syntax) - [Expressions](/packer/docs/templates/hcl_templates/expressions) -## Code Organization +## 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 @@ -69,7 +65,7 @@ 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 +## 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 diff --git a/website/content/docs/templates/hcl_templates/locals.mdx b/website/content/docs/templates/hcl_templates/locals.mdx index 456f6af90..794088022 100644 --- a/website/content/docs/templates/hcl_templates/locals.mdx +++ b/website/content/docs/templates/hcl_templates/locals.mdx @@ -1,30 +1,22 @@ --- -page_title: Local Variables - HCL Configuration Language +page_title: Local variables description: >- - Local variables assign a name to an expression that you can use multiple - times within a folder. + The `local` and `locals` blocks define local variables that assign a name to an expression. Learn how to configure local variables. --- -# Local Variables +# Local variables -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `local` and `locals` blocks, which define local variables that you can use in your Packer templates. To learn about input variables, refer to +[Input variables](/packer/docs/templates/hcl_templates/variables). -There are two kinds of variables in HCL Packer templates: Input variables, -sometimes simply called "variables", and Local variables, also known as -"locals". Input variables may have defaults, but those defaults can be -overridden using command line options, environment variables, or variable -definitions files. Local variables can not be overridden. - -This page is about local variables. To learn about input variables, see the -[input variables](/packer/docs/templates/hcl_templates/variables) page. +## Introduction Local variables assign a name to an expression, which you can use multiple times within a folder. The expression is evaluated at run time, and can reference input variables, other local variables, data sources, and HCL -functions. +functions. You cannot overwrite local variables. -Input variable and local variable usage are introduced in the [_Variables -Guide_](/packer/guides/hcl/variables). +Refer to [Input Variables and local variables](/packer/guides/hcl/variables) for additional information about variables in Packer. ## Examples @@ -126,7 +118,7 @@ _unrelated_ local variables in _separate_ blocks, and consider annotating each block with a comment describing any context common to all of the enclosed locals. -## Known Limitations +## Known limitations `@include 'datasources/local-dependency-limitation.mdx'` diff --git a/website/content/docs/templates/hcl_templates/onlyexcept.mdx b/website/content/docs/templates/hcl_templates/onlyexcept.mdx index 3aab1084c..3ca883265 100644 --- a/website/content/docs/templates/hcl_templates/onlyexcept.mdx +++ b/website/content/docs/templates/hcl_templates/onlyexcept.mdx @@ -1,21 +1,22 @@ --- -page_title: Only Except - HCL Configuration Language +page_title: only and except keywords reference description: >- - Only and Except can be used as a command line argument to selectively run - builds. Only and Except can also be used in a provisioner to not run it for a - source. + The `only` and `except` keywords are filters for Packer builds. Learn how to use `only` and `except` to selectively run provisioners and post-processors. --- -# Only and Except +# `only` and `except` keywords -`only` and `except` are keywords used to filter what runs in your Packer build, -they can be seen as a command line argument: +The `only` and `except` keywords are filters that let you selectively run provisioners and post-processors in your Packer build. You can use the keywords in your Packer templates and as flags on the Packer CLI. + +## Command line flags `@include 'commands/except.mdx'` `@include 'commands/only.mdx'` -They can also be seen in a template to run or skip provisioners and/or +## Templates + +You can add the `only` and `except` keywords to run or skip provisioners and post-processors for a specific source: ```hcl @@ -63,7 +64,7 @@ build { # amazon-ebs.third-example ``` -Note that cli arguments can be used with a glob operator, using the previous +Note that CLI arguments can be used with a glob operator, using the previous configuration: - `packer build -only 'my_build.*' dir`: will only run the builds in blocks diff --git a/website/content/docs/templates/hcl_templates/path-variables.mdx b/website/content/docs/templates/hcl_templates/path-variables.mdx index fb9b74def..420ff3af3 100644 --- a/website/content/docs/templates/hcl_templates/path-variables.mdx +++ b/website/content/docs/templates/hcl_templates/path-variables.mdx @@ -1,14 +1,17 @@ --- -page_title: Path Variables - HCL Configuration Language +page_title: Path variables reference description: |- - Special variables provide directory information. This page covers all path - variables. + Path variables are special variables that enable you to provide directory information. Learn how to use path variables in Packer templates. --- -`@include 'path/separator-note.mdx'` - # Path variables +This topic provides reference information about path variables for Packer templates written in HCL. + +## Description + +Use the following variables to build paths: + - `path.cwd`: the directory from where Packer was started. - `path.root`: the directory of the input HCL file or the input folder. @@ -23,7 +26,11 @@ locals { } ``` -## Related Functions +## Path separators + +`@include 'path/separator-note.mdx'` + +## Related functions - [`abspath`](/packer/docs/templates/hcl_templates/functions/file/abspath) takes a string containing a filesystem path and converts it to an absolute path. diff --git a/website/content/docs/templates/hcl_templates/syntax-json.mdx b/website/content/docs/templates/hcl_templates/syntax-json.mdx index 414f864a0..276f78433 100644 --- a/website/content/docs/templates/hcl_templates/syntax-json.mdx +++ b/website/content/docs/templates/hcl_templates/syntax-json.mdx @@ -1,21 +1,16 @@ --- -page_title: JSON Configuration Syntax - Configuration Language +page_title: JSON syntax reference description: |- - In addition to the native syntax that is most commonly used with Packer, - the HCL language can also be expressed in a JSON-compatible syntax. + A JSON configuration expresses HCL Packer templates as JSON-compatible syntax. Learn about the JSON syntax for creating HCL Packer templates. --- -# JSON Configuration Syntax +# JSON syntax reference -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the JSON syntax you can use to express HCL Packer templates as JSON. For information about the HCL syntax, refer to [HCL syntax reference](/packer/docs/templates/hcl_templates/syntax). -Most Packer configurations are written in [the native HCL -syntax](/packer/docs/templates/hcl_templates/syntax), which is designed to be easy for humans to read and -update. +## Introduction -Packer also supports an alternative syntax that is JSON-compatible. This -syntax is useful when generating portions of a configuration programmatically, -since existing JSON libraries can be used to prepare the generated +Packer supports templates written in JSON, which is useful when generating portions of a configuration programmatically. This is because you can use existing JSON libraries to prepare the generated configuration files. This syntax is not to be confused with the pre-version-1.5 "legacy" Packer diff --git a/website/content/docs/templates/hcl_templates/syntax.mdx b/website/content/docs/templates/hcl_templates/syntax.mdx index 7ed024eca..3cea5da64 100644 --- a/website/content/docs/templates/hcl_templates/syntax.mdx +++ b/website/content/docs/templates/hcl_templates/syntax.mdx @@ -1,27 +1,18 @@ --- -page_title: Syntax - Configuration Language +page_title: HCL syntax reference 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 syntax combines declarative structure with expressions into Packer templates. Learn how to use HCL syntax to define infrastructure as code. --- -# HCL Configuration Syntax +# HCL syntax reference -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the native HashiCorp configuration language (HCL) syntax you can use to create Packer templates. For information about HCL constructs in JSON, refer to the [JSON syntax reference](/packer/docs/templates/hcl_templates/syntax-json). -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. +## Introduction -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](/packer/docs/templates/hcl_templates/syntax-json), 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 +Learning the HCL syntax helps you understand the building blocks that Packer template constructs +are built from. HCL is a rich language designed to be easy for humans to read and write. +Otherwhich 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 diff --git a/website/content/docs/templates/hcl_templates/variables.mdx b/website/content/docs/templates/hcl_templates/variables.mdx index 4c8f856fa..169d9ed81 100644 --- a/website/content/docs/templates/hcl_templates/variables.mdx +++ b/website/content/docs/templates/hcl_templates/variables.mdx @@ -1,36 +1,19 @@ --- -page_title: Input Variables - HCL Configuration Language +page_title: Input variables reference description: |- Input variables are parameters for Packer modules. - This page covers configuration syntax for variables. + Learn how to use the input variable syntax for Packer templates written in HCL. --- # Input Variables -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about input variables in Packer templates. Refer to [Local Variables](/packer/docs/templates/hcl_templates/locals) for information about using local variables in Packer. -There are two kinds of variables in HCL Packer templates: Input variables, -sometimes simply called "variables", and Local variables, also known as -"locals". Input variables may have defaults, but those defaults can be -overridden using command line options, environment variables, or variable -definitions files. However, nothing can change the value of an input variable -after the initial override. +## Introduction -This page is about input variables. To learn about local variables, see the -[locals](/packer/docs/templates/hcl_templates/locals) page. +Input variables, sometimes referred to as variables or Packer variables, are the parameters for a Packer build. Input variables let you customize aspects of a build without altering the build's own source code. Some input variables have default values that you can override using command line options, environment variables, or variable definitions files. You cannot change the value of an input variable after the initial override. -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. - -Input variable and local variable usage are introduced in the [_Variables -Guide_](/packer/guides/hcl/variables). - --> **Note:** For brevity, input variables are often referred to as just -"variables" or "Packer variables" when it is clear from context what sort of -variable is being discussed. Other kinds of variables in Packer include -_environment variables_ (set by the shell where Packer runs) and _expression -variables_ (used to indirectly represent a value in an -[expression](/packer/docs/templates/hcl_templates/expressions)). +Refer to [Input Variables and local variables](/packer/guides/hcl/variables) for additional information. ## Declaring an Input Variable diff --git a/website/content/docs/templates/index.mdx b/website/content/docs/templates/index.mdx index b3c0ccd66..1eda88844 100644 --- a/website/content/docs/templates/index.mdx +++ b/website/content/docs/templates/index.mdx @@ -1,31 +1,26 @@ --- description: | - This section describes the configuration language used to create Packer - templates. -page_title: Templates + Packer templates are configuration files that determine Packer behavior. Learn about the Packer template configuration language. +page_title: Packer templates reference overview --- -# Packer Templates +# Packer templates reference overview -Packer's behavior is determined by the Packer template, which consists of a -series of declarations and commands for Packer to follow. This template tells -Packer what plugins (builders, provisioners, post-processors) to use, how to -configure each of those plugins, and what order to run them in. +This topic provides overview information about Packer templates, which are configuration files that determine Packer behavior. + +## Introduction + +A Packer template contains a series of declarations and commands for Packer to follow. Templates define the following instructions for Packer: + +- Which plugins, such as builders, provisioners, and post-processors to use +- How to configure the plugins +- In what order to run them The template contains flexible variable injection tools, as well as built-in functions to help you customize your builds. -Historically, Packer has used a JSON template for its configuration, but Packer -is transitioning to a new template configuration format that uses HCL2 -- the -same configuration language used by Terraform and HashiCorp's other products. -This format is more flexible, more modular, and more concise than the original -JSON template format. While the JSON format is still supported, certain -new features in the Packer core will only be implemented for the newer HCL -format. Please use the side bar to find documentation for the different -template formats. +## Template language -From version **1.7.0**, HCL2 becomes officially the preferred way to write Packer -configuration(s). +Packer supports templates written in [HCL2](/packer/docs/templates/hcl_templates) or [JSON](/packer/docs/templates/legacy_json_templates). Since v1.7.0, HCL2 is the official format for Packer configurations. -If you need help upgrading a JSON template to an HCL template, check -our upgrade guide [here](/packer/tutorials/configuration-language/hcl2-upgrade). +HCL2 is also the configuration language used in configurations for other HashiCorp products, such as Terraform. HCL is more flexible, modular, and concise than the JSON template format. Refer to [Upgrade Packer JSON template to HCL2](/packer/tutorials/configuration-language/hcl2-upgrade) for a tutorial on upgrading JSON templates to HCL templates. diff --git a/website/content/docs/templates/json_to_hcl.mdx b/website/content/docs/templates/json_to_hcl.mdx index 2be56685d..f6ff56531 100644 --- a/website/content/docs/templates/json_to_hcl.mdx +++ b/website/content/docs/templates/json_to_hcl.mdx @@ -1,20 +1,23 @@ --- description: | - This section highlights the differences between JSON and HCL2 templates and explains the parallels between the specifications. -page_title: JSON to HCL + Learn about the differences between JSON and HCL2 templates and how converting templates to HCL affects plugins. +page_title: Differences between HCL2 and JSON templates --- -# Packer templates +# Differences between HCL2 and JSON templates -Packer uses templates to orchestrate builds for one or more images. -In [legacy JSON templates](/packer/docs/templates/legacy_json_templates), you would declare a series of builders, provisioners and post-processors to build images. -In [HCL2 templates](/packer/docs/templates/hcl_templates), things are different, as the configuration language allows you to specify builders through sources, and weave them in build blocks. +This document explains the differences between JSON to HCL2 templates, including how converting JSON templates to HCL2 affects builder, provisioner, and post-processor behavior. -This document aims to explain the parallels between the two configuration template types, and what you -should expect when moving a template away from JSON to HCL2. +## Introduction + +Packer uses JSON or HCL2 templates to orchestrate builds for one or more artifacts. + +In [legacy JSON templates](/packer/docs/templates/legacy_json_templates), declare a series of builders, provisioners, and post-processors to build images. + +In [HCL2 templates](/packer/docs/templates/hcl_templates), you can specify builders through sources and collect them into build blocks. + +You can use the `packer hcl2_upgrade` command when converting your existing JSON templates to HCL2. Refer to the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) page for more information on its usage. -In addition to this document, you may find the `packer hcl2_upgrade` command useful when converting your existing JSON templates to HCL2. -Refer to the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) page for more information on its usage. ## Builders diff --git a/website/content/docs/templates/legacy_json_templates/builders.mdx b/website/content/docs/templates/legacy_json_templates/builders.mdx index 42d3afa15..4996d367e 100644 --- a/website/content/docs/templates/legacy_json_templates/builders.mdx +++ b/website/content/docs/templates/legacy_json_templates/builders.mdx @@ -1,20 +1,21 @@ --- description: > - Within the template, the builders section contains an array of all the - builders - - that Packer should use to generate machine images for the template. -page_title: Builders - Templates + The `builders` block contains builders that create machines and generate images. Learn how to configure the `builders` block in JSON templates for Packer. +page_title: builders reference for JSON templates --- +# `builders` reference for JSON templates + +This topic provides reference information about the `builders` block in JSON templates. + `@include 'from-1.5/legacy-json-warning.mdx'` -# Template Builders +## Introduction -Within the template, the builders section contains an array of all the builders +The `builders` block contains an array of all the builders that Packer should use to generate machine images for the template. -Builders are responsible for creating machines and generating images from them +Builders create machines and generate images from them for various platforms. For example, there are separate builders for EC2, VMware, VirtualBox, etc. Packer comes with many builders by default, and can also be extended to add new builders. diff --git a/website/content/docs/templates/legacy_json_templates/communicator.mdx b/website/content/docs/templates/legacy_json_templates/communicator.mdx index a1c32a9c6..59d4073e0 100644 --- a/website/content/docs/templates/legacy_json_templates/communicator.mdx +++ b/website/content/docs/templates/legacy_json_templates/communicator.mdx @@ -1,19 +1,19 @@ --- description: | - Communicators are the mechanism Packer uses to upload files, execute scripts, - etc. with the machine being created. -page_title: Communicators - Templates + Packer uses communicators to upload files, execute scripts, and perform actions on the machine it creates. Learn how to configure communicators in JSON templates. +page_title: Communicators reference for JSON templates --- -`@include 'from-1.5/legacy-json-warning.mdx'` +# Communicators reference for JSON templates + +This topic describes how to use communicators in Packer templates written in JSON format. -# Template Communicators +`@include 'from-1.5/legacy-json-warning.mdx'` -Communicators are the mechanism Packer uses to upload files, execute scripts, -etc. with the machine being created. +## Description -Communicators are configured within the -[builder](/packer/docs/templates/legacy_json_templates/builders) section. +Packer uses communicators to upload files, execute scripts, and perform other actions on the machine being created. Configure communicators in the +[`builder`](/packer/docs/templates/legacy_json_templates/builders) section. All communicators have the following options: diff --git a/website/content/docs/templates/legacy_json_templates/engine.mdx b/website/content/docs/templates/legacy_json_templates/engine.mdx index e603320c5..90c31813a 100644 --- a/website/content/docs/templates/legacy_json_templates/engine.mdx +++ b/website/content/docs/templates/legacy_json_templates/engine.mdx @@ -1,19 +1,21 @@ --- description: | - All strings within templates are processed by a common Packer templating - engine, where variables and functions can be used to modify the value of a - configuration parameter at runtime. -page_title: Template Engine - Templates + The JSON template engine processes strings in JSON templates. Learn how to use JSON template engine functions and variables. +page_title: JSON template engine reference --- -# Template Engine +# JSON template engine reference -All strings within templates are processed by a common Packer templating -engine, where variables and functions can be used to modify the value of a -configuration parameter at runtime. +This topic describes the Packer engine that processes JSON templates. `@include 'from-1.5/legacy-json-warning.mdx'` +## Description + +All strings within templates are processed by a common Packer templating +engine. The engine uses variables and functions to modify the value of a +configuration parameter at runtime. + The syntax of templates uses the following conventions: - Anything template related happens within double-braces: `{{ }}`. @@ -234,9 +236,9 @@ respectively. user variables. See the [user variable](/packer/docs/templates/legacy_json_templates/user-variables) documentation for more information on user variables. -# isotime Function Format Reference +## `isotime` Function Format Reference -The isotime template engine uses Go to generate timestamps. If you're +The `isotime` template engine uses Go to generate timestamps. If you're unfamiliar with Go, then the way you format the timestamp is going to feel a bit unusual compared to how you may be used to formatting datetime strings. @@ -331,7 +333,7 @@ _The values in parentheses are the abbreviated, or 24-hour clock values_ Note that "-0700" is always formatted into "+0000" because `isotime` is always UTC time. -# split Function Format Reference +## `split` Function Format Reference The function `split` takes an input string, a seperator string, and a numeric component value and returns the requested substring. @@ -370,13 +372,13 @@ this case, on the `fixed-string` value): } ``` -# replace Function Format Reference +## `replace` Function Format Reference -Here are some examples using the replace options: +Here are some examples using the `replace` options: ```liquid build_name = foo-bar-provider {{ replace_all "-" "/" build_name }} = foo/bar/provider {{ build_name | replace "-" "/" 1 }} = foo/bar-provider -``` +``` \ No newline at end of file diff --git a/website/content/docs/templates/legacy_json_templates/index.mdx b/website/content/docs/templates/legacy_json_templates/index.mdx index 3a01ca7a5..3c8247537 100644 --- a/website/content/docs/templates/legacy_json_templates/index.mdx +++ b/website/content/docs/templates/legacy_json_templates/index.mdx @@ -1,25 +1,20 @@ --- description: > - The JSON templates are JSON files that configure the various components - of Packer in order to create one or more machine images. Templates are - portable, static, and readable and writable by both humans and computers. - This has the added benefit of being able to not only create and modify - templates by hand, but also write scripts to dynamically create or modify - templates. -page_title: JSON Templates + JSON templates are files that configure the Packer components that create one or more machine images. Learn how to configure JSON templates. +page_title: JSON templates configuration reference --- +# JSON templates configuration reference + +This topic provides reference information for creating JSON templates for Packer. + `@include 'from-1.5/legacy-json-warning.mdx'` -# JSON Templates +## Introduction -These Packer templates are JSON files that configure the various components +You can create Packer templates as JSON files that configure the various components of Packer in order to create one or more machine images. Templates are portable, -static, and readable and writable by both humans and computers. - -Templates are given to commands such as `packer build`, which will take the -template and actually run the builds within it, producing any resulting machine -images. +static, and readable and writable by both humans and computers. Use the Packer CLI to run builds described in the template to produce any resulting machine images. ## JSON Template Structure diff --git a/website/content/docs/templates/legacy_json_templates/post-processors.mdx b/website/content/docs/templates/legacy_json_templates/post-processors.mdx index b694d8eb4..42645e4a4 100644 --- a/website/content/docs/templates/legacy_json_templates/post-processors.mdx +++ b/website/content/docs/templates/legacy_json_templates/post-processors.mdx @@ -1,27 +1,24 @@ --- description: | - The post-processor section within a template configures any post-processing - that will be done to images built by the builders. Examples of post-processing - would be compressing files, uploading artifacts, etc. -page_title: Post-Processors - Templates + The `post-processor` block defines actions to perform on images after Packer builds them. Learn how to configure the `post-processor` block in JSON templates. +page_title: post-processors reference for JSON templates --- +# `post-processors` reference for JSON templates + +This documentation describes how to configure a `post-processor` block in JSON +templates. Refer to the documentation for each post-processor type for their specific configuration options. + `@include 'from-1.5/legacy-json-warning.mdx'` -# Template Post-Processors +## Description -The post-processor section within a template configures any post-processing -that will be done to images built by the builders. Examples of post-processing -would be compressing files, uploading artifacts, etc. +The `post-processor` block defines additional actions to perform on the images built by the builders. For example, you can configure the `post-processor` to compress files and upload artifacts. Post-processors are _optional_. If no post-processors are defined within a template, then no post-processing will be done to the image. The resulting artifact of a build is just the image outputted by the builder. -This documentation page will cover how to configure a post-processor in a -template. The specific configuration options available for each post-processor, -however, must be referenced from the documentation for that specific -post-processor. Within a template, a section of post-processor definitions looks like this: diff --git a/website/content/docs/templates/legacy_json_templates/provisioners.mdx b/website/content/docs/templates/legacy_json_templates/provisioners.mdx index 5ecf66023..4374e5288 100644 --- a/website/content/docs/templates/legacy_json_templates/provisioners.mdx +++ b/website/content/docs/templates/legacy_json_templates/provisioners.mdx @@ -1,30 +1,22 @@ --- description: | - Within the template, the provisioners section contains an array of all the - provisioners that Packer should use to install and configure software within - running machines prior to turning them into machine images. -page_title: Provisioners - Templates + The `provisioners` block contains provisioners that Packer uses to install and configure software on machines. Learn how to configure provisioners in JSON templates. +page_title: provisioners reference for JSON templates --- -`@include 'from-1.5/legacy-json-warning.mdx'` +# `provisioners` reference for JSON templates + +This topic provides reference information about the `provisioners` block in JSON templates for Packer. Refer to the documentation for specific provisioner types to learn about their configuration options. -# Template Provisioners +`@include 'from-1.5/legacy-json-warning.mdx'` -Within the template, the provisioners section contains an array of all the -provisioners that Packer should use to install and configure software within -running machines prior to turning them into machine images. +## Description -Provisioners are _optional_. If no provisioners are defined within a template, -then no software other than the defaults will be installed within the resulting -machine images. This is not typical, however, since much of the value of Packer -is to produce multiple identical images of pre-configured software. +The `provisioners` block contains provisioners that Packer uses to install and configure software within running machines prior to turning them into machine images. -This documentation page will cover how to configure a provisioner in a -template. The specific configuration options available for each provisioner, -however, must be referenced from the documentation for that specific -provisioner. +Provisioners are optional. When you omit the `provisioners` block, Packer installs only the default software within the resulting machine images. -Within a template, a section of provisioner definitions looks like this: +Use the following syntax to add the `provisioners` block to your JSON template: ```json { diff --git a/website/content/docs/templates/legacy_json_templates/user-variables.mdx b/website/content/docs/templates/legacy_json_templates/user-variables.mdx index b3c00d620..bb809bb20 100644 --- a/website/content/docs/templates/legacy_json_templates/user-variables.mdx +++ b/website/content/docs/templates/legacy_json_templates/user-variables.mdx @@ -1,18 +1,18 @@ --- description: | - User variables allow your templates to be further configured with variables - from the command-line, environment variables, or files. This lets you - parameterize your templates so that you can keep secret tokens, - environment-specific data, and other types of information out of your - templates. This maximizes the portability and shareability of the template. -page_title: User Variables - Templates +The `variables` block contains parameterized values for your templates. Learn how to configure `variables` to improve a template's security, portability, and shareability. +page_title: variables reference for JSON templates --- +# `variables` reference for JSON templates + +This topic describes how to use user variables in Packer templates written in JSON. + `@include 'from-1.5/legacy-json-warning.mdx'` -# Template User Variables +## Description -User variables allow your templates to be further configured with variables +The `variables` block lets you further configure a template with variables from the command-line, environment variables, Vault, or files. This lets you parameterize your templates so that you can keep secret tokens, environment-specific data, and other types of information out of your @@ -68,7 +68,7 @@ User variables are used by calling the `{{user}}` function in the form of within the template: in builders, provisioners, _anywhere outside the `variables` section_. User variables are available globally within the rest of the template. -## Environment Variables +## Environment variables Environment variables can be used within your template using user variables. The `env` function is available _only_ within the default value of a user @@ -119,7 +119,7 @@ The configuration for consul (address, tokens, ...) must be specified as environment variables, as specified in the [Documentation](/consul/docs/commands#environment-variables). -## Vault Variables +## Vault variables Secrets can be read from [Vault](https://www.vaultproject.io/) and used within your template as user variables. the `vault` function is available _only_ @@ -188,14 +188,14 @@ The full list of available environment variables is: and detailed documentation for usage of each of those variables can be found [here](/vault/docs/commands#environment-variables). -## AWS Secrets Manager Variables +## AWS Secrets Manager variables Secrets can be read from [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) and used within your template as user variables. The `aws_secretsmanager` function is available _only_ within the default value of a user variable, allowing you to default a user variable to an AWS Secrets Manager secret. -### Plaintext Secrets +### Plaintext secrets ```json { @@ -209,7 +209,7 @@ In the example above it is assumed that the secret `globalpassword` is not stored as a key pair but as a single non-JSON string value. Which the `aws_secretsmanager` function will return as a raw string. -### Single Key Secrets +### Single key secrets ```json { @@ -223,7 +223,7 @@ In the example above it is assumed that only one key is stored in `sample/app/password` if there are multiple keys stored in it then you need to indicate the specific key you want to fetch as shown below. -### Multiple Key Secrets +### Multiple key secrets ```json { @@ -242,7 +242,7 @@ one of the following methods: - [Container Credentials](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) - [Instance Profile Credentials](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) -## Using array values +## Use array values Some templates call for array values. You can use template variables for these, too. For example, the `amazon-ebs` builder has a configuration parameter called @@ -277,13 +277,13 @@ by a `,`. For example: } ``` -## Setting Variables +## Set variables Now that we covered how to define and use user variables within a template, the next important point is how to actually set these variables. Packer exposes two methods for setting user variables: from the command line or from a file. -### From the Command Line +### CLI To set user variables from the command line, the `-var` flag is used as a parameter to `packer build` (and some other commands). Continuing our example @@ -307,7 +307,7 @@ your variables rather than single-quoting them. For example: `packer build -var "aws_secret_key=foo" template.json` -### From a File +### From file Variables can also be set from an external JSON file. The `-var-file` flag reads a file containing a key/value mapping of variables to values and sets @@ -354,7 +354,7 @@ Results in the following variables: | aws_access_key | foo | | aws_secret_key | baz | -# Sensitive Variables +## Sensitive variables If you use the environment to set a variable that is sensitive, you probably don't want that variable printed to the Packer logs. You can make sure that @@ -380,9 +380,9 @@ instances of "bar" and of whatever the value of "my_secret" is with ``. This allows you to be confident that you are not printing secrets in plaintext to our logs by accident. -# Recipes +## Recipes -## Making a provisioner step conditional on the value of a variable +### Make a provisioner step conditional on the value of a variable There is no specific syntax in Packer templates for making a provisioner step conditional, depending on the value of a variable. However, you may be able to @@ -397,7 +397,7 @@ example, here is how to make a `shell-local` provisioner only run if the } ``` -## Using HOME Variable +### Using HOME Variable In order to use `$HOME` variable, you can create a `home` variable in Packer: @@ -420,4 +420,4 @@ And this will be available to be used in the rest of the template, i.e.: } ] } -``` +``` \ No newline at end of file diff --git a/website/content/partials/from-1.5/contextual-source-variables.mdx b/website/content/partials/from-1.5/contextual-source-variables.mdx index db375ef70..c609a9ddb 100644 --- a/website/content/partials/from-1.5/contextual-source-variables.mdx +++ b/website/content/partials/from-1.5/contextual-source-variables.mdx @@ -1,7 +1,12 @@ -# Source Variables +## Source Variables -It is possible to access the `name` and `type` of your `source` from -provisioners and post-processors: +Use the following syntax to access the `name` and `type` of your `source` from provisioners and post-processors: + +``` +.. +``` + +The following example queries source names used in the build: ```hcl source "null" "first-example" { @@ -26,11 +31,11 @@ build { inline = ["echo ${source.name} and ${source.type}"] } } - -# This will echo something like: -# -# roles.null.consul: consul and null -# roles.null.nomad: nomad and null -# roles.null.vault: vault and null -# roles.null.first-example: first-example and null ``` + +The example returns the following values: + +- `roles.null.consul`: Returns `consul` and `null` +- `roles.null.nomad`: Returns `nomad` and `null` +- `roles.null.vault`: Returns `vault` and `null` +- `roles.null.first-example`: Returns `first-example` and `null` \ No newline at end of file diff --git a/website/content/partials/path/separator-note.mdx b/website/content/partials/path/separator-note.mdx index de383ccd3..f2483b463 100644 --- a/website/content/partials/path/separator-note.mdx +++ b/website/content/partials/path/separator-note.mdx @@ -1,6 +1,3 @@ -~> **Note:** If possible, try to always use a forward slash `/` as the path separator, -especially when dealing with relative paths. A backward slash `\` will work on -Windows and is the official Windows path separator, but when building from any -system that is not Windows, Packer will only treat slashes `/` as path -separators, and treat backslashes as plain text. Which could lead to pathing -errors. +Separate paths with a forward slash (`/`), especially when using relative paths in your configuration. +Windows uses backward slashes (`\`) to separate paths, but Packer only recognizes `/` as path +separators when it creates builds from any non-Windows system. Packer also treat backslashes as plain text, which could lead to errors. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index f832c4c19..0e4958dbc 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -667,7 +667,7 @@ "path": "templates/legacy_json_templates" }, { - "title": "Builders", + "title": "builders", "path": "templates/legacy_json_templates/builders" }, { @@ -679,15 +679,15 @@ "path": "templates/legacy_json_templates/engine" }, { - "title": "Post-Processors", + "title": "post-processors", "path": "templates/legacy_json_templates/post-processors" }, { - "title": "Provisioners", + "title": "provisioners", "path": "templates/legacy_json_templates/provisioners" }, { - "title": "User Variables", + "title": "variables", "path": "templates/legacy_json_templates/user-variables" } ]