diff --git a/content/packer/v1.10.x/content/community-plugins.mdx b/content/packer/v1.10.x/content/community-plugins.mdx
new file mode 100644
index 0000000000..fa245b73df
--- /dev/null
+++ b/content/packer/v1.10.x/content/community-plugins.mdx
@@ -0,0 +1,41 @@
+---
+page_title: Community vs HashiCorp Maintained Plugins
+description: Packer maintains these core plugins.
+---
+
+# HashiCorp Maintained Plugins
+
+The following plugins (i.e. Builders, Provisioners, and Post-Processors) are
+maintained by HashiCorp. Any plugins not on this list are maintained by the
+community, and not actively contributed to by HashiCorp, although they are
+still distributed with Packer. If you are interested in seeing features or
+bugfixes to these plugins, please consider making a pull request, or asking the
+HashiCorp maintainers for advice on how to get started contributing.
+
+## Builders
+
+- Amazon EC2
+- Azure
+- Docker
+- Google Cloud
+- VMware
+- VirtualBox
+
+## Provisioners
+
+- File
+- InSpec
+- PowerShell
+- Shell
+- Windows Restart
+- Windows Shell
+
+## Post-Processors
+
+- Amazon Import
+- Artifice
+- Docker
+- Local Shell
+- Manifest
+- Vagrant
+- Vagrant Cloud
diff --git a/content/packer/v1.10.x/content/docs/builders/community-supported.mdx b/content/packer/v1.10.x/content/docs/builders/community-supported.mdx
new file mode 100644
index 0000000000..6ce89fb856
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/builders/community-supported.mdx
@@ -0,0 +1,14 @@
+---
+description: |
+ Community-maintained builders are not part of the core Packer binary, but
+ can run alongside Packer with minimal extra effort.
+page_title: Community - Builders
+---
+
+# Community Builders
+
+The following builders are developed and maintained by various members of the
+Packer community, not by HashiCorp. For more information on how to use community
+builders, see our docs on [extending Packer](/packer/docs/plugins/creation).
+
+@include 'builders/community_builders.mdx'
diff --git a/content/packer/v1.10.x/content/docs/builders/custom.mdx b/content/packer/v1.10.x/content/docs/builders/custom.mdx
new file mode 100644
index 0000000000..4445cf03ad
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/builders/custom.mdx
@@ -0,0 +1,15 @@
+---
+description: |
+ Packer is extensible, allowing you to write new builders without having to
+ modify the core source code of Packer itself. Documentation for creating new
+ builders is covered in the custom builders page of the Packer plugin section.
+page_title: Custom - Builders
+---
+
+# Custom Builder
+
+Packer is extensible, allowing you to write new builders without having to
+modify the core source code of Packer itself. Documentation for creating new
+builders is covered in the [custom
+builders](/packer/docs/plugins/creation/custom-builders) page of the Packer plugin
+section.
diff --git a/content/packer/v1.10.x/content/docs/builders/file.mdx b/content/packer/v1.10.x/content/docs/builders/file.mdx
new file mode 100644
index 0000000000..55f73d9b61
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/builders/file.mdx
@@ -0,0 +1,76 @@
+---
+description: |
+ The file Packer builder is not really a builder, it just creates an artifact
+ from a file. It can be used to debug post-processors without incurring high
+ wait times.
+page_title: File - Builders
+---
+
+
+
+
+
+# File Builder
+
+Type: `file`
+Artifact BuilderId: `packer.file`
+
+The `file` Packer builder is not really a builder, it just creates an artifact
+from a file. It can be used to debug post-processors without incurring high
+wait times.
+
+## Basic Example
+
+Below is a fully functioning example. It create a file at `target` with the
+specified `content`.
+
+
+
+
+```json
+{
+ "type": "file",
+ "content": "Lorem ipsum dolor sit amet",
+ "target": "dummy_artifact"
+}
+```
+
+
+
+
+```hcl
+source "file" "basic-example" {
+ content = "Lorem ipsum dolor sit amet"
+ target = "dummy_artifact"
+}
+
+build {
+ sources = ["sources.file.basic-example"]
+}
+```
+
+
+
+
+## Configuration Reference
+
+Configuration options are organized below into two categories: required and
+optional. Within each category, the available options are alphabetized and
+described.
+
+Any [communicator](/packer/docs/templates/legacy_json_templates/communicator) defined is ignored.
+
+### Required:
+
+- `target` (string) - The path for the artifact file that will be created. If
+ the path contains directories that don't exist, Packer will create them, too.
+
+### Optional:
+
+You can only define one of `source` or `content`. If none of them is defined
+the artifact will be empty.
+
+- `source` (string) - The path for a file which will be copied as the
+ artifact.
+
+- `content` (string) - The content that will be put into the artifact.
diff --git a/content/packer/v1.10.x/content/docs/builders/index.mdx b/content/packer/v1.10.x/content/docs/builders/index.mdx
new file mode 100644
index 0000000000..f440105885
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/builders/index.mdx
@@ -0,0 +1,22 @@
+---
+description: |
+ Builders are responsible for creating machines and generating images from them
+ for various platforms.
+page_title: Builders
+---
+
+# Builders
+
+Builders create machines and generate images from those machines for various platforms. Packer also has some builders that perform helper tasks, like running provisioners.
+
+Packer has the following types of builders:
+
+- [Plugin](/packer/plugins): Each plugin has its own associated set of builders. For example, there are separate builders for EC2, VMware, VirtualBox, etc.
+- [File](/packer/docs/builders/file): The `file` builder creates an artifact from a file.
+- [Null](/packer/docs/builders/null): The `null` builder sets up an SSH connection and runs the provisioners.
+- [Custom](/packer/docs/plugins/creation/custom-builders): You can write new builders for new or existing platforms.
+- [Community-Supported](/packer/docs/builders/community-supported): The Packer community develops and maintains builders for several additional platforms.
+
+Refer to the [`source`](/packer/docs/templates/hcl_templates/blocks/source) block documentation to learn more about configuring builders in the Packer templating language.
+
+
diff --git a/content/packer/v1.10.x/content/docs/builders/null.mdx b/content/packer/v1.10.x/content/docs/builders/null.mdx
new file mode 100644
index 0000000000..2098fec67f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/builders/null.mdx
@@ -0,0 +1,61 @@
+---
+description: |
+ The null Packer builder is not really a builder, it just sets up an SSH
+ connection and runs the provisioners. It can be used to debug provisioners
+ without incurring high wait times. It does not create any kind of image or
+ artifact.
+page_title: Null - Builders
+---
+
+
+
+
+
+# Null Builder
+
+Type: `null`
+
+The `null` Packer builder is not really a builder, it just sets up an SSH
+connection and runs the provisioners. It can be used to debug provisioners
+without incurring high wait times. It does not create any kind of image or
+artifact.
+
+## Basic Example
+
+Below is a fully functioning example. It doesn't do anything useful, since no
+provisioners are defined, but it will connect to the specified host via ssh.
+
+
+
+
+```json
+{
+ "type": "null",
+ "ssh_host": "127.0.0.1",
+ "ssh_username": "foo",
+ "ssh_password": "bar"
+}
+```
+
+
+
+
+```hcl
+source "null" "basic-example" {
+ ssh_host = "127.0.0.1"
+ ssh_username = "foo"
+ ssh_password = "bar"
+}
+
+build {
+ sources = ["sources.null.basic-example"]
+}
+```
+
+
+
+
+## Configuration Reference
+
+The null builder has no configuration parameters other than the
+[communicator](/packer/docs/templates/legacy_json_templates/communicator) settings.
diff --git a/content/packer/v1.10.x/content/docs/commands/build.mdx b/content/packer/v1.10.x/content/docs/commands/build.mdx
new file mode 100644
index 0000000000..60c2f7c8d1
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/build.mdx
@@ -0,0 +1,68 @@
+---
+description: |
+ The `packer build` command takes a template and runs all the builds within it
+ in order to generate a set of artifacts. The various builds specified within a
+ template are executed in parallel, unless otherwise specified. And the
+ artifacts that are created will be outputted at the end of the build.
+page_title: packer build - Commands
+---
+
+# `build` Command
+
+The `packer build` command takes a template and runs all the builds within it
+in order to generate a set of artifacts. The various builds specified within a
+template are executed in parallel, unless otherwise specified. And the
+artifacts that are created will be outputted at the end of the build.
+
+## Options
+
+- `-color=false` - Disables colorized output. Enabled by default.
+
+- `-debug` - Disables parallelization and enables debug mode. Debug mode
+ flags the builders that they should output debugging information. The exact
+ behavior of debug mode is left to the builder. In general, builders usually
+ will stop between each step, waiting for keyboard input before continuing.
+ This will allow the user to inspect state and so on.
+
+`@include 'commands/except.mdx'`
+
+- `-force` - Forces a builder to run when artifacts from a previous build
+ prevent a build from running. The exact behavior of a forced build is left
+ to the builder. In general, a builder supporting the forced build will
+ remove the artifacts from the previous build. This will allow the user to
+ repeat a build without having to manually clean these artifacts beforehand.
+
+- `-on-error=cleanup` (default), `-on-error=abort`, `-on-error=ask`, `-on-error=run-cleanup-provisioner` -
+ Selects what to do when the build fails during provisioning. Please note that
+ this only affects the build during the provisioner run, not during the
+ post-processor run, because it is related to whether or not to keep the
+ instance running and related artifacts like generated SSH keys on the system
+ when a provisioner fails.
+
+ - `cleanup` cleans up after the previous steps, deleting temporary files and virtual machines.
+ - `abort` exits without any cleanup, which might require the next build to use `-force`.
+ - `ask` presents a prompt and waits for you to decide to clean up, abort, or retry
+ the failed step.
+ - `run-cleanup-provisioner` aborts and exits without any cleanup besides
+ the [error-cleanup-provisioner](/packer/docs/templates/legacy_json_templates/provisioners#on-error-provisioner) if one is defined.
+
+`@include 'commands/only.mdx'`
+
+- `-parallel-builds=N` - Limit the number of builds to run in parallel, 0
+ means no limit (defaults to 0).
+
+- `-timestamp-ui` - Enable prefixing of each ui output with an RFC3339
+ timestamp.
+
+- `-var` - Set a variable in your Packer template. This option can be used
+ multiple times. This is useful for setting version numbers for your build.
+
+- `-var-file` - Set template variables from a file.
+
+- `-warn-on-undeclared-var` - Setting this flag will yield a warning for each assignment within
+ a variable definitions file (*.pkrvars.hcl | *.pkrvars.json) that does not have an accompanying
+ variable block. This can occur when using a var-file that contains a large amount of unused variables
+ for a given HCL2 template. For HCL2 template builds defining a value for a variable in a var-file is
+ not enough on its own for Packer to function, as there also needs to be a variable block definition in
+ the template files `pkr.hcl` for the variable. By default `packer build` will not warn when a var-file
+ contains one or more undeclared variables.
diff --git a/content/packer/v1.10.x/content/docs/commands/console.mdx b/content/packer/v1.10.x/content/docs/commands/console.mdx
new file mode 100644
index 0000000000..f61a7a1bb6
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/console.mdx
@@ -0,0 +1,156 @@
+---
+description: |
+ The `packer console` command allows you to experiment with Packer variable
+ interpolations.
+page_title: packer console - Commands
+---
+
+# `console` Command
+
+The `packer console` command allows you to experiment with Packer variable
+interpolations. You may access variables in the Packer config you called the
+console with, or provide variables when you call console using the -var or
+-var-file command line options.
+
+~> **Note:** `console` is available from version 1.4.2 and above.
+
+~> **Note:** For HCL2 `console` is available from version 1.6.0 and above, use
+`packer console --config-type=hcl2` to try it without a config file. Go
+templating ( or `{{..}}` calls ) will not work in HCL2 mode.
+
+Type in the interpolation to test and hit `` to see the result.
+
+To exit the console, type "exit" and hit ``, or use Control-C.
+
+```shell-session
+$ packer console my_template.json
+```
+
+The full list of options that the console command will accept is visible in the
+help output, which can be seen via `packer console -h`.
+
+## Options
+
+- `-var` - Set a variable in your Packer template. This option can be used
+ multiple times. This is useful for setting version numbers for your build.
+ example: `-var "myvar=asdf"`
+
+- `-var-file` - Set template variables from a file.
+ example: `-var-file myvars.json`
+
+## REPL commands
+
+- `help` - displays help text for Packer console.
+
+- `exit` - exits the console
+
+- `variables` - prints a list of all variables read into the console from the
+ `-var` option, `-var-files` option, and template.
+
+## Usage Examples - repl session ( JSON )
+
+Let's say you launch a console using a Packer template `example_template.json`:
+
+```shell-session
+$ packer console example_template.json
+```
+
+You'll be dropped into a prompt that allows you to enter template functions and
+see how they're evaluated; for example, if the variable `myvar` is defined in
+your example_template's variable section:
+
+```json
+"variables":{
+ "myvar": "asdfasdf"
+},
+...
+```
+
+and you enter `` {{user `myvar`}} `` in the Packer console, you'll see the value of
+myvar:
+
+```shell-session
+> {{user `myvar`}}
+asdfasdf
+```
+
+From there you can test more complicated interpolations:
+
+```shell-session
+> {{user `myvar`}}-{{timestamp}}
+asdfasdf-1559854396
+```
+
+And when you're done using the console, just type "exit" or CTRL-C
+
+```shell-session
+> exit
+$
+```
+
+If you'd like to provide a variable or variable files, you'd do this:
+
+```shell-session
+$ packer console -var "myvar=fdsafdsa" -var-file myvars.json example_template.json
+```
+
+If you don't have specific variables or var files you want to test, and just
+want to experiment with a particular template engine, you can do so by simply
+calling `packer console` without a template file.
+
+## Usage Examples - piped commands ( JSON )
+
+If you'd like to just see a specific single interpolation without launching
+the REPL, you can do so by echoing and piping the string into the console
+command:
+
+```shell-session
+$ echo {{timestamp}} | packer console
+1559855090
+```
+
+## Usage Examples - repl session ( HCL2 )
+
+~> **Note:** For HCL2 `console` is available from version 1.6.0 and above, use
+`packer console --config-type=hcl2` to try it without a config file. Go
+templating ( or `{{..}}` calls ) will not work in HCL2 mode.
+
+Without a config file, `packer console` can be used to experiment with the
+expression syntax and [built-in functions](/packer/docs/templates/hcl_templates/functions).
+
+### Starting
+
+To start a session on a folder containing HCL2 config files, run:
+
+```shell-session
+packer console folder/
+```
+
+Because `folder/` is a folder Packer will start in HCL2 mode, you can also
+directly pass an HCL2 formatted config file:
+
+```shell-session
+packer console file.pkr.hcl
+```
+
+Because the file is suffixed with `.pkr.hcl` Packer will start in HCL2 mode.
+
+When you just want to play around without a config file you can set the
+`--config-type=hcl2` option and Packer will start in HCL2 mode:
+
+```shell-session
+packer console --config-type=hcl2
+```
+
+### Scripting
+
+The `packer console` command can be used in non-interactive scripts by piping
+newline-separated commands to it. Only the output from the final command is
+printed unless an error occurs earlier.
+
+For example:
+
+```shell-session
+$ echo "1 + 5" | packer console
+6
+```
diff --git a/content/packer/v1.10.x/content/docs/commands/fix.mdx b/content/packer/v1.10.x/content/docs/commands/fix.mdx
new file mode 100644
index 0000000000..a888660650
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/fix.mdx
@@ -0,0 +1,42 @@
+---
+description: |
+ The `packer fix` command takes a template and finds backwards incompatible
+ parts of it and brings it up to date so it can be used with the latest version
+ of Packer. After you update to a new Packer release, you should run the fix
+ command to make sure your templates work with the new release.
+page_title: packer fix - Commands
+---
+
+# `fix` Command
+
+-> **Note** This command is not available on HCL2 templates yet, it will be added when we need to introduce the first 'fix'.
+
+The `packer fix` command takes a template and finds backwards incompatible
+parts of it and brings it up to date so it can be used with the latest version
+of Packer. After you update to a new Packer release, you should run the fix
+command to make sure your templates work with the new release.
+
+The fix command will output the changed template to standard out, so you should
+redirect standard out using standard OS-specific techniques if you want to save it
+to a file. For example, on Linux systems, you may want to do this:
+
+```shell-session
+$ packer fix old.json > new.json
+```
+
+If fixing fails for any reason, the fix command will exit with a non-zero exit
+status. Error messages appear on standard error, so if you're redirecting
+output, you'll still see error messages.
+
+-> **Even when Packer fix doesn't do anything** to the template, the
+template will be outputted to standard out. Things such as configuration key
+ordering and indentation may be changed. The output format however, is
+pretty-printed for human readability.
+
+The full list of fixes that the fix command performs is visible in the help
+output, which can be seen via `packer fix -h`.
+
+## Options
+
+- `-validate=false` - Disables validation of the fixed template. True by
+ default.
diff --git a/content/packer/v1.10.x/content/docs/commands/fmt.mdx b/content/packer/v1.10.x/content/docs/commands/fmt.mdx
new file mode 100644
index 0000000000..d082f9afc7
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/fmt.mdx
@@ -0,0 +1,58 @@
+---
+description: |
+ The `packer fmt` Packer command is used to format HCL2
+ configuration files to a canonical format and style.
+page_title: packer fmt - Commands
+---
+
+# `fmt` Command
+
+The `packer fmt` Packer command is used to format HCL2 configuration files to
+a canonical format and style. JSON files (.json) are not modified. This command
+applies a subset of HCL language style conventions, along with other minor
+adjustments for readability.
+
+`packer fmt` will display the name of the configuration file(s) that need formatting,
+and write any formatted changes back to the original configuration file(s).
+
+Example usage:
+
+Check if configuration file(s) need to be formatted, but don't write the changes.
+
+```shell-session
+$ packer fmt -check .
+my-template.pkr.hcl
+
+```
+
+Format a configuration file, writing the changes back to the original file.
+
+```shell-session
+$ packer fmt my-template.pkr.hcl
+my-template.pkr.hcl
+
+```
+
+Format a configuration file, reading from stdin and writing to stdout.
+
+```shell-session
+$ packer fmt -
+
+// You can use pipes to combine this feature with other command line options
+$ cat my-template.pkr.hcl | packer fmt -
+```
+
+## Options
+
+- `-check` - Checks if the input is formatted. Exit status will be 0 if all
+ input is properly formatted and non-zero otherwise.
+
+- `-diff` - Display diffs of any formatting change
+
+- `-write=false` - Don't write formatting changes to source files
+ (always disabled if using -check)
+
+- `-` - read formatting changes from stdin and write them to stdout.
+
+- `recursive` Also process files in subdirectories. By default, only the
+ given directory (or current directory) is processed.
\ No newline at end of file
diff --git a/content/packer/v1.10.x/content/docs/commands/hcl2_upgrade.mdx b/content/packer/v1.10.x/content/docs/commands/hcl2_upgrade.mdx
new file mode 100644
index 0000000000..baaee637d5
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/hcl2_upgrade.mdx
@@ -0,0 +1,139 @@
+---
+description: |
+ The `packer hcl2_upgrade` Packer command is used to transpile a JSON
+ configuration template to its formatted HCL2 counterpart. The command will
+ return a zero exit status on success, and a non-zero exit status on failure.
+page_title: packer hcl2_upgrade - Commands
+---
+
+-> **Note:** This command is Beta, and currently being improved upon; do not
+hesitate [opening a new
+issue](https://github.com/hashicorp/packer/issues/new/choose) if you find
+something wrong.
+
+# `hcl2_upgrade` Command
+
+The `packer hcl2_upgrade` Packer command is used to transpile a JSON
+configuration template to it's formatted HCL2 counterpart. The command will
+return a zero exit status on success, and a non-zero exit status on failure.
+
+Example usage:
+
+```shell-session
+$ packer hcl2_upgrade my-template.json
+
+Successfully created my-template.json.pkr.hcl
+```
+
+## Upgrading variables file
+
+From **v1.7.1**, the `hcl2_upgrade` command can upgrade a variables file.
+
+
+
+
+```json
+{
+ "variables": {
+ "aws_region": null,
+ "aws_secondary_region": "{{ env `AWS_DEFAULT_REGION` }}",
+ "aws_secret_key": "",
+ "aws_access_key": ""
+ },
+ "sensitive-variables": ["aws_secret_key", "aws_access_key"]
+}
+```
+
+
+
+
+```hcl
+variable "aws_access_key" {
+ type = string
+ default = ""
+ sensitive = true
+}
+
+variable "aws_region" {
+ type = string
+}
+
+variable "aws_secondary_region" {
+ type = string
+ default = "${env("AWS_DEFAULT_REGION")}"
+}
+
+variable "aws_secret_key" {
+ type = string
+ default = ""
+ sensitive = true
+}
+```
+
+
+
+
+## Go template functions
+
+`hcl2_upgrade` will do its best to transform your Go _template calls_ to HCL2,
+here is the list of calls that should get transformed:
+
+- `` {{ user `my_var` }} `` becomes `${var.my_var}`.
+- `` {{ env `my_var` }} `` becomes `${var.my_var}`. Packer HCL2 supports
+ environment variables through input variables. See
+ [docs](/packer/docs/templates/hcl_templates/variables#environment-variables)
+ for more info.
+- `{{ timestamp }}` becomes `${local.timestamp}`, the local variable
+ will be created for all generated files.
+- `` {{ build `ID` }} `` becomes `${build.ID}`.
+
+The rest of the calls should remain Go template calls for now, this will be
+improved over time.
+
+-> **Note**: The `hcl2_upgrade` command does its best to transform template
+calls to their JSON counterpart, but it might fail. In that case the
+`hcl2_upgrade` command will simply output the local HCL2 block without
+transformation and with the error message in a comment. We are currently
+working on improving this part of the transformer.
+
+## Options
+
+- `-output-file` - Filename of the hcl2 generated template. Defaults to
+ JSON_TEMPLATE.pkr.hcl; for example, if the file is called
+ "packerparty.json", the default output-file is "packerparty.json.pkr.hcl".
+- `-with-annotations` - Adds helpful comments to the HCL template with
+ information about the generated HCL2 blocks.
+
+## User variables using other user variables
+
+Packer JSON recently started allowing using user variables from variables. In
+HCL2, input variables cannot use functions nor other variables and are
+virtually static, local variables must be used instead to craft more dynamic
+variables.
+
+For v1.7.0 and lower, `hcl2_upgrade` doesn't upgrade variables to local variables,
+and it is up to you to upgrade them manually. Upgrade to **v1.7.1** to let the command do it
+automatically for you.
+
+Here is an example of a local variable using a string input variables:
+
+```hcl
+variable "foo" {
+ default = "Hello,"
+}
+
+variable "bar" {
+ default = "World!"
+}
+
+locals {
+ baz = "${var.foo} ${var.bar}"
+}
+```
+
+## Upgrading templates that use third-party community plugins
+
+If your template references a plugin that is not bundled with the main Packer
+binary, you need to make sure that the [plugin is installed](/packer/docs/plugins#installing-plugins)
+or you will get an `unknown builder type` error. Packer needs to load the plugin
+to transpose the template.
diff --git a/content/packer/v1.10.x/content/docs/commands/index.mdx b/content/packer/v1.10.x/content/docs/commands/index.mdx
new file mode 100644
index 0000000000..bd2a8108d8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/index.mdx
@@ -0,0 +1,166 @@
+---
+description: |
+ Packer is controlled using a command-line interface. All interaction with
+ Packer is done via the `packer` tool. Like many other command-line tools, the
+ `packer` tool takes a subcommand to execute, and that subcommand may have
+ additional options as well. Subcommands are executed with `packer SUBCOMMAND`,
+ where "SUBCOMMAND" is the actual command you wish to execute.
+page_title: Commands
+---
+
+# Packer Commands (CLI)
+
+Packer is controlled using a command-line interface. All interaction with
+Packer is done via the `packer` tool. Like many other command-line tools, the
+`packer` tool takes a subcommand to execute, and that subcommand may have
+additional options as well. Subcommands are executed with `packer SUBCOMMAND`,
+where "SUBCOMMAND" is the actual command you wish to execute.
+
+If you run `packer` by itself, help will be displayed showing all available
+subcommands and a brief synopsis of what they do. In addition to this, you can
+run any `packer` command with the `-h` flag to output more detailed help for a
+specific subcommand.
+
+The documentation contains information about each subcommand.
+
+## Machine-Readable Output
+
+By default, the output of Packer is very human-readable. It uses nice
+formatting, spacing, and colors in order to make Packer a pleasure to use.
+However, Packer was built with automation in mind. To that end, Packer supports
+a fully machine-readable output setting, allowing you to use Packer in
+automated environments.
+
+Because the machine-readable output format was made with Unix tools in mind, it
+is `awk`/`sed`/`grep`/etc. friendly and provides a familiar interface without
+requiring you to learn a new format.
+
+### Enabling Machine-Readable Output
+
+The machine-readable output format can be enabled by passing the
+`-machine-readable` flag to any Packer command. This immediately enables all
+output to become machine-readable on stdout. Logging, if enabled, continues to
+appear on stderr. An example of the output is shown below:
+
+```shell-session
+$ packer -machine-readable version
+1498365963,,version,1.0.2
+1498365963,,version-prelease,
+1498365963,,version-commit,3ead2750b+CHANGES
+1498365963,,ui,say,Packer v1.0.2
+```
+
+The format will be covered in more detail later. But as you can see, the output
+immediately becomes machine-friendly. Try some other commands with the
+`-machine-readable` flag to see!
+
+~>; The `-machine-readable` flag is designed for automated environments and
+is mutually-exclusive with the `-debug` flag, which is designed for interactive
+environments.
+
+### Format for Machine-Readable Output
+
+The machine readable format is a line-oriented, comma-delimited text format.
+This makes it more convenient to parse using standard Unix tools such as `awk`
+or `grep` in addition to full programming languages like Ruby or Python.
+
+The format is:
+
+```text
+timestamp,target,type,data...
+```
+
+Each component is explained below:
+
+- `timestamp` is a Unix timestamp in UTC of when the message was printed.
+
+- `target` When you call `packer build` this can be either empty or
+ individual build names, e.g. `amazon-ebs`. It is normally empty when builds
+ are in progress, and the build name when artifacts of particular builds are
+ being referred to.
+
+- `type` is the type of machine-readable message being outputted. The two
+ most common `type`s are `ui` and `artifact`
+
+- `data` is zero or more comma-separated values associated with the prior
+ type. The exact amount and meaning of this data is type-dependent, so you
+ must read the documentation associated with the type to understand fully.
+
+Within the format, if data contains a comma, it is replaced with
+`%!(PACKER_COMMA)`. This was preferred over an escape character such as `\'`
+because it is more friendly to tools like `awk`.
+
+Newlines within the format are replaced with their respective standard escape
+sequence. Newlines become a literal `\n` within the output. Carriage returns
+become a literal `\r`.
+
+### Machine-Readable Message Types
+
+Here's an incomplete list of types you may see in the machine-readable output:
+
+You'll see these data types when you run `packer build`:
+
+- `ui`: this means that the information being provided is a human-readable
+ string that would be sent to stdout even if we aren't in machine-readable
+ mode. There are three "data" subtypes associated with this type:
+
+ - `say`: in a non-machine-readable format, this would be bolded. Normally
+ it is used for announcements about beginning new steps in the build
+ process
+
+ - `message`: the most commonly used message type, used for basic updates
+ during the build process.
+
+ - `error`: reserved for errors
+
+- `artifact-count`: This data type tells you how many artifacts a particular
+ build produced.
+
+- `artifact`: This data type tells you information about what Packer created
+ during its build. An example of output follows the pattern
+ `timestamp, buildname, artifact, artifact_number, key, value` where `key`
+ and `value` contain information about the artifact.
+
+ For example:
+
+ ```text
+ 1539967803,,ui,say,\n==> Builds finished. The artifacts of successful builds are:
+ 1539967803,amazon-ebs,artifact-count,2
+ 1539967803,amazon-ebs,artifact,0,builder-id,mitchellh.amazonebs
+ 1539967803,amazon-ebs,artifact,0,id,eu-west-1:ami-04d23aca8bdd36e30
+ 1539967803,amazon-ebs,artifact,0,string,AMIs were created:\neu-west-1: ami-04d23aca8bdd36e30\n
+ 1539967803,amazon-ebs,artifact,0,files-count,0
+ 1539967803,amazon-ebs,artifact,0,end
+ 1539967803,,ui,say,--> amazon-ebs: AMIs were created:\neu-west-1: ami-04d23aca8bdd36e30\n
+ 1539967803,amazon-ebs,artifact,1,builder-id,
+ 1539967803,amazon-ebs,artifact,1,id,
+ 1539967803,amazon-ebs,artifact,1,string,
+ 1539967803,amazon-ebs,artifact,1,files-count,0
+ 2018/10/19 09:50:03 waiting for all plugin processes to complete...
+ 1539967803,amazon-ebs,artifact,1,end
+ ```
+
+You'll see these data types when you run `packer version`:
+
+- `version`: what version of Packer is running
+
+- `version-prerelease`: Data will contain `dev` if version is prerelease, and
+ otherwise will be blank.
+
+- `version-commit`: The git hash for the commit that the branch of Packer is
+ currently on; most useful for Packer developers.
+
+## Autocompletion
+
+The `packer` command features opt-in subcommand autocompletion that you can
+enable for your shell with `packer -autocomplete-install`. After doing so, you
+can invoke a new shell and use the feature.
+
+For example, assume a tab is typed at the end of each prompt line:
+
+```shell-session
+$ packer p
+plugin build
+$ packer build -
+-color -debug -except -force -machine-readable -on-error -only -parallel -timestamp -var -var-file
+```
diff --git a/content/packer/v1.10.x/content/docs/commands/init.mdx b/content/packer/v1.10.x/content/docs/commands/init.mdx
new file mode 100644
index 0000000000..940751c5b6
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/init.mdx
@@ -0,0 +1,94 @@
+---
+description: |
+ The `packer init` Packer command is used to download Packer plugin binaries.
+page_title: packer init - Commands
+---
+
+# `init` Command
+
+-> **Note:** Packer init does not work with legacy JSON templates. You can
+upgrade your JSON config files to HCL using the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) command.
+
+-> **Note:** Packer init will only work with multi-component plugins -- that is
+plugins that are named `packer-plugin-*`. To install a single-component plugin --
+that is `packer-provisioner-*`, `packer-builder-*`, etc. -- nothing changes, you will
+have to [install the plugin manually](/packer/docs/plugins#installing-plugins).
+
+The `packer init` command is used to download Packer plugin binaries. This is
+the first command that should be executed when working with a new or existing
+template. This command is always safe to run multiple times. Though subsequent
+runs may give errors, this command will never delete anything.
+
+You should invoke `packer init` on either an HCL2 template, or a directory that contains
+at least a valid HCL2 template, and eventually other related dependencies like varfiles
+for example.
+
+Example:
+
+```sh
+$ ls .
+template.pkr.hcl varfile.pkrvars.pkr.hcl
+
+$ packer init template.pkr.hcl # You can invoke packer init on a single template in this case
+ # This works if the template is self-contained, but may fail if
+ # the template is meant to be built as a bundle of partials.
+
+$ packer init . # Alternatively, you can invoke packer init on a directory instead,
+ # which behaves the same in a configuration like this one, but if
+ # the target is a collection ofHCL2 templates, this is the
+ # preferred way to invoke it.
+```
+
+Packer does not currently have the notion of a state like Terraform has. In other words,
+currently `packer init` is only in charge of installing Packer plugins.
+
+Currently, `packer init` can only fetch binaries from public projects on **GitHub**. GitHub's public API, [limits the number of unauthenticated requests
+per hour one IP can
+do](https://docs.github.com/en/developers/apps/rate-limits-for-github-apps#normal-user-to-server-rate-limits).
+Packer will do its best to avoid hitting those limits and in an average local
+usage this should not be an issue. Otherwise you can set the
+`PACKER_GITHUB_API_TOKEN` env var in order to get more requests per hour. Go to
+your personal [access token page](https://github.com/settings/tokens) to
+generate a new token.
+
+`packer init` will list all installed plugins then download the latest versions
+for the ones that are missing.
+
+`packer init -upgrade` will try to get the latest versions for all plugins.
+
+Import a plugin using the [`required_plugin`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements)
+block :
+
+```hcl
+packer {
+ required_plugins {
+ happycloud = {
+ version = ">= 2.7.0"
+ source = "github.com/azr/happycloud"
+ }
+ }
+}
+```
+
+HashiCorp does not officially verify third party Packer plugins, plugins not under the HashiCorp namespace `hashicorp/*`; as with all community tools, please do your own due diligence when using a new tool.
+
+## Plugin Selection
+
+Plugin selection depends on the source and version constraints defined within the `required_plugins` block.
+For each of the required plugins Packer will query the source repository `github.com/azr/happycloud` whose fully qualified address
+is `https://github.com/azr/packer-plugin-happycloud` for a plugin matching the version constraints for the host operating system.
+
+Packer init will install the latest found version matching the version selection
+in the `required_plugins` section. Make sure to set a correct [version
+constraint
+string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints). The
+plugins will be installed in the [Plugin
+Directory](/packer/docs/configure#packer-s-plugin-directory).
+
+See [Installing Plugins](/packer/docs/plugins#installing-plugins) for more information on how plugin installation works.
+
+## Options
+
+- `-upgrade` - On top of installing missing plugins, update installed plugins to
+ the latest available version, if there is a new higher one. Note that this
+ still takes into consideration the version constraint of the config.
diff --git a/content/packer/v1.10.x/content/docs/commands/inspect.mdx b/content/packer/v1.10.x/content/docs/commands/inspect.mdx
new file mode 100644
index 0000000000..9cebe60c53
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/inspect.mdx
@@ -0,0 +1,62 @@
+---
+description: >
+ The `packer inspect` command takes a template and outputs the various
+
+ components a template defines. This can help you quickly learn about a
+ template
+
+ without having to dive into the HCL itself. The command will tell you things
+
+ like what variables a template accepts, the builders it defines, the
+
+ provisioners it defines and the order they'll run, and more.
+page_title: packer inspect - Commands
+---
+
+# `inspect` Command
+
+The `packer inspect` command takes a template and outputs the various
+components a template defines. This can help you quickly learn about a template
+without having to dive into the HCL itself. The command will tell you things
+like what variables a template accepts, the builders it defines, the
+provisioners it defines and the order they'll run, and more.
+
+This command is extra useful when used with [machine-readable
+output](/packer/docs/commands) enabled. The command outputs the components
+in a way that is parseable by machines.
+
+The command doesn't validate the actual configuration of the various components
+(that is what the `validate` command is for), but it will validate the syntax
+of your template by necessity.
+
+## Usage Example
+
+Given a basic template, here is an example of what the output might look like:
+
+```shell-session
+$ packer inspect template.pkr.hcl
+> input-variables:
+
+var.aws_access_key: ""
+var.aws_secret_key: ""
+
+> local-variables:
+
+> builds:
+
+ > :
+
+ sources:
+
+ amazon-ebs.foo
+ amazon-instance.bar
+ virtualbox-iso.basic
+
+ provisioners:
+
+ shell
+
+ post-processors:
+
+
+```
diff --git a/content/packer/v1.10.x/content/docs/commands/plugins/index.mdx b/content/packer/v1.10.x/content/docs/commands/plugins/index.mdx
new file mode 100644
index 0000000000..551cbff03b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/plugins/index.mdx
@@ -0,0 +1,30 @@
+---
+description: |
+ The "plugin" command groups subcommands for interacting with
+ Packer's plugin and the plugin catalog.
+page_title: plugins Command
+---
+
+# `plugins`
+
+The `plugins` command groups subcommands for interacting with Packers' plugins.
+
+```shell-session
+$ packer plugins -h
+Usage: packer plugins [options] [args]
+ This command groups subcommands for interacting with Packer plugins.
+
+Related but not under the "plugins" command :
+
+- "packer init " will install all plugins required by a config.
+
+Subcommands:
+ install Install latest Packer plugin [matching version constraint]
+ installed List all installed Packer plugin binaries
+ remove Remove Packer plugins [matching a version]
+ required List plugins required by a config
+```
+
+## Related
+
+- [`packer init`](/packer/docs/commands/init) will install all required plugins.
diff --git a/content/packer/v1.10.x/content/docs/commands/plugins/install.mdx b/content/packer/v1.10.x/content/docs/commands/plugins/install.mdx
new file mode 100644
index 0000000000..711bfc3469
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/plugins/install.mdx
@@ -0,0 +1,24 @@
+---
+description: |
+ The "plugins install" command can install a plugin at a version constraint.
+page_title: plugins Command
+---
+
+# `plugins install`
+
+The `plugins install` subcommand installs a Packer plugin at a version constraint
+
+```shell-session
+$ packer plugins install -h
+Usage: packer plugins install []
+
+ This command will install the most recent compatible Packer plugin matching
+ version constraint. When the version constraint is omitted, the most recent
+ version will be installed.
+
+ Ex: packer plugins install github.com/hashicorp/happycloud v1.2.3
+```
+
+## Related
+
+- [`packer init`](/packer/docs/commands/init) will install all required plugins.
diff --git a/content/packer/v1.10.x/content/docs/commands/plugins/installed.mdx b/content/packer/v1.10.x/content/docs/commands/plugins/installed.mdx
new file mode 100644
index 0000000000..164da29e07
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/plugins/installed.mdx
@@ -0,0 +1,21 @@
+---
+description: |
+ The "plugins installed" command will list installed plugins.
+page_title: plugins Command
+---
+
+# `plugins installed`
+
+The `plugins installed` subcommand lists installed Packer plugins
+
+```shell-session
+$ packer plugins installed -h
+Usage: packer plugins installed
+
+ This command lists all installed plugin binaries that match with the current
+ OS and architecture. Packer's API version will be ignored.
+```
+
+## Related
+
+- [`packer init`](/packer/docs/commands/init) will install all required plugins.
diff --git a/content/packer/v1.10.x/content/docs/commands/plugins/remove.mdx b/content/packer/v1.10.x/content/docs/commands/plugins/remove.mdx
new file mode 100644
index 0000000000..4a5ea6dbd5
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/plugins/remove.mdx
@@ -0,0 +1,24 @@
+---
+description: |
+ The "plugins remove" command can remove a plugin at a version constraint.
+page_title: plugins Command
+---
+
+# `plugins remove`
+
+The `plugins remove` subcommand removes a Packer plugin at a version constraint
+
+```shell-session
+$ packer plugins remove -h
+Usage: packer plugins remove []
+
+ This command will remove all Packer plugins matching the version constraint
+ for the current OS and architecture.
+ When the version is omitted all installed versions will be removed.
+
+ Ex: packer plugins remove github.com/hashicorp/happycloud v1.2.3
+```
+
+## Related
+
+- [`packer init`](/packer/docs/commands/init) will install all required plugins.
diff --git a/content/packer/v1.10.x/content/docs/commands/plugins/required.mdx b/content/packer/v1.10.x/content/docs/commands/plugins/required.mdx
new file mode 100644
index 0000000000..3852310879
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/plugins/required.mdx
@@ -0,0 +1,30 @@
+---
+description: |
+ The "plugins required" command lists all plugins required in a Packer configuration.
+page_title: plugins Command
+---
+
+# `plugins required`
+
+The `plugins required` command lists all plugins required by a Packer config and
+all the installed binaries that match the constraint. The first binary
+is the most up-to-date installed version and will be the one picked by Packer in a build.
+
+```shell-session
+$ packer plugins required -h
+Usage: packer plugins required
+
+ This command will list every Packer plugin required by a Packer config, in
+ packer.required_plugins blocks. All binaries matching the required version
+ constrain and the current OS and Architecture will be listed. The most recent
+ version (and the first of the list) will be the one picked by Packer during a
+ build.
+
+
+ Ex: packer plugins required require.pkr.hcl
+ Ex: packer plugins required path/to/folder/
+```
+
+## Related
+
+- [`packer init`](/packer/docs/commands/init) will install all required plugins.
diff --git a/content/packer/v1.10.x/content/docs/commands/validate.mdx b/content/packer/v1.10.x/content/docs/commands/validate.mdx
new file mode 100644
index 0000000000..0827f5b53c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/commands/validate.mdx
@@ -0,0 +1,73 @@
+---
+description: |
+ The `packer validate` Packer command is used to validate the syntax and
+ configuration of a template. The command will return a zero exit status on
+ success, and a non-zero exit status on failure. Additionally, if a template
+ doesn't validate, any error messages will be outputted.
+page_title: packer validate - Commands
+---
+
+# `validate` Command
+
+The `packer validate` Packer command is used to validate the syntax and
+configuration of a [template](/packer/docs/templates). The command will
+return a zero exit status on success, and a non-zero exit status on failure.
+Additionally, if a template doesn't validate, any error messages will be
+outputted.
+
+Example usage:
+
+```shell-session
+$ packer validate my-template.pkr.hcl
+Template validation failed. Errors are shown below.
+
+Errors validating build 'vmware'. 1 error(s) occurred:
+
+* Either a path or inline script must be specified.
+```
+
+## Options
+
+- `-syntax-only` - Only the syntax of the template is checked. The
+ configuration is not validated.
+
+- `-evaluate-datasources` - Evaluate all data sources when validating a template.
+ This is only valid on HCL2 templates, since JSON templates do not feature
+ datasources, this option will be ignored.
+
+ ~> **Warning:** Data sources may rely on external services for fetching data,
+ which can incur some costs at validation if the services being contacted are
+ billing per operation.
+
+- `-except=foo,bar,baz` - Validates all the builds except those with the
+ comma-separated names. In legacy JSON templates, build names default to the
+ types of their builders (e.g. `docker` or
+ `amazon-ebs` or `virtualbox-iso`), unless a specific `name` attribute is
+ specified within the configuration. In HCL2 templates, the "name" is the
+ source block's "name" label, unless an in-build source definition adds the
+ "name" configuration option.
+
+- `-no-warn-undeclared-var` - Silence warnings when the variable definition
+ file contains variable assignments for undeclared variables. This can occur
+ when using a var-file that contains a large amount of unused variables for a
+ given HCL2 template. For HCL2 template defining a value for a variable in a
+ var-file is not enough on its own for Packer to function, as there also needs
+ to be a variable block definition in the template files `pkr.hcl` for the
+ variable. By default `packer validate` will warn when a var-file contains one
+ or more undeclared variables.
+
+- `-only=foo,bar,baz` - Only validate the builds with the given comma-separated
+ names. In legacy JSON templates, build names default to the
+ types of their builders (e.g. `docker` or
+ `amazon-ebs` or `virtualbox-iso`), unless a specific `name` attribute is
+ specified within the configuration. In HCL2 templates, the "name" is the
+ source block's "name" label, unless an in-build source definition adds the
+ "name" configuration option.
+
+- `-machine-readable` Sets all output to become machine-readable on stdout.
+ Logging, if enabled, continues to appear on stderr.
+
+- `-var` - Set a variable in your Packer template. This option can be used
+ multiple times. This is useful for setting version numbers for your build.
+
+- `-var-file` - Set template variables from a file.
diff --git a/content/packer/v1.10.x/content/docs/communicators/index.mdx b/content/packer/v1.10.x/content/docs/communicators/index.mdx
new file mode 100644
index 0000000000..d6564fa4c8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/communicators/index.mdx
@@ -0,0 +1,30 @@
+---
+description: |
+ Communicators are the mechanism Packer uses to upload files, execute
+ scripts, etc. with the machine being created.
+page_title: Communicators
+---
+
+# Communicators
+
+Communicators are the mechanism Packer uses to upload files, execute scripts,
+etc. with the machine being created.
+
+Communicators are configured within the
+[builder](/packer/docs/templates/legacy_json_templates/builders) section. Packer currently supports
+three kinds of communicators:
+
+- `none` - No communicator will be used. If this is set, most provisioners
+ also can't be used.
+
+- [ssh](/packer/docs/communicators/ssh) - An SSH connection will be established to the machine. This is
+ usually the default.
+
+- [winrm](/packer/docs/communicators/winrm) - A WinRM connection will be established.
+
+In addition to the above, some builders have custom communicators they can use.
+For example, the Docker builder has a "docker" communicator that uses
+`docker exec` and `docker cp` to execute scripts and copy files.
+
+For more details on how to use each communicator, click the links above to be
+taken to each communicator's page.
diff --git a/content/packer/v1.10.x/content/docs/communicators/ssh.mdx b/content/packer/v1.10.x/content/docs/communicators/ssh.mdx
new file mode 100644
index 0000000000..f3b48e528b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/communicators/ssh.mdx
@@ -0,0 +1,82 @@
+---
+description: |
+ The SSH communicator uses SSH to upload files, execute scripts, etc. on
+ the machine being created.
+page_title: Communicators - SSH
+---
+
+# SSH Communicator
+
+Communicators are the mechanism Packer uses to upload files, execute scripts,
+etc. on the machine being created, and are configured within the
+[builder](/packer/docs/templates/legacy_json_templates/builders) section.
+
+The SSH communicator does this by using the SSH protocol. It is the default
+communicator for a majority of builders.
+
+If you have an SSH agent configured on the host running Packer, and SSH agent
+authentication is enabled in the communicator config, Packer will automatically
+forward the SSH agent to the remote host.
+
+## Getting Ready to Use the SSH Communicator
+
+The SSH communicator is the default communicator for a majority of builders, but
+depending on your builder it may not work "out of the box".
+
+If you are building from a cloud image (for example, building on Amazon), there
+is a good chance that your cloud provider has already preconfigured SSH on the
+image for you, meaning that all you have to do is configure the communicator in
+the Packer template.
+
+However, if you are building from a brand-new and unconfigured operating system
+image, you will almost always have to perform some extra work to configure SSH
+on the guest machine. For most operating system distributions, this work will
+be performed by a [boot command](/packer/plugins/builders/vmware/iso#boot-configuration)
+that references a file which provides answers to the normally-interactive
+questions you get asked when installing an operating system. The name of this
+file varies by operating system; some common examples are the "preseed" file
+required by Debian, the "kickstart" file required by CentOS or the
+"answer file", also known as the Autounattend.xml file, required by Windows.
+For simplicity's sake, we'll refer to this file as the "preseed" file in the
+rest of the documentation.
+
+If you are unfamiliar with how to use a preseed file for automatic
+bootstrapping of an image, please either take a look at our
+[quick guides](/packer/guides/automatic-operating-system-installs) to
+image bootstrapping, or research automatic configuration for your specific
+guest operating system. Knowing how to automatically initalize your operating
+system is critical for being able to successfully use Packer.
+
+## SSH Communicator
+
+The SSH communicator connects to the host via SSH. If you have an SSH agent
+configured on the host running Packer, and SSH agent authentication is enabled
+in the communicator config, Packer will automatically forward the SSH agent to
+the remote host.
+
+The SSH communicator has the following options:
+
+@include "packer-plugin-sdk/communicator/SSH-not-required.mdx"
+
+~> Note: SSH communicator options: `ssh_keypair_name`, `ssh_agent_auth`,
+`temporary_key_pair_name` and `ssh_private_key_file` are also supported by
+the communicator. But they may not be supported for every builder. Please check
+the builder specific documentation for additional SSH supported options.
+
+### SSH Communicator Details
+
+Packer will only use one authentication method, either `publickey` or if
+`ssh_password` is used packer will offer `password` and `keyboard-interactive`
+both sending the password. In other words Packer will not work with _sshd_
+configured with more than one configured authentication method using
+`AuthenticationMethods`.
+
+Packer supports the following MACs:
+
+- hmac-sha1
+- hmac-sha1-96
+- hmac-sha2-256
+- `hmac-sha2-256-etm@openssh.com`
+
+For more information on the ciphers that Packer supports, check the docs for
+the [ssh_ciphers](/packer/docs/communicators/ssh#ssh_ciphers) template option.
diff --git a/content/packer/v1.10.x/content/docs/communicators/winrm.mdx b/content/packer/v1.10.x/content/docs/communicators/winrm.mdx
new file mode 100644
index 0000000000..103637205a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/communicators/winrm.mdx
@@ -0,0 +1,197 @@
+---
+description: |
+ Communicators are the mechanism Packer uses to upload files, execute scripts,
+ etc. with the machine being created.
+page_title: Communicators - Templates
+---
+
+# WinRM Communicator
+
+Communicators are the mechanism Packer uses to upload files, execute scripts,
+etc. with the machine being created. The WinRM communicator uses the
+Windows Remote Management protocol to do this.
+
+## Getting Ready to Use the WinRM Communicator
+
+The WinRM communicator is not the default communicator, so you will always have
+to set the `"communicator": "winrm",` template option explicitly. In addition,
+you will almost always have to provide a pre-run script that enables and
+configures WinRM on the guest machine. This will generally be in the form of a
+PowerShell script or a batch file.
+
+If you are building from a brand-new and unconfigured operating system
+image, you will need to provide this pre-run script as part of your
+Autounattend.xml file, required by Windows for automatic operating system
+installation. If you are building in a cloud or from a pre-installed image, your
+method for providing this pre-run script will vary based on the builder. Please
+refer to each builder's documentation for more information on how to supply the
+winrm configuration script.
+
+If you are unfamiliar with how to use an autounattend file, take a look at our
+[quick guides](/packer/guides/automatic-operating-system-installs); knowing
+how to automatically initalize your operating system is critical for being able
+to successfully use Packer to build from an iso.
+
+## WinRM Communicator Options
+
+@include "packer-plugin-sdk/communicator/WinRM-not-required.mdx"
+
+## Examples
+
+### Basics of WinRM Connection
+
+Please note that WinRM is not a Packer-specific protocol. Microsoft has a great
+deal of documentation about WinRM. If you find after reading this guide that
+you are still not able to connect via WinRM, check the
+[Microsoft documentation](https://docs.microsoft.com/en-us/windows/win32/winrm/installation-and-configuration-for-windows-remote-management)
+to make sure there isn't anything you're missing.
+
+There are some steps that you will normally need to take in order for Packer
+to be able to connect via WinRM
+
+1. Set up a username and password that Packer to connect with.
+2. Make any necesary registry edits to enable remote execution
+ (and remote execution with elevated privileges, if needed)
+3. Start WinRM, setting any config needed for allowing basic auth
+4. Open ports 5985 and/or 5986 depending on how you're connecting
+5. launch WinRM and set it to automatically launch when the computer restarts
+6. If necessary, generate a self-signed certificate or provide a real certificate
+ to the WinRM listener.
+
+#### Configuring WinRM in VMware
+
+If you are configuring WinRM using an Autounattend.xml, the simplest way to set
+up WinRM is to put the configuration commands directly into the Autounattend
+file as shown [here](https://github.com/StefanScherer/packer-windows/blob/6e603e904e9b280eeb97f7eb542940a043954112/answer_files/2008_r2_core/Autounattend.xml#L157-L234)
+
+Instead of entering each line individually, you can also add a batch file to
+your autounattend that contains the commands for configuring winrm. Depending
+on your winrm setup, this could be a complex batch file, or a very simple one.
+
+Below is an example of how we would call a batch file from inside the
+Autounattend file.
+
+```xml
+
+ ...
+
+ cmd.exe /c a:\winrmConfig.bat
+ Configure WinRM
+ 3
+ true
+
+ ...
+
+```
+
+It is also possible to call PowerShell scripts in a similar manner.
+
+The winrmConfig.bat referenced above can be as simple as
+
+```powershell
+rem basic config for winrm
+cmd.exe /c winrm quickconfig -q
+
+rem allow unencrypted traffic, and configure auth to use basic username/password auth
+cmd.exe /c winrm set winrm/config/service @{AllowUnencrypted="true"}
+cmd.exe /c winrm set winrm/config/service/auth @{Basic="true"}
+
+rem update firewall rules to open the right port and to allow remote administration
+cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes
+
+rem restart winrm
+cmd.exe /c net stop winrm
+cmd.exe /c net start winrm
+```
+
+Please note that the above batch file is _extremely_ simplistic, and not secure.
+It is intended to be an example of the bare minimum configuration. Below, you'll
+find a more complicated example of a more secure WinRM configuration process.
+
+This batch file will only work for HTTP connections, not HTTPS, but will enable
+you to connect using only the username and password created earlier in the
+Autounattend file. The above batchfile will allow you to connect using a very
+simple Packer config:
+
+```json
+ "communicator": "winrm",
+ "winrm_username": "packeruser",
+ "winrm_password": "SecretPassword"
+```
+
+A more complex example of a PowerShell script used for configuration can be seen
+below.
+
+```powershell
+# A Packer config that works with this example would be:
+#
+#
+# "winrm_username": "Administrator",
+# "winrm_password": "SuperS3cr3t!!!",
+# "winrm_insecure": true,
+# "winrm_use_ssl": true
+#
+#
+
+# Create username and password
+net user Administrator SuperS3cr3t!!!
+wmic useraccount where "name='Administrator'" set PasswordExpires=FALSE
+
+Set-ExecutionPolicy Unrestricted -Scope LocalMachine -Force -ErrorAction Ignore
+
+# Don't set this before Set-ExecutionPolicy as it throws an error
+$ErrorActionPreference = "stop"
+
+# Remove HTTP listener
+Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse
+
+# Create a self-signed certificate to let ssl work
+$Cert = New-SelfSignedCertificate -CertstoreLocation Cert:\LocalMachine\My -DnsName "packer"
+New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $Cert.Thumbprint -Force
+
+# WinRM
+write-output "Setting up WinRM"
+write-host "(host) setting up WinRM"
+
+# Configure WinRM to allow unencrypted communication, and provide the
+# self-signed cert to the WinRM listener.
+cmd.exe /c winrm quickconfig -q
+cmd.exe /c winrm set "winrm/config/service" '@{AllowUnencrypted="true"}'
+cmd.exe /c winrm set "winrm/config/client" '@{AllowUnencrypted="true"}'
+cmd.exe /c winrm set "winrm/config/service/auth" '@{Basic="true"}'
+cmd.exe /c winrm set "winrm/config/client/auth" '@{Basic="true"}'
+cmd.exe /c winrm set "winrm/config/service/auth" '@{CredSSP="true"}'
+cmd.exe /c winrm set "winrm/config/listener?Address=*+Transport=HTTPS" "@{Port=`"5986`";Hostname=`"packer`";CertificateThumbprint=`"$($Cert.Thumbprint)`"}"
+
+# Make sure appropriate firewall port openings exist
+cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes
+cmd.exe /c netsh firewall add portopening TCP 5986 "Port 5986"
+
+# Restart WinRM, and set it so that it auto-launches on startup.
+cmd.exe /c net stop winrm
+cmd.exe /c sc config winrm start= auto
+cmd.exe /c net start winrm
+```
+
+Please note that having WinRM auto-launch on all start ups may not be the right
+choice for you, if you don't need the server to recieve WinRM connections in the
+future. Clean up after yourself and close unnecesary firewall ports at a final
+provisioning step to make sure your image is secure.
+
+#### Configuring WinRM in the Cloud
+
+Most clouds allow you to provide a configuration script that runs when the
+instance is launched. In AWS, this is the
+[user_data_file](/packer/plugins/builders/amazon/ebs#user_data_file). In Google
+Cloud, this is provided using the `windows-startup-script-cmd`
+[metadata](/packer/plugins/builders/googlecompute#metadata) tag.
+[Example](/packer/plugins/builders/googlecompute#windows-example)
+
+Essentially, these files are powershell or cmd scripts that configure winrm,
+without having to be wrapped in an Autounattend. Provide the script in the
+format requested by each cloud, and make sure you manually configure any
+firewall rules that the cloud doesn't allow you to manage internally. More
+specific details for each cloud can be found in the builder sections.
+
+The above examples will work in cloud prep too, but may be overkill depending on
+how much preconfiguration the cloud has done for you.
diff --git a/content/packer/v1.10.x/content/docs/community-tools.mdx b/content/packer/v1.10.x/content/docs/community-tools.mdx
new file mode 100644
index 0000000000..3a222f17a7
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/community-tools.mdx
@@ -0,0 +1,80 @@
+---
+page_title: Download Packer Community Projects
+description: >-
+ Packer has a vibrant community of contributors who have built a number of
+ great tools on top of Packer. There are also quite a few projects
+ demonstrating the power of Packer templates.
+---
+
+# Download Community Projects
+
+Packer has a vibrant community of contributors who have built a number of great
+tools on top of Packer. There are also quite a few projects demonstrating the
+power of Packer templates.
+
+## Third-Party plugins
+
+The plugins listed below have been built by the community of Packer users and
+vendors. These plugins are not officially tested nor officially maintained by
+HashiCorp, and are listed here in order to help users find them easily.
+
+To learn more about how to use community plugins, or how to build your own,
+check out the docs on [extending Packer](https://developer.hashicorp.com/packer/docs/plugins/install-plugins)
+
+If you have built a plugin and would like to add it to this community list,
+please make a pull request so that we can document your
+contribution here!
+
+@include "builders/community_builders.mdx"
+
+@include "provisioners/community_provisioners.mdx"
+
+@include "post-processors/community_post-processors.mdx"
+
+## Templates
+
+- [bento](https://github.com/chef/bento) - Packer templates for building minimal
+ Vagrant base boxes
+
+- [boxcutter](https://github.com/boxcutter) - Community-driven templates and
+ tools for creating cloud, virtual machines, containers and metal operating
+ system environments
+
+- [cbednarski/packer-ubuntu](https://github.com/cbednarski/packer-ubuntu) -
+ Ubuntu LTS Virtual Machines for Vagrant
+
+- [geerlingguy/packer-ubuntu-1604](https://github.com/geerlingguy/packer-ubuntu-1604)
+ \- Ubuntu 16.04 minimal Vagrant Box using Ansible provisioner
+
+- [jakobadam/packer-qemu-templates](https://github.com/jakobadam/packer-qemu-templates)
+ \- QEMU templates for various operating systems
+
+- [lucidone/baseliner](https://git.sr.ht/~lucidone/baseliner) - Example of using
+ QEMU + Ansible with Packer
+
+- [packer-build](https://github.com/tylert/packer-build) - Build fresh Debian
+ and Ubuntu virtual machine images for Vagrant, VirtualBox and QEMU
+
+- [packer-windows](https://github.com/joefitzgerald/packer-windows) - Windows
+ Packer Templates
+
+- [packer-baseboxes](https://github.com/taliesins/packer-baseboxes) - Templates
+ for Packer to build base boxes
+
+- [vmware-samples/packer-examples-for-vsphere](https://github.com/vmware-samples/packer-examples-for-vsphere) - Examples
+ to automate the creation of virtual machine images and their guest operating systems on VMware vSphere using HashiCorp Packer
+ and the Packer Plugin for VMware vSphere (vsphere-iso).
+
+- [Parallels/packer-examples](https://github.com/parallels/packer-examples) - Examples in how to use Packer with Parallels Desktop
+ to automate the creation of virtual machine images and their guest operating systems on macOS, windows and linux.
+
+## Wrappers
+
+- [packer-config](https://github.com/ianchesal/packer-config) - a Ruby model that lets you build Packer configurations in Ruby
+- [packerlicious](https://github.com/mayn/packerlicious) - a Python library for generating Packer templates
+- [packer.py](https://github.com/mayn/packer.py) - a Python library for executing Packer CLI commands
+- [racker](https://github.com/aspring/racker) - an opinionated Ruby DSL for generating Packer templates
+
+## Other
+
+- [suitcase](https://github.com/tmclaugh/suitcase) - Packer based build system for CentOS OS images
diff --git a/content/packer/v1.10.x/content/docs/configure.mdx b/content/packer/v1.10.x/content/docs/configure.mdx
new file mode 100644
index 0000000000..18eeb40939
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/configure.mdx
@@ -0,0 +1,146 @@
+---
+description: |
+ There are various ways to configure Packer. By default Packer will use known folders,
+ which can be changed by using environment variables.
+page_title: Configuring Packer
+---
+
+# Configuring Packer
+
+-> **Note:** There are a few configuration settings that affect Packer globally
+by configuring the core of Packer. These settings all have reasonable defaults,
+so you generally don't have to worry about it until you want to tweak a
+configuration. If you're just getting started with Packer, don't worry about
+core configuration for now.
+
+## Packer's config directory
+
+Packer's configuration directory can potentially contain plugins and internal
+Packer files. The Packer config directory will be looked up on the following paths:
+
+| Unix | Windows |
+| --------------------------- | --------------------------- |
+| `${HOME}/.config/packer/` | `%APPDATA%\packer.d\` |
+
+-> **Note:** On Unix systems, Packer defaults to using the XDG base directory specification.
+When the environment variable `PACKER_CONFIG_DIR` is unset or empty a default equal to `$HOME/.config/packer` should be used.
+In all other cases, where there is an existing older style `.packer.d` directory (e.g `$HOME/.packer.d/`) or PACKER_CONFIG_DIR is not empty
+the older configuration directory will be used.
+
+Examples:
+
+- On a Unix system, if the `$PACKER_CONFIG_DIR` environment variable is set to
+ `/home/packer`, the config directory will be: `/home/packer/.packer.d/` and
+ other values will not be checked.
+- On a Windows system, if the `PACKER_CONFIG_DIR` environment variable is set to `C:/`,the
+ config directory will be: `C:/packer.d/` and other values will not be checked.
+
+
+
+## Packer's config file (deprecated)
+
+Packer can optionally read a JSON file for the end user to set core settings.
+The config file of Packer will be looked up on the following paths:
+
+| Unix | Windows |
+| -------------------------------- | --------------------------------- |
+| `${PACKER_CONFIG}` | `%PACKER_CONFIG%` |
+| `${HOME}/.packerconfig` | `%APPDATA%\packer.config\` |
+
+The format of the configuration file is basic JSON.
+
+### Packer config file configuration Reference
+
+Below is the list of all available configuration parameters for the core
+configuration file. None of these are required, since all have defaults.
+
+- `plugin_min_port` and `plugin_max_port` (number) - These are the minimum
+ and maximum ports that Packer uses for communication with plugins, since
+ plugin communication happens over TCP connections on your local host. By
+ default these are 10,000 and 25,000, respectively. Be sure to set a fairly
+ wide range here, since Packer can easily use over 25 ports on a single run.
+
+- `builders`, `commands`, `post-processors`, and `provisioners` are objects
+ that are used to install plugins. The details of how exactly these are set is
+ covered in more detail in the [installing plugins documentation
+ page](/packer/docs/plugins/install-plugins). It is instead recommended to use [HCL2
+ `required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements)
+ and the [`packer init`](/packer/docs/commands/init) command to install plugins; if
+ you are using both, the `required_plugin` config will take precedence.
+
+## Packer's plugin directory
+
+@include "plugins/plugin-location.mdx"
+
+## Packer's cache directory
+
+Packer uses a cache directory to download large files and for logistics around
+large file download. By default, Packer caches things in the current directory,
+under: `./packer_cache/`. This can be changed by setting the `PACKER_CACHE_DIR`
+env var. It is recommended to share the same Packer cache directory across your
+builds if you have multiple builds doing similar things to avoid downloading the
+same ISO twice for example.
+
+## Environment Variables usable for Packer
+
+Packer uses a variety of environmental variables. A listing and description of
+each can be found below:
+
+- `PACKER_CACHE_DIR` - The location of the Packer cache. This defaults to
+ `./packer_cache/`. Relative paths can be used. Some plugins can cache large
+ files like ISOs in the cache dir.
+
+- `PACKER_CONFIG` - The location of the core configuration file. The format
+ of the configuration file is basic JSON. See [Packer's Config
+ file](#packer-s-config-file).
+
+- `PACKER_CONFIG_DIR` - The location for the home directory of Packer. See
+ [Packer's home directory](#packer-s-home-directory) for more.
+
+- `PACKER_GITHUB_API_TOKEN` - When using Packer init on HCL2 templates, Packer
+ queries the public API from Github which limits the amount of queries on can
+ set the `PACKER_GITHUB_API_TOKEN` with a Github Token to make it higher.
+
+- `PACKER_LOG` - Setting this to any value other than "" (empty string) or
+ "0" will enable the logger. See the [debugging
+ page](/packer/docs/debugging).
+
+- `PACKER_LOG_PATH` - The location of the log file. Note: `PACKER_LOG` must
+ be set for any logging to occur. See the [debugging
+ page](/packer/docs/debugging).
+
+- `PACKER_NO_COLOR` - Setting this to any value will disable color in the
+ terminal.
+
+- `PACKER_PLUGIN_MAX_PORT` - The maximum port that Packer uses for
+ communication with plugins, since plugin communication happens over TCP
+ connections on your local host. The default is 25,000. This can also be set
+ using the Packer's config file, see the [config file configuration
+ reference](#packer-config-file-configuration-reference) for more.
+
+- `PACKER_PLUGIN_MIN_PORT` - The minimum port that Packer uses for
+ communication with plugins, since plugin communication happens over TCP
+ connections on your local host. The default is 10,000. This can also be set
+ using the Packer's config file, see the [config file configuration
+ reference](#packer-config-file-configuration-reference) for more.
+
+- `PACKER_PLUGIN_PATH` - a PATH variable for finding third-party packer
+ plugins. For example: `~/custom-dir-1:~/custom-dir-2`. Separate directories in
+ the PATH string using a colon (`:`) on POSIX systems and a semicolon (`;`) on
+ Windows systems. The above example path would be able to find a provisioner
+ named `packer-provisioner-foo` in either
+ `~/custom-dir-1/packer-provisioner-foo` or
+ `~/custom-dir-2/packer-provisioner-foo`. See the documentation on [plugin
+ directories](#packer-s-plugin-directory) for more.
+
+- `CHECKPOINT_DISABLE` - When Packer is invoked it sometimes calls out to
+ [checkpoint.hashicorp.com](https://checkpoint.hashicorp.com/) to look for
+ new versions of Packer. If you want to disable this for security or privacy
+ reasons, you can set this environment variable to `1`.
+
+- `TMPDIR` (Unix) / `TMP` `TEMP` `USERPROFILE` (Windows) - The
+ location of the directory used for temporary files (defaults to `/tmp` on
+ Linux/Unix and `%USERPROFILE%\AppData\Local\Temp` on Windows Vista and above).
+ It might be necessary to customize it when working with large files since
+ `/tmp` is a memory-backed filesystem in some Linux distributions in which case
+ `/var/tmp` might be preferred.
diff --git a/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-artifact.mdx b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-artifact.mdx
new file mode 100644
index 0000000000..e0fc58c030
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-artifact.mdx
@@ -0,0 +1,105 @@
+---
+description: |
+ The HCP Packer Artifact Data Source retrieves information about an
+ artifact from the HCP Packer Registry. This information can be used to
+ provide a source artifact to various Packer builders.
+page_title: HCP Packer Artifact - Data Sources
+---
+
+
+
+
+
+
+# HCP Packer Artifact Data Source
+
+Type: `hcp-packer-artifact`
+
+The `HCP Packer Artifact` Data Source retrieves information about an
+artifact from the HCP Packer Registry. This information can be used to
+provide a source artifact to various Packer builders.
+
+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).
+
+~> **Note:** You will receive an error if you try to reference metadata from a deactivated or deleted registry.
+An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries
+with billing issues. Contact [HashiCorp Support](https://support.hashicorp.com/) with questions.
+
+## Revoked Versions
+
+If an HCP Packer Version is revoked, the `hcp-packer-version` data source will fail and Packer won't proceed with
+the build. Building new artifacts from a revoked artifact is not compliant.
+Versions that are scheduled to be revoked will still be considered valid until the revocation date.
+
+## Basic Example
+
+Below is a fully functioning example. It stores information about an image artifact,
+which can then be parsed and accessed as a variable.
+
+```hcl
+data "hcp-packer-artifact" "example" {
+ bucket_name = "hardened-ubuntu-16-04"
+ version_fingerprint = "${data.hcp-packer-version.hardened-source.fingerprint}"
+ platform = "aws"
+ region = "us-east-1"
+}
+```
+
+## Full Example
+
+This data source can be used in conjunction with the hcp-packer-version
+data source to retrieve a version fingerprint using a channel. You provide the version fingerprint and channel
+name to the version data source, then use the version source inside the
+artifact data source, then use the artifact data source inside your source block.
+
+```hcl
+# Retrieves information about the HCP Packer Version; a "version" can be
+# thought of as all the metadata created by a single call of `packer build`.
+data "hcp-packer-version" "hardened-source" {
+ bucket_name = "hardened-ubuntu-16-04"
+ channel_name = "dev"
+}
+
+# Retrieves information about the HCP Packer Artifact; an artifact can be thought
+# of as all the metadata (including the artifact names) created by a single
+# "source" builder; this can include multiple artifacts so we provide a
+# region to disambiguate.
+data "hcp-packer-artifact" "example" {
+ bucket_name = "hardened-ubuntu-16-04"
+ version_fingerprint = data.hcp-packer-version.hardened-source.fingerprint
+ platform = "aws"
+ region = "us-east-1"
+}
+
+# This source uses the output from a previous Packer build. By using the
+# HCP Packer Registry in this way, you can easily create build pipelines where
+# a single base artifact can be customized in multiple secondary layers.
+source "amazon-ebs" "packer-secondary" {
+ source_ami = data.hcp-packer-artifact.example.external_identifier
+ ...
+}
+```
+
+## Configuration Reference
+
+Configuration options are organized below into two categories: required and
+optional. Within each category, the available options are alphabetized and
+described.
+
+### Required:
+
+@include 'datasource/hcp-packer-artifact/Config-required.mdx'
+
+### Optional:
+
+~> **Note:** This data source only returns the first found artifact's metadata filtered by the given options,
+from the returned list of artifacts associated with the specified version. Therefore, if multiple artifacts exist
+in the same region, it will only pick one of them. In this case, you can filter artifact by a source build name
+(Ex: `amazon-ebs.example`) using the `component_type` option.
+
+@include 'datasource/hcp-packer-artifact/Config-not-required.mdx'
+
+### Output Fields:
+
+@include 'datasource/hcp-packer-artifact/DatasourceOutput.mdx'
diff --git a/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-image.mdx b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-image.mdx
new file mode 100644
index 0000000000..d7312921cb
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-image.mdx
@@ -0,0 +1,100 @@
+---
+description: |
+ This data source has been deprecated, please use HCP Packer Artifact data source instead.
+ The HCP Packer Image Data Source retrieves information about an
+ image from the HCP Packer registry. This information can be used to
+ provide a source image to various Packer builders.
+page_title: HCP Packer Image - Data Sources
+---
+
+
+
+
+
+# HCP Packer Image Data Source
+
+~> **Note:** This data source has been deprecated, please use [HCP Packer Artifact](/packer/docs/datasources/hcp/hcp-packer-artifact) data source instead.
+
+Type: `hcp-packer-image`
+
+The `HCP Packer Image` Data Source retrieves information about an
+image from the HCP Packer registry. This information can be used to
+provide a source image to various Packer builders.
+
+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).
+
+~> **Note:** You will receive an error if you try to reference metadata from a deactivated or deleted registry. An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries with billing issues. Contact [HashiCorp Support](https://support.hashicorp.com/) with questions.
+
+## Revoked Iterations
+
+If an iteration is revoked, the `hcp-packer-iteration` data source will fail and Packer won't proceed with the build. Building new images from a revoked image is not compliant.
+Iterations that are scheduled to be revoked will still be considered valid until the revocation date.
+
+## Basic Example
+
+Below is a fully functioning example. It stores information about an image,
+which can then be parsed and accessed as a variable.
+
+```hcl
+data "hcp-packer-image" "example" {
+ bucket_name = "hardened-ubuntu-16-04"
+ iteration_id = "${data.hcp-packer-iteration.hardened-source.id}"
+ cloud_provider = "aws"
+ region = "us-east-1"
+}
+```
+
+## Full Example
+
+This data source can be used in conjunction with the hcp-packer-iteration
+data source to retrieve an image ID using a channel. You provide the channel
+name to the iteration data source, then use the iteration source in the image
+data source, then use the image data source inside your source block.
+
+```hcl
+# Retrieves information about the HCP Packer "iteration"; an "iteration" can be
+# thought of as all the metadata created by a single call of `packer build`.
+data "hcp-packer-iteration" "hardened-source" {
+ bucket_name = "hardened-ubuntu-16-04"
+ channel = "packer-test"
+}
+
+# Retrieves information about the HCP Packer "image"; an image can be thought
+# of as all the metadata (including the artifact names) created by a single
+# "source" builder; this can include multiple images so we provide a cloud
+# region to disambiguate.
+data "hcp-packer-image" "foo" {
+ bucket_name = "hardened-ubuntu-16-04"
+ iteration_id = data.hcp-packer-iteration.hardened-source.id
+ cloud_provider = "aws"
+ region = "us-east-1"
+}
+
+# This source uses the output from a previous Packer build. By using the
+# HCP Packer registry in this way, you can easily create build pipelines where
+# a single base image can be customized in multiple secondary layers.
+source "amazon-ebs" "packer-secondary" {
+ source_ami = data.hcp-packer-image.foo.id
+ # ...
+}
+```
+
+## Configuration Reference
+
+Configuration options are organized below into two categories: required and
+optional. Within each category, the available options are alphabetized and
+described.
+
+### Required:
+
+@include 'datasource/hcp-packer-image/Config-required.mdx'
+
+### Optional:
+
+~> **Note:** This data source only returns the first found image's metadata filtered by the given options, from the returned list of images associated with the specified iteration. Therefore, if multiple images exist in the same region, it will only pick one of them. In this case, you can filter images by a source build name (Ex: `amazon-ebs.example`) using the `component_type` option.
+
+@include 'datasource/hcp-packer-image/Config-not-required.mdx'
+
+### Output Fields:
+
+@include 'datasource/hcp-packer-image/DatasourceOutput.mdx'
diff --git a/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-iteration.mdx b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-iteration.mdx
new file mode 100644
index 0000000000..6ad6fb3c39
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-iteration.mdx
@@ -0,0 +1,95 @@
+---
+description: |
+ This data source has been deprecated, please use HCP Packer Version data source instead.
+ The HCP Packer Iteration Data Source retrieves information about an
+ iteration from the HCP Packer registry. This information can be used to
+ query HCP for a source image for various Packer builders.
+page_title: HCP Packer Iteration - Data Sources
+---
+
+
+
+
+
+# HCP Packer Iteration Data Source
+
+~> **Note:** This data source has been deprecated, please use [HCP Packer Version](/packer/docs/datasources/hcp/hcp-packer-version) data source instead.
+
+Type: `hcp-packer-iteration`
+
+The `HCP Packer Iteration` Data Source retrieves information about an
+iteration from the HCP Packer registry. This information can be used to query
+HCP for a source image for various Packer builders.
+
+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).
+
+~> **Note:** You will receive an error if you try to reference metadata from a deactivated or deleted registry. An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries with billing issues. Contact [HashiCorp Support](https://support.hashicorp.com/) with questions.
+
+## Revoked Iterations
+
+If an iteration is revoked, the `hcp-packer-iteration` data source will fail and Packer won't proceed with the build. Building new images from a revoked image is not compliant.
+Iterations that are scheduled to be revoked will still be considered valid until the revocation date.
+
+## Basic Example
+
+Below is a fully functioning example. It stores information about an image
+iteration, which can then be accessed as a variable.
+
+```hcl
+data "hcp-packer-iteration" "hardened-source" {
+ bucket_name = "hardened-ubuntu-16-04"
+ channel = "packer-test"
+}
+```
+
+## Full Example
+
+This data source can be used in conjunction with the hcp-packer-image
+data source to retrieve an image ID using a channel. You provide the channel
+name to the iteration data source, then use the iteration source inside the
+image data source, then use the image data source inside your source block.
+
+```hcl
+# Retrieves information about the HCP Packer "iteration"; an "iteration" can be
+# thought of as all the metadata created by a single call of `packer build`.
+data "hcp-packer-iteration" "hardened-source" {
+ bucket_name = "hardened-ubuntu-16-04"
+ channel = "packer-test"
+}
+
+# Retrieves information about the HCP Packer "image"; an image can be thought
+# of as all the metadata (including the artifact names) created by a single
+# "source" builder; this can include multiple images so we provide a cloud
+# region to disambiguate.
+data "hcp-packer-image" "foo" {
+ bucket_name = "hardened-ubuntu-16-04"
+ iteration_id = data.hcp-packer-iteration.hardened-source.id
+ cloud_provider = "aws"
+ region = "us-east-1"
+}
+
+# This source uses the output from a previous Packer build. By using the
+# HCP Packer registry in this way, you can easily create build pipelines where
+# a single base image can be customized in multiple secondary layers.
+source "amazon-ebs" "packer-secondary" {
+ source_ami = data.hcp-packer-image.foo.id
+ ...
+}
+```
+
+## Configuration Reference
+
+Configuration options are organized below into two categories: required and
+optional. Within each category, the available options are alphabetized and
+described.
+
+### Required:
+
+@include 'datasource/hcp-packer-iteration/Config-required.mdx'
+
+There are currently no optional fields for this datasource, though we intend
+to add filtering fields in the future.
+
+### Output Fields:
+
+@include 'datasource/hcp-packer-iteration/DatasourceOutput.mdx'
diff --git a/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-version.mdx b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-version.mdx
new file mode 100644
index 0000000000..b84efdf405
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/hcp/hcp-packer-version.mdx
@@ -0,0 +1,96 @@
+---
+description: |
+ The HCP Packer Version Data Source retrieves information about
+ HCP Packer Version from the HCP Packer Registry. This information can be used to
+ query HCP for a source external identifier for various Packer builders.
+page_title: HCP Packer Version - Data Sources
+---
+
+
+
+
+
+
+# HCP Packer Version Data Source
+
+Type: `hcp-packer-version`
+
+The `HCP Packer Version` Data Source retrieves information about
+HCP Packer Version from the HCP Packer Registry. This information can be used to
+query HCP for a source external identifier for various Packer builders.
+
+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).
+
+~> **Note:** You will receive an error if you try to reference metadata from a deactivated or deleted registry.
+An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries
+with billing issues. Contact [HashiCorp Support](https://support.hashicorp.com/) with questions.
+
+## Revoked Versions
+
+If an HCP Packer Version is revoked, the `hcp-packer-version` data source will fail and Packer won't proceed with
+the build. Building new artifacts from a revoked artifact is not compliant.
+Versions that are scheduled to be revoked will still be considered valid until the revocation date.
+
+## Basic Example
+
+Below is a fully functioning example. It stores information about an HCP Packer Version, which can then be accessed as a variable.
+
+```hcl
+data "hcp-packer-version" "hardened-source" {
+ bucket_name = "hardened-ubuntu-16-04"
+ channel_name = "dev"
+}
+```
+
+## Full Example
+
+This data source can be used in conjunction with the `hcp-packer-artifact`
+data source to retrieve an artifact identifier. You provide the version fingerprint and channel
+name to the version data source, then use the version source inside the
+artifact data source, then use the artifact data source inside your source block.
+
+```hcl
+# Retrieves information about the HCP Packer Version; a "version" can be
+# thought of as all the metadata created by a single call of `packer build`.
+data "hcp-packer-version" "hardened-source" {
+ bucket_name = "hardened-ubuntu-16-04"
+ channel_name = "dev"
+}
+
+# Retrieves information about the HCP Packer Artifact; an artifact can be thought
+# of as all the metadata (including the artifact names) created by a single
+# "source" builder; this can include multiple artifacts so we provide a
+# region to disambiguate.
+data "hcp-packer-artifact" "example" {
+ bucket_name = "hardened-ubuntu-16-04"
+ version_fingerprint = data.hcp-packer-version.hardened-source.fingerprint
+ platform = "aws"
+ region = "us-east-1"
+}
+
+# This source uses the output from a previous Packer build. By using the
+# HCP Packer Registry in this way, you can easily create build pipelines where
+# a single base artifact can be customized in multiple secondary layers.
+source "amazon-ebs" "packer-secondary" {
+ source_ami = data.hcp-packer-artifact.example.external_identifier
+ ...
+}
+```
+
+## Configuration Reference
+
+Configuration options are organized below into two categories: required and
+optional. Within each category, the available options are alphabetized and
+described.
+
+### Required:
+
+@include 'datasource/hcp-packer-version/Config-required.mdx'
+
+There are currently no optional fields for this datasource, though we intend
+to add filtering fields in the future.
+
+### Output Fields:
+
+@include 'datasource/hcp-packer-version/DatasourceOutput.mdx'
diff --git a/content/packer/v1.10.x/content/docs/datasources/hcp/index.mdx b/content/packer/v1.10.x/content/docs/datasources/hcp/index.mdx
new file mode 100644
index 0000000000..7f5fff7616
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/hcp/index.mdx
@@ -0,0 +1,47 @@
+---
+description: |
+ Data sources used to data from the HCP Packer registry.
+page_title: HCP - Data sources
+sidebar_title: Overview
+---
+
+
+
+
+
+# HCP Packer Registry Data sources
+
+The HCP Packer Registry bridges the gap between artifact factories and artifact
+deployments, allowing development and security teams to work together to create,
+manage, and consume artifacts in a centralized way.
+
+The HCP Packer Registry stores metadata about your artifacts, including when they
+were created, where the artifacts exists in the cloud, and what (if any) git commit
+is associated with your build. You can use the registry to track
+information about the artifacts your Packer builds produce, clearly
+designate which artifacts are appropriate for test and production environments,
+and query for the right artifacts to use in both Packer and Terraform
+configurations.
+
+Packer has two data sources that work together to retrieve information from the
+HCP Packer registry:
+
+- [hcp-packer-version](/packer/docs/datasources/hcp/hcp-packer-version) -
+retrieves information about an HCP Packer Version in HCP Packer Registry
+- [hcp-packer-artifact](/packer/docs/datasources/hcp/hcp-packer-artifact) - retrieves
+information about a specific artifact created in the HCP Packer registry
+
+Deprecated data sources: (Please use above given data sources instead)
+- [hcp-packer-iteration](/packer/docs/datasources/hcp/hcp-packer-iteration) -
+ retrieves information about an iteration in HCP Packer registry
+- [hcp-packer-image](/packer/docs/datasources/hcp/hcp-packer-image) - retrieves
+ information about a specific image created in the HCP Packer registry
+
+These data sources are intended to be used together to determine source artifact
+for pipelined Packer builds.
+
+## How to use this plugin
+
+This plugin comes bundled with the Packer core, so you do not need to install
+it separately. Please install Packer v1.7.7 or above to use the latest version
+of the HCP Packer Registry data sources.
diff --git a/content/packer/v1.10.x/content/docs/datasources/http.mdx b/content/packer/v1.10.x/content/docs/datasources/http.mdx
new file mode 100644
index 0000000000..f11e5c64a8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/http.mdx
@@ -0,0 +1,50 @@
+---
+description: |
+ The HTTP Data Source retrieves information from an HTTP endpoint to be used
+ during Packer builds
+page_title: HTTP - Data Sources
+---
+
+
+
+
+
+
+# HTTP Data Source
+
+Type: `http`
+
+The `http` data source makes an HTTP GET request to the given URL and exports information about the response.
+
+
+## Basic Example
+
+```hcl
+data "http" "example" {
+ url = "https://checkpoint-api.hashicorp.com/v1/check/terraform"
+
+ # Optional request headers
+ request_headers = {
+ Accept = "application/json"
+ }
+}
+```
+
+## Configuration Reference
+
+Configuration options are organized below into two categories: required and
+optional. Within each category, the available options are alphabetized and
+described.
+
+### Required:
+
+@include 'datasource/http/Config-required.mdx'
+
+### Not Required:
+@include 'datasource/http/Config-not-required.mdx'
+
+## Datasource outputs
+
+The outputs for this datasource are as follows:
+
+@include 'datasource/http/DatasourceOutput.mdx'
diff --git a/content/packer/v1.10.x/content/docs/datasources/index.mdx b/content/packer/v1.10.x/content/docs/datasources/index.mdx
new file mode 100644
index 0000000000..cf70bde28c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/datasources/index.mdx
@@ -0,0 +1,15 @@
+---
+description: |
+ Data sources allow data to be fetched for use in Packer configuration. Use of data sources
+ allows a build to use information defined outside of Packer.
+page_title: Data Sources
+---
+
+# Data Sources
+
+Data sources let Packer fetch data to use in a template, including information defined outside of Packer.
+
+Refer to the [`data`](/packer/docs/templates/hcl_templates/datasources) block documentation to learn more about working with data sources. The documentation also contains details about each type of data source.
+
+-> **Note:** Data sources is a feature exclusively available to HCL2 templates included in Packer `v1.7.0` (and newer).
+
diff --git a/content/packer/v1.10.x/content/docs/debugging.mdx b/content/packer/v1.10.x/content/docs/debugging.mdx
new file mode 100644
index 0000000000..0adad6c9d8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/debugging.mdx
@@ -0,0 +1,151 @@
+---
+description: |
+ Packer strives to be stable and bug-free, but issues inevitably arise where
+ certain things may not work entirely correctly, or may not appear to work
+ correctly.
+page_title: Debugging - Other
+---
+
+# Debugging Packer Builds
+
+Using `packer build -on-error=ask` allows you to inspect failures and try out
+solutions before restarting the build.
+
+For remote builds with cloud providers like Amazon Web Services AMIs, debugging
+a Packer build can be eased greatly with `packer build -debug`. This disables
+parallelization and enables debug mode.
+
+Debug mode informs the builders that they should output debugging information.
+The exact behavior of debug mode is left to the builder. In general, builders
+usually will stop between each step, waiting for keyboard input before
+continuing. This will allow you to inspect state and so on.
+
+In debug mode once the remote instance is instantiated, Packer will emit to the
+current directory an ephemeral private SSH key as a .pem file. Using that you
+can `ssh -i ` into the remote build instance and see what is going on
+for debugging. The key will only be emitted for cloud-based builders. The
+ephemeral key will be deleted at the end of the Packer run during cleanup.
+
+For a local builder, the SSH session initiated will be visible in the detail
+provided when `PACKER_LOG=1` environment variable is set prior to a build, and
+you can connect to the local machine using the userid and password defined in
+the kickstart or preseed associated with initializing the local VM.
+
+It should be noted that one of the options `-on-error` is to `retry`, the retry
+of the step in question has limitations:
+
+- the template Packer is building is **not** reloaded from file.
+- the resources specified from builders **are** reloaded from file.
+
+Check the specifics on your builder to confirm their behavior.
+
+### Windows
+
+As of Packer 0.8.1 the default WinRM communicator will emit the password for a
+Remote Desktop Connection into your instance. This happens following the
+several minute pause as the instance is booted. Note a .pem key is still
+created for securely transmitting the password. Packer automatically decrypts
+the password for you in debug mode.
+
+## Debugging Packer
+
+Issues occasionally arise where certain things may not work entirely correctly,
+or may not appear to work correctly. In these cases, it is sometimes helpful to
+see more details about what Packer is actually doing.
+
+Packer has detailed logs which can be enabled by setting the `PACKER_LOG`
+environmental variable to any value but `""` (empty string) and `"0"` like this
+`PACKER_LOG=1 packer build `. This will cause detailed logs to
+appear on stderr. The logs contain log messages from Packer as well as any
+plugins that are being used. Log messages from plugins are prefixed by their
+application name.
+
+Note that because Packer is highly parallelized, log messages sometimes appear
+out of order, especially with respect to plugins. In this case, it is important
+to pay attention to the timestamp of the log messages to determine order.
+
+In addition to simply enabling the log, you can set `PACKER_LOG_PATH` in order
+to force the log to always go to a specific file when logging is enabled. Note
+that even when `PACKER_LOG_PATH` is set, `PACKER_LOG` must be set in order for
+any logging to be enabled.
+
+### Debugging Plugins
+
+Each packer plugin runs in a separate process and communicates with RPC over a
+socket therefore using a debugger will not work (be complicated at least).
+
+But most of the Packer code is really simple and easy to follow with PACKER_LOG
+turned on. If that doesn't work adding some extra debug print outs when you have
+homed in on the problem is usually enough.
+
+### Debugging Packer in Powershell/Windows
+
+In Windows you can set the detailed logs environmental variable `PACKER_LOG` or
+the log variable `PACKER_LOG_PATH` using PowerShell environment variables. For
+example:
+
+```powershell
+$env:PACKER_LOG=1
+$env:PACKER_LOG_PATH="packerlog.txt"
+```
+
+If you find a bug with Packer, please include the detailed log by using a
+service such as [gist](https://gist.github.com).
+
+## Issues Installing Ubuntu Packages
+
+Issues may arise using and building Ubuntu AMIs where common packages that
+_should_ be installed from Ubuntu's Main repository are not found during a
+provisioner step:
+
+```text
+amazon-ebs: No candidate version found for build-essential
+amazon-ebs: No candidate version found for build-essential
+```
+
+This, obviously can cause problems where a build is unable to finish
+successfully as the proper packages cannot be provisioned correctly. The
+problem arises when cloud-init has not finished fully running on the source AMI
+by the time that packer starts any provisioning steps.
+
+Adding the following provisioner to the Packer template, allows for the
+cloud-init process to fully finish before packer starts provisioning the source
+AMI.
+
+```json
+{
+ "type": "shell",
+ "inline": [
+ "cloud-init status --wait"
+ ]
+}
+```
+
+## Issues when using numerous Builders/Provisioners/Post-Processors
+
+Packer uses a separate process for each builder, provisioner, post-processor,
+and plugin. In certain cases, if you have too many of these, you can run out of
+[file descriptors](https://en.wikipedia.org/wiki/File_descriptor). This results
+in an error that might look like
+
+```text
+error initializing provisioner 'powershell': fork/exec /files/go/bin/packer:
+too many open files
+```
+
+On Unix systems, you can check what your file descriptor limit is with
+`ulimit -Sn`. You should check with your OS vendor on how to raise this limit.
+
+## Issues when using long temp directory
+
+Packer uses Unix sockets internally, which are created inside the default
+directory for temporary files. Some operating systems place a limit on the
+length of the socket name, usually between 80 and 110 characters. If you get an
+error like this (for any builder, not just Docker):
+
+```text
+Failed to initialize build 'docker': error initializing builder 'docker': plugin exited before we could connect
+```
+
+you should try setting your temp directory to something shorter. This can be
+done through the `TMPDIR` environment variable.
diff --git a/content/packer/v1.10.x/content/docs/hcp/index.mdx b/content/packer/v1.10.x/content/docs/hcp/index.mdx
new file mode 100644
index 0000000000..8063bd0dcc
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/hcp/index.mdx
@@ -0,0 +1,120 @@
+---
+description: |
+ Packer can publish metadata for completed builds to an HCP Packer Registry. Legacy JSON templates can connect to the registry using environment variables. HCL2 templates can connect using an hcp_packer_registry block.
+page_title: HCP Packer
+---
+
+-> **Note:** On May 16th 2023, HCP introduced multi-project support to the platform. In order to use multiple projects
+in your organization, you will need to update Packer to version 1.9.1 or above. Starting with 1.9.1, you may specify
+a project ID to push builds to with the `HCP_PROJECT_ID` environment variable. If no project ID is specified,
+Packer will pick the project with the oldest creation date. Older versions of Packer are incompatible with multi-project
+support on HCP, and builds will fail for HCP organizations with multiple projects on versions before 1.9.1.
+
+# HCP Packer
+
+The HCP Packer registry bridges the gap between artifact factories and artifact deployments, allowing development and
+security teams to work together to create, manage, and consume artifacts in a centralized way.
+
+The HCP Packer Registry stores metadata about your artifact, including when they were created, where the artifact
+exists on the external platform, and what (if any) git commit is associated with your build. You can use the registry
+to track information about the artifact your Packer builds produce, clearly designate which artifact are appropriate
+for test and production environments, and query for the right artifact to use in both Packer and Terraform
+configurations.
+
+You can use HCP Packer with both JSON and HCL2 templates. If you are using JSON templates, we recommend getting started with
+the [HCP Packer environment variables](#hcp-packer-environment-variables) and then migrating to HCL when possible.
+
+This page summarizes the methods you can use to connect JSON and HCL2 templates to the HCP Packer registry. It also
+provides a full list of HCP Packer environment variables. Refer to the
+[Packer Template Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration) page in the HCP
+Packer documentation for full configuration details and examples.
+
+### HCP Packer Environment Variables
+
+The following environment variables let you configure Packer to push artifact metadata to an active registry without
+changing your template. You can use environment variables with both JSON and HCL2 templates.
+Refer to [Basic Configuration With Environment Variables](/hcp/docs/packer/store-image-metadata/packer-template-configuration#basic-configuration-with-environment-variables)
+in the HCP Packer documentation for complete instructions and examples.
+
+You must set the following environment variables to enable Packer to push metadata to a registry.
+
+- `HCP_CLIENT_ID` - The HCP client ID of a HashiCorp Cloud Platform service principle that Packer can use to
+authenticate to an HCP Packer Registry.
+
+- `HCP_CLIENT_SECRET` - The HCP client secret of the HashiCorp Cloud Platform service principle that Packer
+can use to authenticate to an HCP Packer Registry.
+
+- `HCP_PACKER_BUCKET_NAME` - The name of the HCP Packer Bucket where you want HCP Packer to store artifact metadata
+from builds associated with your template. HCP Packer automatically creates the bucket if it does not already exist.
+If your HCL2 template contains an `hcp_packer_registry` block, the bucket name specified in the configuration will be
+overwritten by this environment variable.
+
+You can set these additional environment variables to control how metadata is pushed to the registry.
+
+- `HCP_PACKER_BUILD_FINGERPRINT` - A unique identifier assigned to each version. To reuse a fingerprint that is
+associated with an existing incomplete version you must set this environment variable. Refer to
+[Version Fingerprinting](#version-fingerprinting) for usage details.
+
+- `HCP_PACKER_REGISTRY` - When set, Packer does not push artifact metadata to HCP Packer from an otherwise
+configured template. Allowed values are [0|OFF].
+
+- `HCP_ORGANIZATION_ID` - The ID of the HCP organization linked to your service principal. This is environment
+variable is not required and available for the sole purpose of keeping parity with the HCP SDK authentication options.
+Its use may change in a future release.
+
+- `HCP_PROJECT_ID` - The ID of the HCP project to use. This is useful if your service principal has access to multiple
+projects, as by default Packer will pick the one created first as target.
+
+-> **Note**: The HCP_PROJECT_ID environment variable must be set if you're authenticating with a project-level service
+principal, otherwise Packer will attempt to get the list of projects for an organization and error due to a lack of
+permissions for a project-level service principal. This is supported starting with Packer 1.9.3; older versions of
+Packer do not support using project-level service principals.
+
+### HCP Packer Registry Block
+
+The only metadata that Packer can infer from a template with the basic configuration are the build name and build fingerprint.
+For HCL2 templates, we recommend adding the `hcp_packer_registry` block to your template so that you can customize
+the metadata that Packer sends to the registry.
+
+The `hcp_packer_registry` block is only available for HCL2 Packer templates. There is no [`PACKER_CONFIG`](/packer/docs/configure#packer-s-config-file) equivalent for JSON.
+
+Refer to [`hcp_packer_registry`](/packer/docs/templates/hcl_templates/blocks/build/hcp_packer_registry) for a full list
+of configuration arguments. Refer to [Custom Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration#custom-configuration)
+in the HCP Packer documentation for information and examples about how to customize artifact metadata.
+
+### Version Fingerprinting
+
+Packer uses a unique fingerprint for tracking the completion of builds associated to a version. By default a fingerprint
+is automatically generated by Packer during each invocation of `packer build`, unless a fingerprint is manually provided
+via the `HCP_PACKER_BUILD_FINGERPRINT` environment variable.
+
+In versions before 1.9.0, this fingerprint was computed from the Git SHA of the current HEAD in which your template is
+stored. If you were running builds using a non Git managed template, you had to set the `HCP_PACKER_BUILD_FINGERPRINT`
+environment variable prior to invoking `packer build`.
+Starting with Packer 1.9.0, fingerprint generation does not rely on Git at all, and instead Packer now generates
+a Unique Lexicographically sortable Identifier (ULID) as the fingerprint for every `packer build` invocation.
+
+#### Fingerprints and Incomplete Versions
+
+When you build a template with Packer, there's always a chance that it does not succeed because of a network issue,
+a provisioning failure, or some upstream error. When that happens, Packer will output the generated fingerprint
+associated with the incomplete version so that you can resume building that version using the `HCP_PACKER_BUILD_FINGERPRINT`
+environment variable; a version can be resumed until it is marked as complete. This environment variable is necessary
+for resuming an incomplete version, otherwise Packer will create a new version for the build.
+
+There are two alternatives for when and how to set your own fingerprint:
+
+* You can set it prior to invoking `packer build` for the first time on this template. This will require the
+fingerprint to be unique, otherwise Packer will attempt to continue the version with the same fingerprint.
+* You can invoke `packer build` on the template, and if it fails, you can then get the fingerprint from the output of
+the command and set it for subsequent runs, Packer will then continue building this version.
+
+The first alternative is recommended for CI environments, as you can use environment variables from the CI to generate
+a unique, deterministic, fingerprint, and then re-use this in case the step fails for any reason. This will let you
+continue building the same version, rather than creating a new one on each invocation.
+
+The second alternative is good for local builds, as you can interact with the build environment directly, and therefore
+can decide if you want to continue building a version by setting the fingerprint provided by Packer in case of failure.
+
+Please note that in all cases, a version can only be continued if it has not completed yet. Once a version is
+complete, it cannot be modified, and you will have to create a new one.
diff --git a/content/packer/v1.10.x/content/docs/index.mdx b/content/packer/v1.10.x/content/docs/index.mdx
new file mode 100644
index 0000000000..b4ab7cf0cd
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/index.mdx
@@ -0,0 +1,19 @@
+---
+description: |
+ Packer allows you to create identical machine images for multiple platforms from a single source template.
+page_title: Documentation
+---
+
+# Packer Documentation
+
+[Packer](https://www.packer.io/) is a community tool that enables you to create identical machine images for multiple platforms from a single source template. A common use case is creating "golden images" that teams across an organization can use in cloud infrastructure.
+
+To install Packer and learn the standard Packer workflow, try the [Get Started tutorials](/packer/tutorials).
+
+## HCP Packer
+
+The HCP Packer registry stores metadata about your artifacts. You can use the registry to track information about
+artifacts from your Packer builds, clearly designate which artifacts are appropriate for test and production
+environments, and query for the right artifacts to use in both Packer and Terraform configurations.
+
+To get started, visit the [HCP Packer documentation](/hcp/docs/packer) or try the [Get Started with HCP Packer tutorials](/packer/tutorials/hcp-get-started).
diff --git a/content/packer/v1.10.x/content/docs/install.mdx b/content/packer/v1.10.x/content/docs/install.mdx
new file mode 100644
index 0000000000..548049dc7a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/install.mdx
@@ -0,0 +1,13 @@
+---
+description: |
+ Installing Packer is simple. You can download a precompiled binary or compile
+ from source. This page details both methods.
+page_title: Install
+---
+
+# Install Packer
+
+For detailed instructions on how to install Packer, see [this
+Getting Started guide][install].
+
+[install]: /packer/tutorials/docker-get-started/get-started-install-cli 'Install Packer'
diff --git a/content/packer/v1.10.x/content/docs/intro/index.mdx b/content/packer/v1.10.x/content/docs/intro/index.mdx
new file mode 100644
index 0000000000..d6fb56902f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/intro/index.mdx
@@ -0,0 +1,31 @@
+---
+page_title: Introduction
+description: |-
+ Welcome to the world of Packer! This introduction guide will show you what
+ Packer is, explain why it exists, the benefits it has to offer, and how you
+ can get started with it. If you're already familiar with Packer, the
+ documentation provides more of a reference for all available features.
+---
+
+# Introduction to Packer
+
+Welcome to the world of Packer! This introduction guide will show you what
+Packer is, explain why it exists, the benefits it has to offer, and how you can
+get started with it. If you're already familiar with Packer, the
+[documentation](/packer/docs) provides more of a reference for all available
+features.
+
+## What is Packer?
+
+Packer is a community tool for creating identical machine images for multiple
+platforms from a single source configuration. Packer is lightweight, runs on
+every major operating system, and is highly performant, creating machine images
+for multiple platforms in parallel. Packer does not replace configuration
+management like Chef or Puppet. In fact, when building images, Packer is able to
+use tools like Chef or Puppet to install software onto the image.
+
+A _machine image_ is a single static unit that contains a pre-configured
+operating system and installed software which is used to quickly create new
+running machines. Machine image formats change for each platform. Some examples
+include [AMIs](https://en.wikipedia.org/wiki/Amazon_Machine_Image) for EC2,
+VMDK/VMX files for VMware, OVF exports for VirtualBox, etc.
diff --git a/content/packer/v1.10.x/content/docs/intro/use-cases.mdx b/content/packer/v1.10.x/content/docs/intro/use-cases.mdx
new file mode 100644
index 0000000000..e6e3c63c67
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/intro/use-cases.mdx
@@ -0,0 +1,54 @@
+---
+page_title: Use Cases - Introduction
+description: |-
+ By now you should know what Packer does and what the benefits of image
+ creation are. In this section, we'll enumerate *some* of the use cases for
+ Packer. Note that this is not an exhaustive list by any means. There are
+ definitely use cases for Packer not listed here. This list is just meant to
+ give you an idea of how Packer may improve your processes.
+---
+
+# Use Cases
+
+By now you should know what Packer does and what the benefits of image creation
+are. In this section, we'll enumerate _some_ of the use cases for Packer. Note
+that this is not an exhaustive list by any means. There are definitely use cases
+for Packer not listed here. This list is just meant to give you an idea of how
+Packer may improve your processes.
+
+### Continuous Delivery
+
+Packer is lightweight, portable, and command-line driven. This makes it the
+perfect tool to put in the middle of your continuous delivery pipeline. Packer
+can be used to generate new machine images for multiple platforms on every
+change to Chef/Puppet.
+
+As part of this pipeline, the newly created images can then be launched and
+tested, verifying the infrastructure changes work. If the tests pass, you can be
+confident that the image will work when deployed. This brings a new level of
+stability and testability to infrastructure changes.
+
+### Dev/Prod Parity
+
+Packer helps [keep development, staging, and production as similar as
+possible](http://www.12factor.net/dev-prod-parity). Packer can be used to
+generate images for multiple platforms at the same time. So if you use AWS for
+production and VMware (perhaps with [Vagrant](https://www.vagrantup.com/)) for
+development, you can generate both an AMI and a VMware machine using Packer at
+the same time from the same template.
+
+Mix this in with the continuous delivery use case above, and you have a pretty
+slick system for consistent work environments from development all the way
+through to production.
+
+### Appliance/Demo Creation
+
+Since Packer creates consistent images for multiple platforms in parallel, it is
+perfect for creating
+[appliances](https://en.wikipedia.org/wiki/Software_appliance) and disposable
+product demos. As your software changes, you can automatically create appliances
+with the software pre-installed. Potential users can then get started with your
+software by deploying it to the environment of their choice.
+
+Packaging up software with complex requirements has never been so easy. Or
+enjoyable, if you ask me.
diff --git a/content/packer/v1.10.x/content/docs/intro/why.mdx b/content/packer/v1.10.x/content/docs/intro/why.mdx
new file mode 100644
index 0000000000..ff8a317564
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/intro/why.mdx
@@ -0,0 +1,55 @@
+---
+page_title: Why Packer - Introduction
+description: |-
+ Pre-baked machine images have a lot of advantages, but most have been unable
+ to benefit from them because images have been too tedious to create and
+ manage. There were either no existing tools to automate the creation of
+ machine images or they had too high of a learning curve. The result is that,
+ prior to Packer, creating machine images threatened the agility of operations
+ teams, and therefore aren't used, despite the massive benefits.
+---
+
+# Why Use Packer?
+
+Pre-baked machine images have a lot of advantages, but most have been unable to
+benefit from them because images have been too tedious to create and manage.
+There were either no existing tools to automate the creation of machine images
+or they had too high of a learning curve. The result is that, prior to Packer,
+creating machine images threatened the agility of operations teams, and
+therefore aren't used, despite the massive benefits.
+
+Packer changes all of this. Packer automates the creation of
+any type of machine image. It embraces modern configuration management by
+encouraging you to use a framework such as Chef or Puppet to install and
+configure the software within your Packer-made images.
+
+In other words: Packer brings pre-baked images into the modern age, unlocking
+untapped potential and opening new opportunities.
+
+## Advantages of Using Packer
+
+**_Super fast infrastructure deployment_**. Packer images allow you to launch
+completely provisioned and configured machines in seconds, rather than several
+minutes or hours. This benefits not only production, but development as well,
+since development virtual machines can also be launched in seconds, without
+waiting for a typically much longer provisioning time.
+
+**_Multi-provider portability_**. Because Packer creates identical images for
+multiple platforms, you can run production in AWS, staging/QA in a private cloud
+like OpenStack, and development in desktop virtualization solutions such as
+VMware or VirtualBox. Each environment is running an identical machine image,
+giving ultimate portability.
+
+**_Improved stability_**. Packer installs and configures all the software for a
+machine at the time the image is built. If there are bugs in these scripts,
+they'll be caught early, rather than several minutes after a machine is
+launched.
+
+**_Greater testability_**. After a machine image is built, that machine image
+can be quickly launched and smoke tested to verify that things appear to be
+working. If they are, you can be confident that any other machines launched from
+that image will function properly.
+
+Packer makes it extremely easy to take advantage of all these benefits.
+
+What are you waiting for? Let's get started!
diff --git a/content/packer/v1.10.x/content/docs/partnerships.mdx b/content/packer/v1.10.x/content/docs/partnerships.mdx
new file mode 100644
index 0000000000..97d1ec526f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/partnerships.mdx
@@ -0,0 +1,147 @@
+---
+description: |
+ The HashiCorp Packer Integration Program allows vendors to integrate
+ their products to work with Packer.
+page_title: Integration Program
+---
+
+# Packer Integration Program
+
+The HashiCorp Packer Integration Program allows vendors to integrate their products to work with Packer.
+
+Vendors integrating their solutions via the Packer Integration Process provide their customers a verified and seamless user experience. The Packer Integration Program currently only supports coding with the Go programming language.
+
+This program is intended to be largely a self-service process with links and guidance to information sources, clearly defined steps, and checkpoints.
+
+### Types of Packer Integrations
+
+Packer is a community tool for creating identical machine images for multiple platforms from a single source configuration.
+Packer is lightweight, runs on every major operating system, and is highly performant, creating machine images for multiple platforms in parallel. Packer does not replace configuration management like Chef or Puppet. In fact, when building images, Packer is able to use tools like Chef or Puppet to install software onto the image.
+
+A machine image is a single static unit that contains a pre-configured operating system and installed software which is used to quickly create new running machines. Machine image formats change for each platform. Some examples include AMIs for EC2, VMDK/VMX files for VMware, OVF exports for VirtualBox, etc. To know more about use cases of Packer click ([Use Cases - Introduction | Packer by HashiCorp](/packer/docs/intro/use-cases))
+
+The diagram below depicts the key Packer integration categories and types.
+
+
+
+
+
+
+
+Main Packer categories for partners to integrate with include:
+
+- **Data Sources**
+ - Data Sources allow users to retrieve values from a remote API and store them as variables in the Packer configuration template. An example is the [AWS secrets manager](/packer/plugins/datasources/amazon/secretsmanager) data source.
+- **Builders**
+ - Builders manage the VM lifecycle. They manage launching a VM/instance, running provisioners against that instance, shutting the instance down, and saving an artifact image from that instance. Your builder handles all of the setup and cleanup costs associated with creating the output image artifact.
+- **Provisioners**
+ - Provisioners are run against the instance launched by the builder. They generally provide an interface for interacting with a particular provisioning tool, such as Ansible, Puppet, or Chef.
+- **Post-Processors**
+ - Post-Processors manage the image artifact after it has been created. This can be something general like running a compression tool against the artifact, or something specific like uploading it to a particular cloud service.
+
+### Development Process
+
+The Packer integration development process is divided into six steps. By following these steps, Packer integrations can be developed alongside HashiCorp to ensure that the integrations are able to be verified and supported in Packer as quickly as possible. A visual representation of the self-guided steps is depicted below.
+
+
+
+The individual Packer integration steps include:
+
+1. Engage: Initial contact between vendor and HashiCorp
+1. Enable: Information and articles to aid with the development of the integration
+1. Dev/Test: Integration development and test process
+1. Review: HashiCorp code review and verification of integration (iterative process)
+1. Release: Verified integration made available and listed on the HashiCorp website once the HashiCorp technology partnership agreement has been executed
+1. Support: Ongoing maintenance and support of the provider by the vendor.
+
+#### 1. Engage
+
+Please begin by providing some basic information about the integration that is being built via a simple [webform](https://docs.google.com/forms/d/e/1FAIpQLSfgq3HJ9Rfsi7LgPLFln28ZrmarATGlD_6A47-Io-bPUftKUw/viewform)
+
+This information is recorded and used by HashiCorp to track the integration through various stages. The information is also used to notify the integration developer of any overlapping work, perhaps coming from the community so you may better focus resources.
+
+Packer has an active community and ecosystem of partners that may have already started working on a similar integration. We'll do our best to connect similar parties to avoid duplicate work.
+
+#### 2. Enable
+
+While not mandatory, HashiCorp encourages vendors to sign an MNDA (Mutual Non-Disclosure Agreement) to allow for open dialog and sharing of ideas during the integration process.
+
+In an effort to support our self-serve model we’ve included links to resources, documentation, examples and best practices to guide you through the Packer integration development and testing process.
+
+- [Writing vendor extension guide](/packer/docs/plugins/creation)
+- Sample development implemented by a [partner](https://github.com/exoscale/packer-plugin-exoscale)
+- [Scaffolding plugin repository](https://github.com/hashicorp/packer-plugin-scaffolding) to help bootstrap a new contribution:
+- Contributing to Packer [guidelines](https://github.com/hashicorp/packer/blob/main/.github/CONTRIBUTING.md)
+- [Packer developer community forum](https://discuss.hashicorp.com/c/packer/23)
+- [Packer's source code](https://github.com/hashicorp/packer)
+
+We encourage vendors to closely follow the above guidance. Adopting the same structure and coding patterns helps expedite the review and release cycles.
+
+#### 3. Dev & Test
+
+Packer requires all code-level integrations to be written in the [Go](https://go.dev/) programming language and contain an [MPL-2.0](https://en.wikipedia.org/wiki/Mozilla_Public_License) open source license. The only knowledge necessary to write a plugin is basic command-line skills and knowledge of the Go programming language. When writing in Go, HashiCorp has found the integration development process to be straightforward and simple when vendors pay close attention and follow the resources and by adopting the same structure and coding patterns helps expedite the review and release cycles. Please remember that all integration major steps should contain acceptance testing and the appropriate documentation.
+
+Data Sources
+
+- [Custom Data Sources documentation](/packer/docs/plugins/creation/custom-datasources)
+- [Example Data Source](https://github.com/hashicorp/packer-plugin-hashicups/tree/main/datasource)
+
+Builders
+
+- [Custom Builders documentation](/packer/docs/plugins/creation/custom-builders)
+- [Example Builder](https://github.com/hashicorp/packer-plugin-hashicups/tree/main/builder/order)
+
+Provisioners
+
+- [Custom Provisioners documentation](/packer/docs/plugins/creation/custom-provisioners)
+- [Example Provisioner](https://github.com/hashicorp/packer-plugin-hashicups/tree/main/provisioner/toppings)
+
+Post-Processors
+
+- [Custom Post-Processors documentation](/packer/docs/plugins/creation/custom-post-processors)
+- [Example Post-Processor](https://github.com/hashicorp/packer-plugin-hashicups/tree/main/post-processor/receipt)
+
+Packer-Plugin-SDK
+
+- The [Packer-plugin SDK](https://github.com/hashicorp/packer-plugin-sdk) contains tools to help plugin developers with common needs, like handling SSH connections or basic plugin architecture.
+
+#### 4. Review
+
+During the review process, HashiCorp will provide feedback on the newly developed integration. This is an important step to allow HashiCorp to review and verify your Packer integration. Please send the integration code and other relevant logs for verification to: [Packer-integration-dev@hashicorp.com](mailto:packer-integration-dev@hashicorp.com).
+
+In order to document your plugins with Packer, please submit a GitHub pull request (PR) against the [Packer project](https://github.com/hashicorp/packer). See [Registering Plugin Documentation](/packer/docs/plugins/creation#registering-plugin-documentation) for instructions on how to register your remote plugin documentation with Packer.
+The review process can take a while to complete and may require some iterations through the code to address any problems identified by the HashiCorp team.
+
+#### 5. Release
+
+At this stage, it is expected that the integration is fully complete, the necessary documentation has been written, the acceptance tests have all passed, and that HashiCorp has reviewed the integration. Once the plugin has been validated and accepted by HashiCorp, the plugin can be hosted on GitHub so it can easily be [downloaded then installed within Packer](/packer/docs/plugins/creation#creating-a-github-release).
+
+Once the integration has been released the vendor is requested to sign the HashiCorp Technology Partner Agreement so that we can have their integration be listed on the HashiCorp website.
+
+#### 6. Support
+
+Many vendors view the release step to be the end of the journey, while at HashiCorp we view it to be the beginning of the journey. Getting the integration built is just the first step in enabling users to leverage it against their infrastructure. Once development is completed, on-going effort is required to support the developed integration, maintain the plugin and address any issues in a timely manner.
+
+The expectation from the vendor/partner is to create a mechanism for them to track and resolve all issues on an ongoing basis. Vendors who choose to not support their integration will not be considered a verified integration and cannot be listed on the website.
+
+### Checklist
+
+Below is an ordered checklist of steps that should be followed during the integration process. This just reiterates the steps already documented in the sections above.
+
+
+
+- Fill out the Packer integration [webform](https://docs.google.com/forms/d/e/1FAIpQLSfgq3HJ9Rfsi7LgPLFln28ZrmarATGlD_6A47-Io-bPUftKUw/viewform)
+- Execute the HashiCorp MNDA (Mutual Non-Disclosure Agreement) if needed
+- Develop and test Packer integration along with the acceptance tests and documentation
+- Send email to [packer-integration-dev@hashicorp.com](mailto:packer-integration-dev@hashicorp.com) to schedule an initial review
+- Address review feedback and finalize the development process
+- Provide HashiCorp with credentials for underlying infrastructure for test purposes
+- Demo the integration and/or send the test logs to HashiCorp at: [packer-integration-dev@hashicorp.com](mailto:packer-integration-dev@hashicorp.com)
+- Execute HashiCorp Partner Agreement Documents, review logo guidelines, partner listing and more
+- Plan to continue supporting the integration with additional functionality and responding to customer issues.
+
+
+
+### Contact Us
+
+For any questions or feedback, please contact us at: packer-integration-dev@hashicorp.com.
diff --git a/content/packer/v1.10.x/content/docs/plugins/creation/custom-builders.mdx b/content/packer/v1.10.x/content/docs/plugins/creation/custom-builders.mdx
new file mode 100644
index 0000000000..efad53accd
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/creation/custom-builders.mdx
@@ -0,0 +1,310 @@
+---
+description: |
+ It is possible to write custom builders using the Packer plugin interface, and
+ this page documents how to do that.
+page_title: Custom Builders - Extending
+---
+
+# Custom Builders
+
+Packer builders are responsible for creating a virtual machine, setting the virtual machine up for provisioning, and then turning that provisioned virtual machine into a machine image. We officially maintain and distribute several builders, including builders to create images on Amazon EC2, VMware, Google
+Compute Engine, and many more. Refer to the [Builders](/packer/docs/builders) documentation for details.
+
+This page explains how to use the Packer plugin interface to write custom builders. If you want your builder to support HashiCorp Cloud Platform (HCP) Packer, you should also review the [HCP Packer Support](/packer/docs/plugins/creation/hcp-support) documentation.
+
+~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
+
+## Before You Begin
+
+We recommend reviewing the following resources before you begin development:
+
+- [Developing Plugins - Overview](/packer/docs/plugins/creation)
+- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language.
+
+## The Interface
+
+To create your own builder, you must create a struct that implements the
+[`packer.Builder`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#Builder) interface. It is reproduced below for reference.
+
+```go
+type Builder interface {
+ ConfigSpec() hcldec.ObjectSpec
+ Prepare(...interface{}) ([]string, []string, error)
+ Run(context.Context, ui Ui, hook Hook) (Artifact, error)
+}
+```
+
+### The "ConfigSpec" Method
+
+This method returns a hcldec.ObjectSpec, which is a spec necessary for using
+HCL2 templates with Packer. For information on how to use and implement this
+function, check our
+[object spec docs](/packer/guides/hcl/component-object-spec)
+
+### The "Prepare" Method
+
+The `Prepare` method for each builder will be called by the Packer core
+at the beginning of the build. Its purpose is to parse and validate the
+configuration template provided to Packer with `packer build your_packer_template.json`, but not to execute API calls or begin creating any
+resources or artifacts.
+
+The configuration from your Packer template is passed into the Prepare() method
+as an array of `interface{}` types, but is generally `map[string]interface{}`.
+The Prepare method is responsible for translating this configuration into an
+internal structure, validating it, and returning any errors.
+
+If multiple parameters are passed into Prepare(), they should be merged together
+into the final configuration, with later parameters overwriting any previous
+configuration. The exact semantics of the merge are left to the builder author.
+
+We recommend that you use the
+[mapstructure](https://godoc.org/github.com/mitchellh/mapstructure) library to
+decode the interface{} into a meaningful structure. Mapstructure will take an
+`interface{}` and decode it into an arbitrarily complex struct. If there are any
+errors, it generates very human friendly errors that can be returned directly
+from the prepare method. You can find many usage examples of this library within
+the Prepare() methods of HashiCorp-maintained Packer plugins.
+
+While Packer does not actively enforce this, **no side effects** should occur
+from running the `Prepare` method. Specifically: don't create files, don't
+launch virtual machines, etc. Prepare's purpose is solely to load the
+configuration from the template into a format usable by your builder, to
+validate that configuration, and to apply necessary defaults to that
+configuration.
+
+In addition to the configuration provided in the Packer template, Packer will
+also supply a [common.PackerConfig](https://github.com/hashicorp/packer-plugin-sdk/blob/8a28198491f70deca3824ce452adf6f9bd507880/common/packer_config.go#L44)
+containing meta-information such as the build name, builder type, core version,
+etc, and coded into a `map[string]interface{}`. One important piece of
+meta information in this map is the `packer.DebugConfigKey` set to boolean
+`true` if debug mode is enabled for the build. If this is set to true, then the
+builder should enable a debug mode which assists builder developers and
+advanced users to introspect what is going on during a build. During debug
+builds, parallelism is strictly disabled, so it is safe to request input from
+stdin and so on.
+
+Prepare() returns an array of strings and an error. The array of strings is a
+special list of keys for variables created at runtime which your builder will
+make accessible to provisioners using the generatedData mechanism (see below for
+more details) An example could be an instance ID for the cloud instance created
+by your builder. If you do not plan to make use of the generatedData feature,
+just return an empty list. The error should be used if there is something wrong
+with the user-provided configuration and the build should not proceed.
+
+### The "Run" Method
+
+`Run` is executed, often in parallel for multiple builders, to actually build
+the machine, provision it, and create the resulting machine image, which is
+returned as an implementation of the `packer.Artifact` interface.
+
+The `Run` method takes three parameters. The context.Context used to cancel the
+build. The `packer.Ui` object is used to send output to the console.
+`packer.Hook` is used to execute hooks, which are covered in more detail in the
+Provisioning section below.
+
+Because builder runs are typically a complex set of many steps, the
+packer-plugin-sdk contains a
+[multistep](https://godoc.org/github.com/hashicorp/packer-plugin-sdk/multistep)
+module. Multistep allows you to separate your build logic into multiple distinct
+"steps" with separate run and cleanup phases, and run them in order. It
+supports cancellation mid-step, pausing between steps when debugging, the CLI's
+on-error flag, and more. All of the HashiCorp maintained builders make use of
+this module, and while it is not required for builder implementation, it will
+help you create your builder in a way that matches user and Packer Core
+assumptions. The SDK also provides a number of "helper" generic steps that may
+prevent you from having to re-implement work that has already been done by the
+HashiCorp maintainers. Examples include sending boot commands, connecting to
+SSH, and creating virtual CDs to mount on your VM. Take a look at the
+[communicator](https://github.com/hashicorp/packer-plugin-sdk/tree/main/communicator)
+and
+[multistep/commonsteps](https://github.com/hashicorp/packer-plugin-sdk/tree/main/multistep/commonsteps)
+modules in the SDK to see what tools are available to you.
+
+Finally, `Run` should return an implementation of `packer.Artifact`. More
+details on creating a `packer.Artifact` are covered in the artifact section
+below. If something goes wrong during the build that prevents an artifact from
+being correctly created, `Run` should return an error and a nil artifact. Note
+that your builder is allowed to produce no artifact and no error, although this
+is a rare use case.
+
+### Cancellation
+
+#### With the "Cancel" Method ( for plugins for Packer < v1.3 )
+
+The `Cancel` method can be called at any time and requests cancellation of any
+builder run in progress. This method should block until the run actually stops.
+Note that the Cancel method will not be called by Packer versions >= 1.4.0.
+
+#### Context cancellation ( from Packer v1.4 )
+
+The `<-ctx.Done()` can unblock at any time and signifies request for
+cancellation of any builder run in progress.
+
+Cancels are most commonly triggered by external interrupts, such as the user
+pressing `Ctrl-C`. Packer will only exit once all the builders clean up, so it
+is important that you architect your builder in a way that it is quick to
+respond to these cancellations and clean up after itself. If your builder makes
+a long-running call, you should consider the possibility that a user may cancel
+the build during that call, and make sure that such a cancellation is not
+blocked.
+
+## Creating an Artifact
+
+The `Run` method is expected to return an implementation of the
+`packer.Artifact` interface. Each builder must create its own implementation of
+this interface.
+
+Most of the pieces of an artifact should be fairly self-explanatory by reading
+the [packer.Artifact interface
+documentation](https://godoc.org/github.com/hashicorp/packer-plugin-sdk/packer#Artifact).
+
+However one part of an artifact that may be confusing is the `BuilderId` method.
+This method must return an absolutely unique ID for the builder. In general, a
+reasonable ID would be the github username or organization that created the
+builder, followed by the platform it is building for. For example, the builder
+ID of the VMware builder is "hashicorp.vmware".
+
+Post-processors use the builder ID value in order to make some assumptions
+about the artifact results and to determine whether they are even able to run
+against a given artifact, so it is important that this ID never changes once
+the builder is published.
+
+The builder ID for each builder is included on the associated documentation page.
+
+## Provisioning
+
+Packer has built-in support for provisioning using the Provisioner plugins. But
+builders themselves, rather than the Packer core, must determine when to invoke
+the provisioners since only the builder knows when the machine is running and
+ready for communication.
+
+When the machine is ready to be provisioned, run the `packer.HookProvision`
+hook, making sure the communicator is not nil, since this is required for
+provisioners. An example of calling the hook is shown below:
+
+```go
+hook.Run(context.Context, packer.HookProvision, ui, comm, nil)
+```
+
+At this point, Packer will run the provisioners and no additional work is
+necessary.
+
+If you are using the multistep tooling, the Packer plugin SDK contains a
+generic StepProvision which handles execution the provision hook for you and
+automatically supplies any custom builder generatedData you would like to
+provide to provisioners (see below for more details on generatedData.)
+
+## Template Engine
+
+~> Note: In HCL2 the JSON template engine and generated data is slowly going to
+be deprecated in favor of using HCL2 objects, we will keep on supporting those
+but it is recommended to avoid using them if you can.
+
+### Build variables
+
+Packer JSON makes it possible to provide custom template engine variables to be
+shared with provisioners and post-processors using the `build` function.
+JSON template `build` docs are [here](/packer/docs/templates/legacy_json_templates/engine#build)
+and HCL template build docs are [here](/packer/docs/templates/hcl_templates/contextual-variables#build-variables).
+
+As of Packer v1.5.0, builder Prepare() methods return a list of custom variables
+which we call `generated data`. We use that list of variables to generate a
+custom placeholder map per builder that combines custom variables with the
+placeholder map of default build variables created by Packer. Here's an example
+snippet telling packer what will be made available by the builder:
+
+```go
+func (b *Builder) Prepare(raws ...interface{}) ([]string, []string, error) {
+ // ...
+
+ generatedData := []string{"SourceImageName"}
+ return generatedData, warns, nil
+}
+```
+
+When a user provides a Packer template that uses a `build` function, Packer
+validates that the key in the `build` function exists for a given builder using
+this generatedData array. If it does not exist, then Packer validation will
+fail.
+
+Once the placeholder is set, it's necessary to pass the variables' real values
+when calling the provisioner. This can be done as the example below:
+
+```go
+func (b *Builder) Run(ctx context.Context, ui packer.Ui, hook packer.Hook) (packer.Artifact, error) {
+ // ...
+
+ // Create map of custom variable
+ generatedData := map[string]interface{}{"SourceImageName": "the source image name value"}
+ // Pass map to provisioner
+ hook.Run(context.Context, packer.HookProvision, ui, comm, generatedData)
+
+ // ...
+}
+```
+
+In order to make these same variables and the Packer default ones also available
+to post-processors, your builder will need to add them to its Artifact.
+This can be done by adding an attribute of type `map[string]interface{}` to the
+Artifact and putting the generated data in it. The post-processor will access
+this data later via the Artifact's `State` method.
+
+The Artifact code should be implemented similar to the below:
+
+```go
+type Artifact struct {
+ // ...
+
+ // StateData should store data such as GeneratedData
+ // to be shared with post-processors
+ StateData map[string]interface{}
+}
+
+// ...
+
+func (a *Artifact) State(name string) interface{} {
+ return a.StateData[name]
+}
+
+// ...
+```
+
+The builder should return the above Artifact containing the generated data and
+the code should be similar to the example snippet below:
+
+```go
+func (b *Builder) Run(ctx context.Context, ui packer.Ui, hook packer.Hook) (packer.Artifact, error) {
+ // ...
+
+ return &Artifact{
+ // ...
+ StateData: map[string]interface{}{"generated_data": state.Get("generated_data")},
+ }, nil
+}
+```
+
+The code above assigns the `generated_data` state to the `StateData` map with
+the key `generated_data`.
+
+Here some example of how this data will be used by post-processors:
+
+```go
+func (p *PostProcessor) PostProcess(ctx context.Context, ui packer.Ui, source packer.Artifact) (packer.Artifact, bool, bool, error) {
+ generatedData := source.State("generated_data")
+
+ // generatedData will then be used for interpolation
+
+ // ...
+}
+```
+
+## Putting it all together
+
+This page has focused up until now on the implementation details for the Builder
+interface. You will need to create a server and store the builder in a binary in
+order to make it available to the Packer core as a plugin. We have created a
+[scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/builder/scaffolding/builder.go)
+repo to give you an idea of the relationship between the builder
+implementation and the server implementation within a repository, and then read
+[basics of how Plugins work](/packer/docs/plugins/install-plugins), which breaks down all the
+server details.
diff --git a/content/packer/v1.10.x/content/docs/plugins/creation/custom-datasources.mdx b/content/packer/v1.10.x/content/docs/plugins/creation/custom-datasources.mdx
new file mode 100644
index 0000000000..1111ac20c9
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/creation/custom-datasources.mdx
@@ -0,0 +1,95 @@
+---
+description: >
+ Packer Data Sources are the components of Packer that allow data to be fetched for use within the Packer configuration.
+ Use of data sources allows a build to use information defined outside of Packer.
+page_title: Custom Data Sources - Extending
+---
+
+# Custom Data Sources
+
+Packer data sources let Packer fetch data to use within the configuration, including information defined outside of Packer. For example, the [amazon-ami data source](/packer/plugins/datasources/amazon/ami), outputs the data from an Amazon AMI.
+
+Data Source plugins implement the `packersdk.Datasource` interface and are registered within a plugin Set
+with `set.RegisterDatasource(...)` function and served using the `set.Run()`.
+
+~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
+
+## Before You Begin
+
+We recommend reviewing the following resources before you begin development:
+
+- [Developing Plugins - Overview](/packer/docs/plugins/creation)
+- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language.
+
+## The Interface
+
+The interface that must be implemented for a datasource is the
+`packersdk.Datasource` interface. It is reproduced below for reference. The
+actual interface in the source code contains some basic documentation as well
+explaining what each method should do.
+
+```go
+type Datasource interface {
+ ConfigSpec() hcldec.ObjectSpec
+ OutputSpec() hcldec.ObjectSpec
+ Configure(...interface{}) error
+ Execute() (cty.Value, error)
+}
+```
+
+### The "ConfigSpec" Method
+
+This method returns a hcldec.ObjectSpec, which is a spec necessary for using
+HCL2 templates with Packer. For information on how to use and implement this
+function, check our
+[object spec docs](/packer/guides/hcl/component-object-spec)
+
+### The "OutputSpec" Method
+
+This method returns a [hcldec.ObjectSpec](/packer/guides/hcl/component-object-spec) of the data source output.
+The object spec can be generated using the command [`packer-sdc mapstructure-to-hcl2`](https://github.com/hashicorp/packer-plugin-sdk/tree/main/cmd/packer-sdc)
+just like the configuration spec for the `ConfigSpec` method.
+
+This method is used in `packer validate` command. Packer will use the spec to assign
+unknown values to the data source, instead of executing it and fetching real values.
+
+### The "Configure" Method
+
+The `Configure` method is called prior to any runs with the configuration that was given in the template.
+This is passed in as an array of `interface{}` types, but is generally `map[string]interface{}`. The Configure
+method is responsible for translating this configuration into an internal structure, validating it,
+and returning any errors.
+
+For multiple parameters, they should be merged together into the final
+configuration, with later parameters overwriting any previous configuration.
+The exact semantics of the merge are left to the builder author.
+
+For decoding the `interface{}` into a meaningful structure, the
+[mapstructure](https://github.com/mitchellh/mapstructure) library is
+recommended. Mapstructure will take an `interface{}` and decode it into an
+arbitrarily complex struct. If there are any errors, it generates very human
+friendly errors that can be returned directly from the Configure method.
+
+While it is not actively enforced, **no side effects** should occur from
+running the `Configure` method. Specifically, don't create files, don't launch
+virtual machines, etc. Configure's purpose is solely to configure the data source and
+validate the configuration.
+
+The `Configure` method is called very early in the build process so that errors
+may be displayed to the user before anything actually happens.
+
+### The "Execute" Method
+
+This method returns an HCL cty.Value and an error. Packer will run the Execute method on `packer build` command
+so that the data source output will be available prior to evaluating build and locals blocks. Is expected that the
+Execute command will fetch the data and return it as a cty.Value.
+
+To get the equivalent cty.Value from an output config, we suggest using our
+[packer-plugin-sdk hcl2helper functions](https://github.com/hashicorp/packer-plugin-sdk/blob/v0.0.7/hcl2helper/values.go).
+
+## Scaffolding template
+
+To make your experience easier when developing your new data source plugin, we provide you a
+[Packer plugin scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding)
+to use as a template to your plugin repository. The template is structure with the basics and contain the necessary
+configuration to start creating your own plugin.
diff --git a/content/packer/v1.10.x/content/docs/plugins/creation/custom-post-processors.mdx b/content/packer/v1.10.x/content/docs/plugins/creation/custom-post-processors.mdx
new file mode 100644
index 0000000000..4a20496d2a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/creation/custom-post-processors.mdx
@@ -0,0 +1,107 @@
+---
+description: >
+ Packer Post-processors are the components of Packer that transform one
+ artifact
+
+ into another, for example by compressing files, or uploading them.
+page_title: Custom Post-Processors - Extending
+---
+
+# Custom Post-Processors
+
+Packer post-processors transform one artifact into another. For example, a post-processor might compress or upload files.
+
+In the compression example, the transformation would be taking an artifact with
+a set of files, compressing those files, and returning a new artifact with only
+a single file (the compressed archive). For the upload example, the
+transformation would be taking an artifact with some set of files, uploading
+those files, and returning an artifact with a single ID: the URL of the upload.
+
+Post-processor plugins implement the [`packer.PostProcessor`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#PostProcessor) interface and are
+served using the `plugin.ServePostProcessor` function.
+
+This page explains how to implement and serve custom post-processors. If you want your post-processor to support HashiCorp Cloud Platform (HCP) Packer, you should also review the [HCP Packer Support](/packer/docs/plugins/creation/hcp-support) documentation.
+
+~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
+
+## Before You Begin
+
+We recommend reviewing the following resources before you begin development:
+- [Developing Plugins - Overview](/packer/docs/plugins/creation)
+- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language.
+
+## The Interface
+
+The interface that must be implemented for a post-processor is the
+[`packer.PostProcessor`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#PostProcessor) interface. It is reproduced below for reference. The
+actual interface in the source code contains some basic documentation as well
+explaining what each method should do.
+
+```go
+type PostProcessor interface {
+ ConfigSpec() hcldec.ObjectSpec
+ Configure(interface{}) error
+ PostProcess(context.Context, Ui, Artifact) (a Artifact, keep, mustKeep bool, err error)
+}
+```
+
+### The "ConfigSpec" Method
+
+This method returns a hcldec.ObjectSpec, which is a spec necessary for using
+HCL2 templates with Packer. For information on how to use and implement this
+function, check our
+[object spec docs](/packer/guides/hcl/component-object-spec)
+
+### The "Configure" Method
+
+The `Configure` method for each post-processor is called early in the build
+process to configure the post-processor. The configuration is passed in as a
+raw `interface{}`. The configure method is responsible for translating this
+configuration into an internal structure, validating it, and returning any
+errors.
+
+For decoding the `interface{}` into a meaningful structure, the
+[mapstructure](https://github.com/mitchellh/mapstructure) library is
+recommended. Mapstructure will take an `interface{}` and decode it into an
+arbitrarily complex struct. If there are any errors, it generates very
+human-friendly errors that can be returned directly from the configure method.
+
+While it is not actively enforced, **no side effects** should occur from
+running the `Configure` method. Specifically, don't create files, don't create
+network connections, etc. Configure's purpose is solely to setup internal state
+and validate the configuration as much as possible.
+
+`Configure` being run is not an indication that `PostProcess` will ever run.
+For example, `packer validate` will run `Configure` to verify the configuration
+validates, but will never actually run the build.
+
+### The "PostProcess" Method
+
+The `PostProcess` method is where the real work goes. PostProcess is
+responsible for taking one `packer.Artifact` implementation, and transforming
+it into another.
+A `PostProcess` call can be cancelled at any moment. Cancellation is triggered
+when the done chan of the context struct (`<-ctx.Done()`) unblocks .
+
+When we say "transform," we don't mean actually modifying the existing
+`packer.Artifact` value itself. We mean taking the contents of the artifact and
+creating a new artifact from that. For example, if we were creating a
+"compress" post-processor that is responsible for compressing files, the
+transformation would be taking the `Files()` from the original artifact,
+compressing them, and creating a new artifact with a single file: the
+compressed archive.
+
+The result signature of this method is `(Artifact, bool, bool, error)`. Each
+return value is explained below:
+
+- `Artifact` - The newly created artifact if no errors occurred.
+- `bool` - If keep true, the input artifact will forcefully be kept. By default,
+ Packer typically deletes all input artifacts, since the user doesn't
+ generally want intermediary artifacts. However, some post-processors depend
+ on the previous artifact existing. If this is `true`, it forces packer to
+ keep the artifact around.
+- `bool` - If forceOverride is true, then any user input for
+ keep_input_artifact is ignored and the artifact is either kept or discarded
+ according to the value set in `keep`.
+- `error` - Non-nil if there was an error in any way. If this is the case,
+ the other two return values are ignored.
diff --git a/content/packer/v1.10.x/content/docs/plugins/creation/custom-provisioners.mdx b/content/packer/v1.10.x/content/docs/plugins/creation/custom-provisioners.mdx
new file mode 100644
index 0000000000..30bb8312a2
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/creation/custom-provisioners.mdx
@@ -0,0 +1,127 @@
+---
+description: >
+ Packer Provisioners are the components of Packer that install and configure
+
+ software into a running machine prior to turning that machine into an image.
+ An
+
+ example of a provisioner is the shell provisioner, which runs shell scripts
+
+ within the machines.
+page_title: Custom Provisioners - Extending
+---
+
+# Custom Provisioners
+
+Packer provisioners install and configure software into a running machine prior to turning that machine into an image. For example, the [shell
+provisioner](/packer/docs/provisioners/shell), which runs shell scripts within
+the machines.
+
+Provisioner plugins implement the [`packer.Provisioner`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#Provisioner) interface and are served
+using the `plugin.ServeProvisioner` function.
+
+~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
+
+## Before You Begin
+
+We recommend reviewing the following resources before you begin development:
+- [Developing Plugins - Overview](/packer/docs/plugins/creation)
+- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language.
+
+## The Interface
+
+The interface that must be implemented for a provisioner is the
+[`packer.Provisioner`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#Provisioner) interface. It is reproduced below for reference. The
+actual interface in the source code contains some basic documentation as well
+explaining what each method should do.
+
+```go
+type Provisioner interface {
+ ConfigSpec() hcldec.ObjectSpec
+ Prepare(...interface{}) error
+ Provision(context.Context, Ui, Communicator, map[string]interface{}) error
+}
+```
+
+### The "Prepare" Method
+
+The `Prepare` method for each provisioner is called prior to any runs with the
+configuration that was given in the template. This is passed in as an array of
+`interface{}` types, but is generally `map[string]interface{}`. The prepare
+method is responsible for translating this configuration into an internal
+structure, validating it, and returning any errors.
+
+For multiple parameters, they should be merged together into the final
+configuration, with later parameters overwriting any previous configuration.
+The exact semantics of the merge are left to the builder author.
+
+For decoding the `interface{}` into a meaningful structure, the
+[mapstructure](https://github.com/mitchellh/mapstructure) library is
+recommended. Mapstructure will take an `interface{}` and decode it into an
+arbitrarily complex struct. If there are any errors, it generates very human
+friendly errors that can be returned directly from the prepare method.
+
+While it is not actively enforced, **no side effects** should occur from
+running the `Prepare` method. Specifically, don't create files, don't launch
+virtual machines, etc. Prepare's purpose is solely to configure the builder and
+validate the configuration.
+
+The `Prepare` method is called very early in the build process so that errors
+may be displayed to the user before anything actually happens.
+
+### The "ConfigSpec" Method
+
+This method returns a hcldec.ObjectSpec, which is a spec necessary for using
+HCL2 templates with Packer. For information on how to use and implement this
+function, check our
+[object spec docs](/packer/guides/hcl/component-object-spec)
+
+### The "Provision" Method
+
+The `Provision` method is called when a machine is running and ready to be
+provisioned. The provisioner should do its real work here.
+
+The method takes two parameters: a `packer.Ui` and a `packer.Communicator`. The
+UI can be used to communicate with the user what is going on. The communicator
+is used to communicate with the running machine, and is guaranteed to be
+connected at this point.
+
+The provision method should not return until provisioning is complete.
+
+The map[string]interface{} provides users with build-specific information,
+like host and IP, provided by the `build` template engine. Provisioners may use
+this information however they please, or not use it.
+
+## Using the Communicator
+
+The `packer.Communicator` parameter and interface is used to communicate with
+running machine. The machine may be local (in a virtual machine or container of
+some sort) or it may be remote (in a cloud). The communicator interface
+abstracts this away so that communication is the same overall.
+
+The documentation around the [code
+itself](https://godoc.org/github.com/hashicorp/packer-plugin-sdk/packer#Communicator)
+is really great as an overview of how to use the interface. You should begin by
+reading this. Once you have read it, you can see some example usage below:
+
+```go
+// Build the remote command.
+var cmd packer.RemoteCmd
+cmd.Command = "echo foo"
+
+// We care about stdout, so lets collect that into a buffer. Since
+// we don't set stderr, that will just be discarded.
+var stdout bytes.Buffer
+cmd.Stdout = &stdout
+
+// Start the command
+if err := comm.Start(&cmd); err != nil {
+ panic(err)
+}
+
+// Wait for it to complete
+cmd.Wait()
+
+// Read the stdout!
+fmt.Printf("Command output: %s", stdout.String())
+```
diff --git a/content/packer/v1.10.x/content/docs/plugins/creation/hcp-support.mdx b/content/packer/v1.10.x/content/docs/plugins/creation/hcp-support.mdx
new file mode 100644
index 0000000000..ed65ae15aa
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/creation/hcp-support.mdx
@@ -0,0 +1,115 @@
+---
+description: |
+ HCP Packer support allows plugins to manage image metadata that can be stored in a HCP Packer registry.
+page_title: HCP Packer Support
+---
+
+# HCP Packer Support
+
+~> **Note:** HCP Packer is under active development, and we suggest plugin maintainers to keep up with the SDK changes
+for more on HCP Packer support.
+
+This page explains how to update a custom plugin so that it can publish image metadata to the [HCP Packer registry](/hcp/docs/packer). Refer to [Custom Builders](/packer/docs/plugins/creation/custom-builders) and [Custom Post-Processors](/packer/docs/plugins/creation/custom-post-processors) for details about creating an external Packer plugin.
+
+Before pushing metadata to the HCP Packer registry, Packer uses the [`par.artifact.metadata` key](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-constants)
+to query a builder artifact for the image metadata that a particular component would like to have stored in the registry.
+
+For details and examples of how to manage image metadata, refer to the [HCP Packer GitHub documentation](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image).
+
+## Builder Artifact
+
+To support HCP Packer, changes must be made to the plugin's build artifact. The artifact should keep the appropriate
+Image metadata in state under the key `par.artifact.metadata`. The expected key is provided by the [image.ArtifactStateURI](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-constants) constant.
+
+To make HCP Packer support easier, we ship an Image package with the [packer-plugin-sdk](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-overview).
+We provide the [`FromArtifact`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#FromArtifact) function
+to easily create an Image with the basic information contained in the Artifact. If customization is necessary, the `FromArtifact` accepts
+override functions as the second argument, and that can be used to set different values for the metadata.
+
+The [Image metadata](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#Image) must contain every
+metadata HCP Packer should store about this component. The structure is:
+```go
+// Image represents the metadata for some Artifact in the HCP Packer Registry.
+type Image struct {
+ // ImageID is a unique reference identifier stored on the HCP Packer registry
+ // that can be used to get back the built artifact of a builder or post-processor.
+ ImageID string
+ // ProviderName represents the name of the top level cloud or service where the built artifact resides.
+ // For example "aws, azure, docker, gcp, and vsphere".
+ ProviderName string
+ // ProviderRegion represents the location of the built artifact.
+ // For cloud providers region usually maps to a cloud region or zone, but for things like the file builder,
+ // S3 bucket or vsphere cluster region can represent a path on the upstream datastore, or cluster.
+ ProviderRegion string
+ // Labels represents additional details about an image that a builder or post-processor may with to provide for a given build.
+ // Any additional metadata will be made available as build labels within a HCP Packer registry iteration.
+ Labels map[string]string
+ // SourceImageID is the cloud image ID of the image that was used as the
+ // source for this image. If set, the HCP Packer registry will be able
+ // link the parent and child images for ancestry visualizations and
+ // dependency tracking.
+ SourceImageID string
+}
+```
+
+Where `ImageID`, `ProviderName`, and `SourceImageID` are mandatory fields.
+
+Examples using the `FromArtifact` method:
+
+- Simple form:
+```go
+func (a *Artifact) State(name string) interface{} {
+ if name == registryimage.ArtifactStateURI {
+ img, err := registryimage.FromArtifact(a)
+ if err != nil {
+ log.Printf("[DEBUG] error encountered when creating a registry image %v", err)
+ return nil
+ }
+ return img
+ }
+ return a.StateData[name]
+}
+```
+
+- Using overrides:
+```go
+func (a *Artifact) State(name string) interface{} {
+ if name == registryimage.ArtifactStateURI {
+ img, err := registryimage.FromArtifact(a,
+ registryimage.WithID(a.Name),
+ registryimage.WithRegion(a.Region.Name()),
+ registryimage.WithProvider("happy-cloud"),
+ registryimage.WithSourceID(a.SourceID),
+ registryimage.SetLabels(a.Labels),
+ )
+ if err != nil {
+ log.Printf("[DEBUG] error encountered when creating a registry image %v", err)
+ return nil
+ }
+ return img
+ }
+ return a.StateData[name]
+}
+```
+
+See [packer-plugin-sdk/packer/registry/image](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-examples) for additional examples.
+
+### SDK Version
+
+- The HCP Packer support is available from packer-plugin-sdk >= v0.2.7
+
+## Plugins Example
+
+The following plugins currently support HCP Packer and are great references for development:
+
+- [packer-plugin-amazon](https://github.com/hashicorp/packer-plugin-amazon)
+- [packer-plugin-azure](https://github.com/hashicorp/packer-plugin-azure)
+- [packer-plugin-vsphere](https://github.com/hashicorp/packer-plugin-vsphere)
+- [packer-plugin-docker](https://github.com/hashicorp/packer-plugin-docker)
+- [packer-plugin-googlecompute](https://github.com/hashicorp/packer-plugin-googlecompute)
+
+## HCP Packer
+
+To get to know HCP Packer, visit the
+[HCP Packer documentation](/hcp/docs/packer) or try the
+[Get Started with HCP Packer tutorials](/packer/tutorials/hcp-get-started).
diff --git a/content/packer/v1.10.x/content/docs/plugins/creation/index.mdx b/content/packer/v1.10.x/content/docs/plugins/creation/index.mdx
new file mode 100644
index 0000000000..763877aa0f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/creation/index.mdx
@@ -0,0 +1,269 @@
+---
+description: |
+ Packer is designed to be extensible. Because the surface area for workloads is
+ infinite, Packer supports plugins for builders, provisioners, and
+ post-processors.
+page_title: Extending
+---
+
+# Developing Plugins
+
+Packer is extensible and supports plugins that let you
+create and use custom builders, provisioners, post-processors, and data sources. This page explains how to develop Packer plugins. Before you begin, we recommend reviewing the Packer documentation and the instructions for [installing external plugins](https://developer.hashicorp.com/packer/docs/plugins/install-plugins).
+
+~> **Warning** This is an advanced topic. You should have strong knowledge of Packer before you start writing plugins.
+
+## Language Requirements
+
+You must write Packer plugins in [Go](https://go.dev/).
+
+
+## Plugin System Architecture
+
+A Packer plugin is just a Go binary. Instead of loading plugins directly into a
+running application, Packer runs each plugin as a _separate application_.
+The multiple separate Packer plugin processes communicate with the Core using
+an RPC defined in the packer-plugin SDK. The Packer core itself is responsible
+launching and cleaning up the plugin processes.
+
+## Plugin Development Basics
+
+The components that can be created and used in a Packer plugin are builders,
+provisioners, post-processors, and data sources.
+
+Each of these components has a corresponding [interface](https://go.dev/doc/effective_go.html#interfaces_and_types).
+
+All you need to do to create a plugin is:
+
+1. create an implementation of the desired interface, and
+2. serve it using the server provided in the [packer-plugin-sdk](https://github.com/hashicorp/packer-plugin-sdk).
+
+The core and the SDK handle all of the communication details inside the server.
+
+Your plugin must use two packages from the SDK to implement the server and
+interfaces. You're encouraged to use whatever other packages you want in your
+plugin implementation. Because plugins are their own processes, there is no
+danger of colliding dependencies.
+
+- [`github.com/hashicorp/packer-plugin-sdk/packer`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer) - Contains all the interfaces that you have to implement for any given plugin.
+
+- [`github.com/hashicorp/packer-plugin-sdk/plugin`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/plugin) - Contains the code to serve the plugin. This handles all the inter-process communication.
+
+Basic examples of serving your component are shown below.
+
+```go
+// main.go
+
+import (
+ "github.com/hashicorp/packer-plugin-sdk/plugin"
+)
+
+// Assume this implements the packer.Builder interface
+type ExampleBuilder struct{}
+
+// Assume this implements the packer.PostProcessor interface
+type FooPostProcessor struct{}
+
+// Assume this implements the packer.Provisioner interface
+type BarProvisioner struct{}
+
+func main() {
+ pps := plugin.NewSet()
+ pps.RegisterBuilder("example", new(ExampleBuilder))
+ pps.RegisterBuilder(plugin.DEFAULT_NAME, new(AnotherBuilder))
+ pps.RegisterPostProcessor("foo", new(FooPostProcessor))
+ pps.RegisterProvisioner("bar", new(BarProvisioner))
+ err := pps.Run()
+ if err != nil {
+ fmt.Fprintln(os.Stderr, err.Error())
+ os.Exit(1)
+ }
+}
+```
+
+This `plugin.NewSet` invocation handles all the details of communicating with
+Packer core and serving your component over RPC. As long as your struct being
+registered implements one of the component interfaces, Packer will now be able
+to launch your plugin and use it.
+
+If you register a component with its own name, the component name will be
+appended to the plugin name to create a unique name. If you register a component
+using the special string constant `plugin.DEFAULT_NAME`, then the component will
+be referenced by using only the plugin name. For example:
+
+If your plugin is named `packer-plugin-my`, the above set definition would make
+the following components available:
+
+- the `my-example` builder
+- the `my` builder
+- the `my-foo` post-processor
+- the `my-bar` provisioner
+
+Next, build your plugin as you would any other Go application. The resulting
+binary is the plugin that can be installed using
+[standard installation procedures](https://developer.hashicorp.com/packer/docs/plugins#installing-plugins).
+
+This documentation explains how to implement each type of plugin interface: builders, data sources, provisioners, and post-processors.
+
+~> **Lock your dependencies!** Using `go mod` is highly recommended since
+the Packer codebase will continue to improve, potentially breaking APIs along
+the way until there is a stable release. By locking your dependencies, your
+plugins will continue to work with the version of Packer you lock to.
+
+## Logging and Debugging
+
+Plugins can use the standard Go `log` package to log. Anything logged using
+this will be available in the Packer log files automatically. The Packer log is
+visible on stderr when the `PACKER_LOG` environment var is set.
+
+Packer will prefix any logs from plugins with the path to that plugin to make
+it identifiable where the logs come from. Some example logs are shown below:
+
+```text
+2013/06/10 21:44:43 Loading builder: custom
+2013/06/10 21:44:43 packer-builder-custom: 2013/06/10 21:44:43 Plugin minimum port: 10000
+2013/06/10 21:44:43 packer-builder-custom: 2013/06/10 21:44:43 Plugin maximum port: 25000
+2013/06/10 21:44:43 packer-builder-custom: 2013/06/10 21:44:43 Plugin address: :10000
+```
+
+As you can see, the log messages from the custom builder plugin are prefixed
+with "packer-builder-custom". Log output is _extremely_ helpful in debugging
+issues and you're encouraged to be as verbose as you need to be in order for
+the logs to be helpful.
+
+### Creating a GitHub Release
+
+`packer init` does not work using a centralized registry. Instead, it requires
+you to publish your plugin in a GitHub repo with the name
+`packer-plugin-*` where \* represents the name of your plugin. You also need to
+create a GitHub release of your plugin with specific assets for the
+`packer init` download to work. We provide a pre-defined release workflow
+configuration using
+[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions). We
+strongly encourage maintainers to use this configuration to make sure the
+release contains the right assets with the right names for Packer to leverage
+`packer init` installation.
+
+Here's what you need to create releases using GitHub Actions:
+
+1. Generate a GPG key to be used when signing releases (See [GitHub's detailed instructions](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-gpg-key)
+ for help with this step)
+2. Copy the [GoReleaser configuration from the packer-plugin-scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.goreleaser.yml) to the root of your repository.
+ ```sh
+ curl -L -o .goreleaser.yml \
+ https://raw.githubusercontent.com/hashicorp/packer-plugin-scaffolding/main/.goreleaser.yml
+ ```
+3. Copy the [GitHub Actions workflow from the packer-plugin-scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.github/workflows/release.yml) to `.github/workflows/release.yml` in your repository.
+ ```sh
+ mkdir -p .github/workflows &&
+ curl -L -o .github/workflows/release.yml \
+ https://raw.githubusercontent.com/hashicorp/packer-plugin-scaffolding/main/.github/workflows/release.yml
+ ```
+4. Go to your repository page on GitHub and navigate to Settings > Secrets. Add
+ the following secrets:
+ - `GPG_PRIVATE_KEY` - Your ASCII-armored GPG private key. You can export this with `gpg --armor --export-secret-keys [key ID or email]`.
+ - `GPG_PASSPHRASE` - The passphrase for your GPG private key.
+5. Push a new valid version tag (e.g. `v1.2.3`) to test that the GitHub Actions
+ releaser is working. The tag must be a valid
+ [Semantic Version](https://semver.org/) preceded with a `v`. Once the tag is pushed, the github actions you just configured will automatically build release binaries that Packer can download using `packer init`. For more details on how
+ to install a plugin using `packer init`, see the
+ [init docs](https://developer.hashicorp.com/packer/docs/commands/init).
+
+## Registering Plugins
+
+~> Note: Registering a plugin as an integration requires the documentation to match the [Scaffolding example layout](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/.web-docs).
+
+To help with the discovery of Packer plugins, plugins maintainers can choose to register their plugin as a [Packer Integration](https://developer.hashicorp.com/packer/integrations).
+
+The registration process requires [metadata configuration](https://github.com/hashicorp/integration-template#metadata-configuration) to be added to your plugin repository for configuring the Packer integration pipeline and
+a specific directory structure for plugin documentation to be rendered on the [Packer Integrations](https://developer.hashicorp.com/packer/integrations) portal.
+
+You can execute the following steps to register your plugin as an integration:
+
+1. Update your plugin documentation structure to match the [Scaffolding example layout](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/.web-docs).
+New plugins generated from this template have the necessary structure in place. If so you can jump to step 3.
+1. For the integrations library, only one top-level README per integration is supported. Any top-level index.mdx files that exist
+within a plugin's existing documentation will need to migrate to a top-level README.
+1. Update your top-level integration README to include a description, plugin installation steps, available components section, and, any, additional sections
+needed to inform users on how to work with your integration. Refer to [Packer scaffolding plugin](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/docs/README.md) for an example.
+1. Update the top-level README for each of the components within your integration to follow the structure defined in the scaffolding template.
+1. Add the integration configuration file [metadata.hcl](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.web-docs/metadata.hcl) to the plugins `.web-docs` directory.
+1. Open a request for integration issue with the Packer team - [Open Request](https://github.com/hashicorp/packer/issues/new?labels=new-plugin-contribution&template=plugin_integration.md).
+Provide all the requested information to help expedite the integration request.
+
+#### [Example] Add integration files to existing plugin repository
+
+```shell
+## Update Plugin repository with integration config, workflows, and scripts
+cd packer-plugin-name
+mkdir -p .web-docs/scripts
+
+# Download packer-plugin-scaffolding repo copy files
+wget https://github.com/hashicorp/packer-plugin-scaffolding/archive/refs/heads/main.zip
+unzip main.zip
+cp packer-plugin-scaffolding-main/.web-docs/metadata.hcl .web-docs/
+cp -r packer-plugin-scaffolding-main/.web-docs/scripts/ .web-docs/scripts/
+cp packer-plugin-scaffolding-main/.github/workflows/notify-integration-release-via-* .github/workflows/
+
+# Remove downloaded scaffolding project
+rm main.zip
+rm -rf packer-plugin-scaffolding-main
+
+# Add the following commands to your plugin GNUmakefile
+generate: install-packer-sdc
+ @go generate ./...
+ @rm -rf .docs
+ @packer-sdc renderdocs -src docs -partials docs-partials/ -dst .docs/
+ @./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" ""
+ @rm -r ".docs"
+```
+
+By opening an integration request, you are asking a member of the to Packer team to review your plugin integration configuration, plugin documentation,
+and, finally, to open an internal pull-request to finalize the integration setup.
+
+Plugin integrations will be listed as a [Packer Integration](https://developer.hashicorp.com/packer/integrations), with details on how to install and use your the plugin.
+
+Plugin integrations, once deployed, can be updated manually, or automatically upon a new release, by the plugin authors. Changes to the defined documentation structure
+or parent repository should be communicated to the Packer team to ensure a working integration pipeline.
+
+## Plugin Development Tips and FAQs
+
+### Working Examples
+
+Here's a non-exhaustive list of Packer plugins that you can check out:
+
+- [github.com/hashicorp/packer-plugin-docker](https://github.com/hashicorp/packer-plugin-docker)
+- [github.com/exoscale/packer-plugin-exoscale](https://github.com/exoscale/packer-plugin-exoscale)
+- [github.com/sylviamoss/packer-plugin-comment](https://github.com/sylviamoss/packer-plugin-comment)
+
+Looking at their code will give you good examples.
+
+### Naming Conventions
+
+It is standard practice to name the resulting plugin application in the format
+of `packer-plugin-NAME`. For example, if you're building a new builder for
+CustomCloud, it would be standard practice to name the resulting plugin
+`packer-plugin-customcloud`. This naming convention helps users identify the
+scope of a plugin.
+
+### Testing Plugins
+
+Making your unpublished plugin available to Packer is possible by either:
+
+- Starting Packer from the directory where the plugin binary is located.
+- Putting the plugin binary in the same directory as Packer.
+
+In both these cases, if the binary is called `packer-plugin-myawesomecloud` and
+defines an `ebs` builder then you will be able to use an `myawesomecloud-ebs`
+builder or source without needing to have a `required_plugin` block.
+
+This is extremely useful during development.
+
+### Distributing Plugins
+
+We recommend that you use a tool like the GoReleaser in order to cross-compile
+your plugin for every platform that Packer supports, since Go applications are
+platform-specific. If you have created your plugin from the
+[packer-plugin-scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding)
+repo, simply tagging a commit and pushing the tag to GitHub will correctly build
+and release the binaries using GoReleaser.
diff --git a/content/packer/v1.10.x/content/docs/plugins/index.mdx b/content/packer/v1.10.x/content/docs/plugins/index.mdx
new file mode 100644
index 0000000000..4a11840d1b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/index.mdx
@@ -0,0 +1,21 @@
+---
+description: |
+ Packer plugins let you add Packer functionality without modifying
+ the core source code. Packer plugins are able to add new builders,
+ provisioners, hooks, and more.
+page_title: Plugins
+---
+
+# Packer Plugins
+
+Packer plugins are separate, standalone applications that perform tasks during each build.
+
+During a `packer build`, the process list shows `packer-` prefixed applications. One of those applications is the Packer binary, and the rest are plugins. Packer launches one plugin process for each component in the build.
+
+The Packer binary has a set of built-in plugins that it can find and run automatically. You can also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code.
+
+Refer to the following plugin documentation:
+- **Built-in Plugins:** Use [builders](/packer/docs/builders) to create machines and images, [data sources](/packer/docs/datasources) to fetch data, [provisioners](/packer/docs/provisioners) to install and configure machine images, and [post-processors](/packer/docs/post-processors) to perform additional tasks after provisioning
+- **External Plugins:** Review the documentation for [available external plugins](/packer/plugins) not included with the Packer binary
+- **Installing Plugins:** [Installation Guides](/packer/docs/plugins/install-plugins) to add external plugins to your Packer template and install the binaries
+- **Developing Plugins:** Get started [creating custom external plugins](/packer/docs/plugins/creation)
\ No newline at end of file
diff --git a/content/packer/v1.10.x/content/docs/plugins/install-plugins.mdx b/content/packer/v1.10.x/content/docs/plugins/install-plugins.mdx
new file mode 100644
index 0000000000..2413d025ff
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/plugins/install-plugins.mdx
@@ -0,0 +1,241 @@
+---
+description: |
+ Install external Packer plugins that extend Packer functionality.
+page_title: Install Plugins
+---
+
+# Installing Plugins
+
+Packer plugins are separate, standalone applications that perform tasks during each build.
+
+You do not need to install the components that ship with the Packer binary.
+Packer automatically knows how to find and launch these built-in plugins.
+
+This page explains how to install custom external plugins. Refer to [External Plugins](/packer/integrations) for a list of available plugins and their documentation.
+
+Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ.
+
+If you're using HCL2, `packer init` is recommended as you can install all your requirements with one
+command, and those requirements are explicitly documented in the template.
+
+`packer plugins install` is also used to automate the installation from a source, and will need to
+be repeated for as many plugins as you need.
+We recommend this for JSON as the template cannot contain the information about the required plugins.
+
+Finally, you can manually install any plugin. This is mostly useful if you're in an environment with
+restricted internet access, or if you're installing non-final versions of plugins.
+
+Refer to the [Installation Guides](#installation-guides) section of this page for information about
+each, including usage examples.
+
+The remainder of this document will serve as documentation on how Packer interacts with plugins.
+We encourage you to read this to get familiar with this process, as it will help you troubleshoot
+your builds if you encounter problems with that.
+
+## Source Addresses
+
+A plugin's source address is its global identifier. It also tells Packer where
+to download it.
+
+Source addresses consist of three parts delimited by slashes (`/`), as
+follows:
+
+`//`
+
+- **Hostname:** The hostname of the location/service that
+ distributes the plugin. Currently, the only valid "hostname" is github.com,
+ but we plan to eventually support plugins downloaded from other domains.
+
+- **Namespace:** An organizational namespace within the specified host.
+ This often is the organization that publishes the plugin.
+
+- **Type:** A short name for the platform or system the plugin manages. The
+ type is usually the plugin's preferred local name.
+
+For example, the fictional `myawesomecloud` plugin could belong to the
+`hashicorp` namespace on `github.com`, so its `source` could be
+`github.com/hashicorp/myawesomecloud`,
+
+-> Note: the actual _repository_ that myawesomecloud comes from must always have
+the name format `github.com/hashicorp/packer-plugin-myawesomecloud`, but the
+`required_plugins` block omits the redundant `packer-plugin-` repository prefix
+for brevity.
+
+The source address with all three components given explicitly is called the
+plugin's _fully-qualified address_. You will see fully-qualified address in
+various outputs, like error messages.
+
+## Plugin Loading Workflow
+
+At initialization, Packer attempts to discover the plugins installed locally. The
+logic follows what's described in Configuring Packer's
+[plugin directory](/packer/docs/configure#packer-s-plugin-directory)
+section.
+
+While Packer is not verbose during this step, you can peek into what it is discovering
+with `PACKER_LOG=1` enabled, where you can find log lines similar to the following:
+
+```shell
+[TRACE] discovering plugins in [...]
+[INFO] Discovered potential plugin: [...]
+```
+
+This logic however is ignored when plugins are defined in `required_plugins` blocks;
+instead, for every plugin required in this way, Packer will only consider them if they're
+installed in Packer's plugin directory, under a directory hierarchy that matches the
+source, with the plugin name respecting a convention.
+
+For example, if we install the `github.com/hashicorp/amazon` plugin in version 1.2.8 through
+either `packer init` or `packer plugins install`, this will yield the following (in a
+Linux x86_64 environment):
+
+```shell
+
+└── github.com
+ └── hashicorp
+ └── amazon
+ ├── packer-plugin-amazon_v1.2.8_x5.0_linux_amd64
+ └── packer-plugin-amazon_v1.2.8_x5.0_linux_amd64_SHA256SUM
+```
+
+Both the plugin's binary, and the related SHA256SUM file must be placed alongside
+each other for Packer to consider them for a `required_plugins` constraint.
+
+## Installation Guides
+
+
+
+
+In order to use `packer init` for managing installation of your plugins, there are
+two steps required.
+
+First, add a [`required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements)
+block to your [packer block](/packer/docs/templates/hcl_templates/blocks/packer).
+
+Each block will tell Packer what version(s) of a particular plugin can be installed.
+Make sure to set a valid
+[version constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints).
+
+Here is an example `required_plugins` block:
+
+```hcl
+packer {
+ required_plugins {
+ myawesomecloud = {
+ version = ">= 2.7.0"
+ source = "github.com/azr/myawesomecloud"
+ }
+ happycloud = {
+ version = ">= 1.1.3"
+ source = "github.com/azr/happycloud"
+ }
+ }
+}
+```
+
+Once your template contains those `required_plugins`, run
+[`packer init`](/packer/docs/commands/init) to install all missing plugin
+binaries.
+Given the above example, Packer will try to look for a GitHub
+repository owned by user or organization `azr` named
+`packer-plugin-myawesomecloud` and `packer-plugin-happycloud`.
+
+## Names and Addresses
+
+Each plugin has two identifiers:
+
+- A `source` address, which is where the plugin is downloaded from.
+- A unique **local name**, which is used everywhere else in a Packer configuration.
+
+## Local Names
+
+Local names allow you to access the components of a plugin and must be unique
+per configuration.
+
+This is best explained using an example. In the above `required_plugins` block,
+we declared the local name "myawesomecloud" for the plugin `azr/myawesomecloud`.
+If the "myawesomecloud" plugin contains both an "ebs" builder and an "import"
+post-processor, then the builder will be accessed in a source block by using:
+
+```hcl
+source "myawesomecloud-ebs" "example" {
+ // builder configuration...
+}
+```
+
+similarly, the import post-processor would be accessed by declaring the
+post-processor block:
+
+```hcl
+post-processor "myawesomecloud-import" {
+ // post-processor configuration...
+}
+```
+
+If we change the required_plugins block to use a different local name "foo":
+
+```hcl
+ required_plugins {
+ foo = {
+ version = ">= 2.7.0"
+ source = "github.com/azr/myawesomecloud"
+ }
+ }
+```
+
+Then we'd instead access that builder using the source:
+
+```hcl
+source "foo-ebs" "example" {
+ // builder configuration...
+}
+```
+
+
+
+
+Plugin installation via `packer plugins install` works similar to that of the `packer init` command, but
+no `required_plugins` block are required, and thus can be used with both legacy JSON and HCL2 templates.
+
+```shell
+packer plugins install github.com/hashicorp/vagrant
+```
+
+-> You can only install one plugin per invocation of the command. If you need to install
+ a specific version of a plugin, you can specify a version to install as an optional
+ argument to the command line.
+ e.g.: `packer plugins install "github.com/hashicorp/vagrant" "v1.0.1"`
+
+The command will install the plugin in the `PACKER_CONFIG_DIR` set, or its
+default location, which depends on the OS/environment, as documented in
+[Configuring Packer](/packer/docs/configure#packer-s-plugin-directory).
+
+
+
+
+If you have obtained or built a plugin binary for your OS/Architecture and want to
+use it with Packer, you can install it manually. For Packer to load the plugin,
+it must be named with the convention `packer-plugin-NAME`, and placed in Packer's plugin
+directory, as documented in
+[Configuring Packer](/packer/docs/configure#packer-s-plugin-directory).
+
+For example, if your configuration directory is located in `~/.config/packer`,
+you can copy the binary to `~/.config/packer/plugins/packer-plugin-NAME`, and
+Packer will be able to load it afterwards.
+
+If you have a `required_plugins` for the plugin you're manually installing, make sure
+it respects the constraints described in the [Plugin loading workflow](#plugin-loading-workflow)
+section, otherwise Packer will not be able to load it.
+
+Starting with v1.10.0 of Packer, you can also use `packer plugins install` with the
+`--path` flag to install a plugin from a binary, following the layout that is required to
+work with `required_plugins` block.
+
+```shell
+packer plugins install --path github.com/hashicorp/vagrant
+```
+
+-> packer plugins install --path only works with release versions of plugins.
+
+
+
diff --git a/content/packer/v1.10.x/content/docs/post-processors/artifice.mdx b/content/packer/v1.10.x/content/docs/post-processors/artifice.mdx
new file mode 100644
index 0000000000..e47fbf013d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/artifice.mdx
@@ -0,0 +1,173 @@
+---
+description: >
+ The artifice post-processor overrides the artifact list from an upstream
+
+ builder or post-processor. All downstream post-processors will see the new
+
+ artifacts you specify. The primary use-case is to build artifacts inside a
+
+ packer builder -- for example, spinning up an EC2 instance to build a Docker
+
+ container -- and then extracting the Docker container and throwing away the
+ EC2
+
+ instance.
+page_title: Artifice - Post-Processors
+---
+
+
+
+
+
+# Artifice Post-Processor
+
+Type: `artifice`
+Artifact BuilderId: `packer.post-processor.artifice`
+
+The artifice post-processor overrides the artifact list from an upstream
+builder or post-processor. All downstream post-processors will see the new
+artifacts you specify.
+
+After overriding the artifact with artifice, you can use it with other
+post-processors, including most of the core post-processors and third-party
+post-processors.
+
+A major benefit of this is that you can modify builder
+artifacts using shell-local and pass those modified artifacts into
+post-processors that may not have worked with the original builder.
+For example, maybe you want to export a Docker container from an amazon-ebs
+builder and then use Docker-push to put that Docker container into your Docker
+Hub account.
+
+Artifice allows you to use the familiar packer workflow to create a fresh,
+stateless build environment for each build on the infrastructure of your
+choosing. You can use this to build just about anything: buildpacks,
+containers, jars, binaries, tarballs, msi installers, and more.
+
+Please note that the artifice post-processor will _not_ delete your old artifact
+files, even if it removes them from the artifact. If you want to delete the
+old artifact files, you can use the shell-local post-processor to do so.
+
+## Workflow
+
+Artifice helps you tie together a few other packer features:
+
+- A builder, which spins up a VM (or container) to build your artifact
+- A provisioner, which performs the steps to create your artifact
+- A file provisioner, which downloads the artifact from the VM
+- The artifice post-processor, which identifies which files have been
+ downloaded from the VM
+- Additional post-processors, which push the artifact to Docker hub, etc.
+
+You will want to perform as much work as possible inside the VM. Ideally the
+only other post-processor you need after artifice is one that uploads your
+artifact to the appropriate repository.
+
+## Configuration
+
+The configuration allows you to specify which files comprise your artifact.
+
+### Required:
+
+- `files` (array of strings) - A list of files that comprise your artifact.
+ These files must exist on your local disk after the provisioning phase of
+ packer is complete. These will replace any of the builder's original
+ artifacts (such as a VM snapshot).
+
+### Optional:
+
+- `keep_input_artifact` (boolean) - if true, do not delete the original
+ artifact files after creating your new artifact. Defaults to true.
+
+### Example Configuration
+
+This minimal example:
+
+1. Spins up a cloned VMware virtual machine
+2. Installs a [consul](https://www.consul.io/) release
+3. Downloads the consul binary
+4. Packages it into a `.tar.gz` file
+5. Uploads it to S3.
+
+VMX is a fast way to build and test locally, but you can easily substitute
+another builder.
+
+```json
+{
+ "builders": [
+ {
+ "type": "vmware-vmx",
+ "source_path": "/opt/ubuntu-1404-vmware.vmx",
+ "ssh_username": "vagrant",
+ "ssh_password": "vagrant",
+ "shutdown_command": "sudo shutdown -h now",
+ "headless": "true",
+ "skip_compaction": "true"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell",
+ "inline": [
+ "sudo apt-get install -y python-pip",
+ "sudo pip install ifs",
+ "sudo ifs install consul --version=0.5.2"
+ ]
+ },
+ {
+ "type": "file",
+ "source": "/usr/local/bin/consul",
+ "destination": "consul",
+ "direction": "download"
+ }
+ ],
+ "post-processors": [
+ [
+ {
+ "type": "artifice",
+ "files": ["consul"]
+ },
+ {
+ "type": "compress",
+ "output": "consul-0.5.2.tar.gz"
+ },
+ {
+ "type": "shell-local",
+ "inline": [
+ "/usr/local/bin/aws s3 cp consul-0.5.2.tar.gz s3://"
+ ]
+ }
+ ]
+ ]
+}
+```
+
+**Notice that there are two sets of square brackets in the post-processor
+section.** This creates a post-processor chain, where the output of the
+proceeding artifact is passed to subsequent post-processors. If you use only
+one set of square braces the post-processors will run individually against the
+build artifact (the vmx file in this case) and it will not have the desired
+result.
+
+```json
+{
+ "post-processors": [
+ [ // <--- Start post-processor chain
+ {
+ "type": "artifice",
+ "files": ["consul"]
+ },
+ {
+ "type": "compress",
+ ...
+ }
+ ], // <--- End post-processor chain
+ {
+ "type":"compress" // <-- Standalone post-processor
+ }
+ ]
+}
+```
+
+You can create multiple post-processor chains to handle multiple builders (for
+example, building Linux and Windows binaries during the same build).
diff --git a/content/packer/v1.10.x/content/docs/post-processors/checksum.mdx b/content/packer/v1.10.x/content/docs/post-processors/checksum.mdx
new file mode 100644
index 0000000000..0f8056c64b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/checksum.mdx
@@ -0,0 +1,85 @@
+---
+description: >
+ The checksum post-processor computes specified checksum for the artifact list
+ from an upstream builder or post-processor. All downstream post-processors
+ will see the new artifacts. The primary use-case is compute checksum for
+ artifacts allows to verify it later. So firstly this post-processor get
+ artifact, compute it checksum and pass to next post-processor original
+ artifacts and checksum files.
+page_title: Checksum - Post-Processors
+---
+
+
+
+
+
+# Checksum Post-Processor
+
+Type: `checksum`
+Artifact BuilderId: `packer.post-processor.checksum`
+
+The checksum post-processor computes specified checksum for the artifact list
+from an upstream builder or post-processor. All downstream post-processors will
+see the new artifacts. The primary use-case is compute checksum for artifact to
+verify it later.
+
+After computes checksum for artifacts, you can use new artifacts with other
+post-processors like
+[artifice](/packer/docs/post-processors/artifice),
+[compress](/packer/docs/post-processors/compress),
+[docker-push](/packer/plugins/post-processors/docker/docker-push), or
+a third-party post-processor.
+
+## Basic example
+
+
+
+
+```json
+{
+ "type": "checksum",
+ "checksum_types": ["sha1", "sha256"],
+ "output": "packer_{{.BuildName}}_{{.ChecksumType}}.checksum"
+}
+```
+
+
+
+
+```hcl
+post-processor "checksum" {
+ checksum_types = ["sha1", "sha256"]
+ output = "packer_{{.BuildName}}_{{.ChecksumType}}.checksum"
+}
+```
+
+
+
+
+## Configuration Reference
+
+Optional parameters:
+
+- `checksum_types` (array of strings) - An array of strings of checksum types
+ to compute. If empty, Defaults to md5. Allowed values are:
+
+ - md5
+ - sha1
+ - sha224
+ - sha256
+ - sha384
+ - sha512
+
+- `output` (string) - Specify filename to store checksums. This defaults to
+ `packer_{{.BuildName}}_{{.BuilderType}}_{{.ChecksumType}}.checksum`. For
+ example, if you had a builder named `database`, you might see the file
+ written as `packer_database_docker_md5.checksum`. This is treated as a
+ [template engine](/packer/docs/templates/legacy_json_templates/engine). Therefore, you
+ may use user variables and template functions in this field.
+ The following special variables are also available to use in the output
+ template:
+
+ - `BuildName`: The name of the builder that produced the artifact.
+ - `BuilderType`: The type of builder used to produce the artifact.
+ - `ChecksumType`: The type of checksums the file contains. This should be
+ used if you have more than one value in `checksum_types`.
diff --git a/content/packer/v1.10.x/content/docs/post-processors/community-supported.mdx b/content/packer/v1.10.x/content/docs/post-processors/community-supported.mdx
new file mode 100644
index 0000000000..1be070e2fa
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/community-supported.mdx
@@ -0,0 +1,16 @@
+---
+description: >
+ Community-maintained post-processors are not part of the core Packer binary,
+ but
+
+ can run alongside Packer with minimal extra effort.
+page_title: Community - Post-Processors
+---
+
+# Community Post-Processors
+
+The following post-processors are developed and maintained by various members of the
+Packer community, not by HashiCorp. For more information on how to use community
+post-processors, see our docs on [extending Packer](/packer/docs/plugins/creation).
+
+@include 'post-processors/community_post-processors.mdx'
diff --git a/content/packer/v1.10.x/content/docs/post-processors/compress.mdx b/content/packer/v1.10.x/content/docs/post-processors/compress.mdx
new file mode 100644
index 0000000000..0a45ad171d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/compress.mdx
@@ -0,0 +1,87 @@
+---
+description: |
+ The Packer compress post-processor takes an artifact with files (such as from
+ VMware or VirtualBox) and compresses the artifact into a single archive.
+page_title: Compress - Post-Processors
+---
+
+
+
+
+
+# Compress Post-Processor
+
+Type: `compress`
+Artifact BuilderId: `packer.post-processor.compress`
+
+The Packer compress post-processor takes an artifact with files (such as from
+VMware or VirtualBox) and compresses the artifact into a single archive.
+
+## Configuration
+
+### Optional:
+
+By default, packer will build archives in `.tar.gz` format with the following
+filename: `packer_{{.BuildName}}_{{.BuilderType}}`. If you want to change this
+you will need to specify the `output` option.
+
+- `output` (string) - The path to save the compressed archive. The archive
+ format is inferred from the filename. E.g. `.tar.gz` will be a gzipped
+ tarball. `.zip` will be a zip file. If the extension can't be detected
+ packer defaults to `.tar.gz` behavior but will not change the filename.
+
+ This is treated as a
+ [template engine](/packer/docs/templates/legacy_json_templates/engine). Therefore, you
+ may use user variables and template functions in this field.
+ The following special variables are also available to use in the output
+ template:
+
+ - `{{.BuildName}}`
+ - `{{.BuilderType}}`
+
+ If you are executing multiple builders in parallel you should make sure
+ `output` is unique for each one. For example `packer_{{.BuildName}}.zip`.
+
+- `format` (string) - Disable archive format autodetection and use provided
+ string.
+
+- `compression_level` (number) - Specify the compression level, for
+ algorithms that support it, from 1 through 9 inclusive. Typically higher
+ compression levels take longer but produce smaller files. Defaults to `6`
+
+- `keep_input_artifact` (boolean) - if `true`, keep both the source files and
+ the compressed file; if `false`, discard the source files. Defaults to
+ `false`
+
+### Supported Formats
+
+Supported file extensions include `.zip`, `.tar`, `.gz`, `.tar.gz`, `.lz4` and
+`.tar.lz4`. Note that `.gz` and `.lz4` will fail if you have multiple files to
+compress.
+
+## Examples
+
+Some minimal examples are shown below, showing only the post-processor
+configuration:
+
+```json
+{
+ "type": "compress",
+ "output": "archive.tar.lz4"
+}
+```
+
+```json
+{
+ "type": "compress",
+ "output": "{{.BuildName}}_bundle.zip"
+}
+```
+
+```json
+{
+ "type": "compress",
+ "output": "log_{{.BuildName}}.gz",
+ "compression_level": 9
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/post-processors/index.mdx b/content/packer/v1.10.x/content/docs/post-processors/index.mdx
new file mode 100644
index 0000000000..0db8b5c34c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/index.mdx
@@ -0,0 +1,14 @@
+---
+description: |
+ Post-processors run after the image is built by the builder and provisioned by
+ the provisioner(s).
+page_title: Post-Processors
+---
+
+# Post-Processors
+
+Post-processors run after builders and provisioners. Post-processors are optional, and you can use them to upload artifacts, re-package files, and more. The documentation includes a page for each type of post-processor.
+
+Refer to the [`post-processor`](/packer/docs/templates/hcl_templates/blocks/build/post-processor) and
+[`post-processors`](/packer/docs/templates/hcl_templates/blocks/build/post-processors)
+blocks documentation to learn more about working with post-processors.
diff --git a/content/packer/v1.10.x/content/docs/post-processors/manifest.mdx b/content/packer/v1.10.x/content/docs/post-processors/manifest.mdx
new file mode 100644
index 0000000000..839c940cb1
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/manifest.mdx
@@ -0,0 +1,207 @@
+---
+description: >
+ The manifest post-processor writes a JSON file with the build artifacts and
+ IDs from a packer run.
+page_title: Manifest - Post-Processors
+---
+
+
+
+
+
+# Manifest Post-Processor
+
+Type: `manifest`
+Artifact BuilderId: `packer.post-processor.manifest`
+
+The manifest post-processor writes a JSON file with a list of all of the
+artifacts packer produces during a run. If your Packer template includes
+multiple builds, this helps you keep track of which output artifacts (files,
+AMI IDs, Docker containers, etc.) correspond to each build.
+
+The manifest post-processor is invoked each time a build completes and
+_updates_ data in the manifest file. Builds are identified by name and type,
+and include their build time, artifact ID, and file list.
+
+If packer is run with the `-force` flag the manifest file will be truncated
+automatically during each packer run. Otherwise, subsequent builds will be
+added to the file. You can use the timestamps to see which is the latest
+artifact.
+
+You can specify manifest more than once and write each build to its own file,
+or write all builds to the same file. For simple builds manifest only needs to
+be specified once (see below) but you can also chain it together with other
+post-processors such as Docker and Artifice.
+
+## Configuration
+
+### Optional:
+
+@include 'post-processor/manifest/Config-not-required.mdx'
+
+~> **Note**: Unlike most other post-processors, the keep_input_artifact option doesn't apply for the manifest
+post-processor. We will always retain the input artifact for manifest, since deleting the files we just recorded
+is not a behavior anyone should ever expect.
+
+### Example Configuration
+
+The minimal way to use the manifest post-processor is by just writing its definition, like:
+
+
+
+
+```json
+{
+ "post-processors": [
+ {
+ "type": "manifest"
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+post-processor "manifest" {}
+```
+
+
+
+
+A more complete example:
+
+
+
+
+```json
+{
+ "post-processors": [
+ {
+ "type": "manifest",
+ "output": "manifest.json",
+ "strip_path": true,
+ "custom_data": {
+ "my_custom_data": "example"
+ }
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+post-processor "manifest" {
+ output = "manifest.json"
+ strip_path = true
+ custom_data = {
+ my_custom_data = "example"
+ }
+}
+```
+
+
+
+
+An example manifest file looks like:
+
+```json
+{
+ "builds": [
+ {
+ "name": "docker",
+ "builder_type": "docker",
+ "build_time": 1507245986,
+ "files": [
+ {
+ "name": "packer_example",
+ "size": 102219776
+ }
+ ],
+ "artifact_id": "Container",
+ "packer_run_uuid": "6d5d3185-fa95-44e1-8775-9e64fe2e2d8f",
+ "custom_data": {
+ "my_custom_data": "example"
+ }
+ }
+ ],
+ "last_run_uuid": "6d5d3185-fa95-44e1-8775-9e64fe2e2d8f"
+}
+```
+
+If the build is run again, the new build artifacts will be added to the
+manifest file rather than replacing it. It is possible to grab specific build
+artifacts from the manifest by using `packer_run_uuid`.
+
+The above manifest was generated with the following template:
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "docker",
+ "image": "ubuntu:latest",
+ "export_path": "packer_example",
+ "run_command": ["-d", "-i", "-t", "--entrypoint=/bin/bash", "{{.Image}}"]
+ }
+ ],
+ "post-processors": [
+ {
+ "type": "manifest",
+ "output": "manifest.json",
+ "strip_path": true,
+ "custom_data": {
+ "my_custom_data": "example"
+ }
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+source "docker" "docker"{
+ image = "ubuntu:latest"
+ export_path = "packer_example"
+ run_command = ["-d", "-i", "-t", "--entrypoint=/bin/bash", "{{.Image}}"]
+}
+
+build {
+ sources = ["docker.docker"]
+
+ post-processor "manifest" {
+ output = "manifest.json"
+ strip_path = true
+ custom_data = {
+ my_custom_data = "example"
+ }
+ }
+}
+```
+
+
+
+
+Example usage:
+
+The manifest can be very useful for cleaning up old artifacts, or printing
+important values to logs. The following example uses jq, a command-line tool for
+parsing json output, to find and echo the AWS ami-id of an AMI created by a
+build.
+
+```bash
+
+#!/bin/bash
+
+AMI_ID=$(jq -r '.builds[-1].artifact_id | split(":") | .[1]' manifest.json)
+echo $AMI_ID
+
+```
diff --git a/content/packer/v1.10.x/content/docs/post-processors/shell-local.mdx b/content/packer/v1.10.x/content/docs/post-processors/shell-local.mdx
new file mode 100644
index 0000000000..e04cd51277
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/post-processors/shell-local.mdx
@@ -0,0 +1,649 @@
+---
+description: |
+ The shell-local Packer post processor enables users to do some post processing
+ after artifacts have been built.
+page_title: Local Shell - Post-Processors
+---
+
+
+
+
+
+# Local Shell Post Processor
+
+Type: `shell-local`
+
+The local shell post processor executes scripts locally during the post
+processing stage. Shell local provides a convenient way to automate executing
+some task with packer outputs and variables.
+
+## Basic example
+
+The example below is a fully functional self-contained build.
+
+
+
+
+```hcl
+source "file" "example" {
+ content = "example content"
+}
+
+build {
+ source "source.file.example" {
+ target = "./test_artifact.txt"
+ }
+
+ post-processor "shell-local" {
+ inline = ["echo foo"]
+ }
+}
+```
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "file",
+ "name": "example",
+ "target": "./test_artifact.txt",
+ "content": "example content"
+ }
+ ],
+ "post-processors": [
+ {
+ "type": "shell-local",
+ "inline": ["echo foo"]
+ }
+ ]
+}
+```
+
+
+
+
+## Configuration Reference
+
+The reference of available configuration options is listed below. The only
+required element is either "inline" or "script". Every other option is
+optional.
+
+Exactly _one_ of the following is required:
+
+- `command` (string) - This is a single command to execute. It will be
+ written to a temporary file and run using the `execute_command` call below.
+
+- `inline` (array of strings) - This is an array of commands to execute. The
+ commands are concatenated by newlines and turned into a single file, so
+ they are all executed within the same context. This allows you to change
+ directories in one command and use something in the directory in the next
+ and so on. Inline scripts are the easiest way to pull off simple tasks
+ within the machine.
+
+- `script` (string) - The path to a script to execute. This path can be
+ absolute or relative. If it is relative, it is relative to the working
+ directory when Packer is executed.
+
+- `scripts` (array of strings) - An array of scripts to execute. The scripts
+ will be executed in the order specified. Each script is executed in
+ isolation, so state such as variables from one script won't carry on to the
+ next.
+
+Optional parameters:
+
+- `env` (map of strings) - A map of key/value pairs to inject prior to the
+ execute_command. Packer injects some environmental variables by default into
+ the environment, as well, which are covered in the section below. Duplicate
+ `env` settings override `environment_vars` settings.
+
+- `environment_vars` (array of strings) - An array of key/value pairs to
+ inject prior to the `execute_command`. The format should be `key=value`.
+ Packer injects some environmental variables by default into the
+ environment, as well, which are covered in the section below.
+
+- `env_var_format` (string) - When we parse the environment_vars that you
+ provide, this gives us a string template to use in order to make sure that
+ we are setting the environment vars correctly. By default on Windows hosts
+ this format is `set %s=%s &&` and on Unix, it is `%s='%s'`. You probably
+ won't need to change this format, but you can see usage examples for where
+ it is necessary below.
+
+- `execute_command` (array of strings) - The command used to execute the
+ script. By default, on \*nix systems this is:
+
+ ```text
+ ["/bin/sh", "-c", "{{.Vars}} {{.Script}}"]
+ ```
+
+ While on Windows, `execute_command` defaults to:
+
+ ```text
+ ["cmd", "/V", "/C", "{{.Vars}}", "call", "{{.Script}}"]
+ ```
+
+ This is treated as a [template engine](/packer/docs/templates/legacy_json_templates/engine).
+ There are several available variables: `Script`, which is the path to the
+ script to run, and `Vars`, which is the list of `environment_vars`, if
+ configured. In addition, you may access any of the variables stored in the
+ generated data using the [build](/packer/docs/templates/legacy_json_templates/engine) template
+ function. If you choose to set this option, make sure that the first
+ element in the array is the shell program you want to use (for example,
+ "sh" or "/usr/local/bin/zsh" or even "powershell.exe" although anything
+ other than a flavor of the shell command language is not explicitly
+ supported and may be broken by assumptions made within Packer). It's
+ worth noting that if you choose to try to use shell-local for
+ Powershell or other Windows commands, the environment variables will
+ not be set properly for your environment.
+
+ For backwards compatibility, `execute_command` will accept a string instead
+ of an array of strings. If a single string or an array of strings with only
+ one element is provided, Packer will replicate past behavior by appending
+ your `execute_command` to the array of strings `["sh", "-c"]`. For example,
+ if you set `"execute_command": "foo bar"`, the final `execute_command` that
+ Packer runs will be \["sh", "-c", "foo bar"\]. If you set
+ `"execute_command": ["foo", "bar"]`, the final execute_command will remain
+ `["foo", "bar"]`.
+
+ Again, the above is only provided as a backwards compatibility fix; we
+ strongly recommend that you set execute_command as an array of strings.
+
+- `inline_shebang` (string) - The
+ [shebang](http://en.wikipedia.org/wiki/Shebang_%28Unix%29) value to use
+ when running commands specified by `inline`. By default, this is
+ `/bin/sh -e`. If you're not using `inline`, then this configuration has no
+ effect. **Important:** If you customize this, be sure to include something
+ like the `-e` flag, otherwise individual steps failing won't fail the
+ provisioner.
+
+- `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+ keep_input_artifact option will have no effect for the shell-local
+ post-processor. Packer will always retain the input artifact for
+ shell-local, since the shell-local post-processor merely passes forward the
+ artifact it receives. If your shell-local post-processor produces a file or
+ files which you would like to have replace the input artifact, you may
+ overwrite the input artifact using the [artifice](/packer/docs/post-processors/artifice)
+ post-processor after your shell-local processor has run.
+
+- `only_on` (array of strings) - This is an array of [runtime operating
+ systems](https://go.dev/doc/install/source#environment) where
+ `shell-local` will execute. This allows you to execute `shell-local` _only_
+ on specific operating systems. By default, shell-local will always run if
+ `only_on` is not set."
+
+- `use_linux_pathing` (bool) - This is only relevant to Windows hosts. If you
+ are running Packer in a Windows environment with the Windows Subsystem for
+ Linux feature enabled, and would like to invoke a bash script rather than
+ invoking a Cmd script, you'll need to set this flag to true; it tells
+ Packer to use the Linux subsystem path for your script rather than the
+ Windows path. (e.g. /mnt/c/path/to/your/file instead of
+ C:/path/to/your/file). Please see the example below for more guidance on
+ how to use this feature. If you are not on a Windows host, or you do not
+ intend to use the shell-local post-processor to run a bash script, please
+ ignore this option. If you set this flag to true, you still need to provide
+ the standard Windows path to the script when providing a `script`. This is
+ a beta feature.
+
+- `valid_exit_codes` (list of ints) - Valid exit codes for the script. By
+ default this is `0`.
+
+## Execute Command
+
+To many new users, the `execute_command` is puzzling. However, it provides an
+important function: customization of how the command is executed. The most
+common use case for this is dealing with **sudo password prompts**. You may
+also need to customize this if you use a non-POSIX shell, such as `tcsh` on
+FreeBSD.
+
+### The Windows Linux Subsystem
+
+The shell-local post-processor was designed with the idea of allowing you to
+run commands in your local operating system's native shell. For Windows, we've
+assumed in our defaults that this is Cmd. However, it is possible to run a bash
+script as part of the Windows Linux Subsystem from the shell-local
+post-processor, by modifying the `execute_command` and the `use_linux_pathing`
+options in the post-processor config.
+
+The example below is a fully functional test config.
+
+One limitation of this offering is that "inline" and "command" options are not
+available to you; please limit yourself to using the "script" or "scripts"
+options instead.
+
+Please note that this feature is still in beta, as the underlying WSL is also
+still in beta. There will be some limitations as a result. For example, it will
+likely not work unless both Packer and the scripts you want to run are both on
+the C drive.
+
+
+
+
+```hcl
+source "null" "example" {
+ communicator = "none"
+}
+
+build {
+ sources = [
+ "source.null.example"
+ ]
+
+ post-processor "shell-local"{
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
+ execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
+ use_linux_pathing = true
+ scripts = ["C:/Users/me/scripts/example_bash.sh"]
+ }
+ post-processor "shell-local"{
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
+ execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
+ use_linux_pathing = true
+ script = "C:/Users/me/scripts/example_bash.sh"
+ }
+}
+```
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "post-processors": [
+ {
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
+ "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
+ "use_linux_pathing": true,
+ "scripts": ["C:/Users/me/scripts/example_bash.sh"]
+ },
+ {
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
+ "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
+ "use_linux_pathing": true,
+ "script": "C:/Users/me/scripts/example_bash.sh"
+ }
+ ]
+}
+```
+
+
+
+
+## Default Environmental Variables
+
+In addition to being able to specify custom environmental variables using the
+`environment_vars` configuration, the provisioner automatically defines certain
+commonly useful environmental variables:
+
+- `PACKER_BUILD_NAME` is set to the [name of the
+ build](/packer/docs/templates/legacy_json_templates/builders#named-builds) that Packer is running.
+ This is most useful when Packer is making multiple builds and you want to
+ distinguish them slightly from a common provisioning script.
+
+- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
+ the machine that the script is running on. This is useful if you want to
+ run only certain parts of the script on systems built with certain
+ builders.
+
+## Safely Writing A Script
+
+Whether you use the `inline` option, or pass it a direct `script` or `scripts`,
+it is important to understand a few things about how the shell-local
+post-processor works to run it safely and easily. This understanding will save
+you much time in the process.
+
+### Once Per Builder
+
+The `shell-local` script(s) you pass are run once per builder. This means that
+if you have an `amazon-ebs` builder and a `docker` builder, your script will be
+run twice. If you have 3 builders, it will run 3 times, once for each builder.
+
+### Interacting with Build Artifacts
+
+In order to interact with build artifacts, you may want to use the [manifest
+post-processor](/packer/docs/post-processors/manifest). This will write the list
+of files produced by a `builder` to a json file after each `builder` is run.
+
+For example, if you wanted to package a file from the file builder into a
+tarball, you might write this:
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "content": "Lorem ipsum dolor sit amet",
+ "target": "dummy_artifact",
+ "type": "file"
+ }
+ ],
+ "post-processors": [
+ [
+ {
+ "output": "manifest.json",
+ "strip_path": true,
+ "type": "manifest"
+ },
+ {
+ "inline": [
+ "jq \".builds[].files[].name\" manifest.json | xargs tar cfz artifacts.tgz"
+ ],
+ "type": "shell-local"
+ }
+ ]
+ ]
+}
+```
+
+
+
+
+```hcl
+source "file" "example" {
+ content = "Lorem ipsum dolor sit amet"
+ target = "dummy_artifact.txt"
+}
+build {
+ sources = [
+ "source.file.example"
+ ]
+ post-processor "manifest" {
+ output = "manifest.json"
+ strip_path = true
+ }
+
+ post-processor "shell-local" {
+ inline = [
+ "jq \".builds[].files[].name\" manifest.json | xargs tar cfz artifacts.tgz"
+ ]
+ }
+}
+```
+
+
+
+
+This uses the [jq](https://stedolan.github.io/jq/) tool to extract all of the
+file names from the manifest file and passes them to tar.
+
+### Always Exit Intentionally
+
+If any post-processor fails, the `packer build` stops and all interim artifacts
+are cleaned up.
+
+For a shell script, that means the script **must** exit with a zero code. You
+_must_ be extra careful to `exit 0` when necessary.
+
+## Usage Examples:
+
+### Windows Host
+
+Example of running a .cmd file on Windows:
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest1"]
+ scripts = ["./scripts/test_cmd.cmd"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest1"],
+ "scripts": ["./scripts/test_cmd.cmd"]
+}
+```
+
+
+
+
+Contents of `test_cmd.cmd`:
+
+ echo %SHELLLOCALTEST%
+
+Example of running an inline command on Windows: Required customization:
+tempfile_extension
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest2"],
+ tempfile_extension = ".cmd",
+ inline = ["echo %SHELLLOCALTEST%"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest2"],
+ "tempfile_extension": ".cmd",
+ "inline": ["echo %SHELLLOCALTEST%"]
+}
+```
+
+
+
+
+Example of running a bash command on Windows using WSL: Required
+customizations: `use_linux_pathing` and `execute_command`:
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest3"],
+ execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
+ use_linux_pathing = true
+ script = "./scripts/example_bash.sh"
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest3"],
+ "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
+ "use_linux_pathing": true,
+ "script": "./scripts/example_bash.sh"
+}
+```
+
+
+
+
+Contents of `example_bash.sh`:
+
+ #!/bin/bash
+ echo $SHELLLOCALTEST
+
+Example of running a PowerShell script on Windows:
+Required customizations: `env_var_format` and `execute_command`.
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest4"]
+ execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
+ env_var_format = "$env:%s=\"%s\"; "
+ script = "./scripts/example_ps.ps1"
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest4"],
+ "execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
+ "env_var_format": "$env:%s=\"%s\"; ",
+ "script": "./scripts/example_ps.ps1"
+}
+```
+
+
+
+
+Example of running a PowerShell script on Windows as "inline": Required
+customizations: `env_var_format`, `tempfile_extension`, and `execute_command`
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ tempfile_extension = ".ps1"
+ environment_vars = ["SHELLLOCALTEST=ShellTest5"]
+ execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
+ env_var_format = "$env:%s=\"%s\"; "
+ inline = ["write-output $env:SHELLLOCALTEST"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "tempfile_extension": ".ps1",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest5"],
+ "execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
+ "env_var_format": "$env:%s=\"%s\"; ",
+ "inline": ["write-output $env:SHELLLOCALTEST"]
+}
+```
+
+
+
+
+### Unix Host
+
+Example of running a Shell script on Unix:
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
+ scripts = ["./scripts/example_bash.sh"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
+ "scripts": ["./scripts/example_bash.sh"]
+}
+```
+
+
+
+
+Example of running a bash "inline" on Unix:
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
+ inline = ["echo hello", "echo $PROVISIONERTEST"]
+}
+
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
+ "inline": ["echo hello", "echo $PROVISIONERTEST"]
+}
+```
+
+
+
+
+Example of running a Python script on Unix:
+
+
+
+
+```hcl
+post-processor "shell-local" {
+ script = "hello.py"
+ environment_vars = ["HELLO_USER=packeruser"]
+ execute_command = [
+ "/bin/sh",
+ "-c",
+ "{{.Vars}} /usr/local/bin/python {{.Script}}"
+ ]
+}
+
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "script": "hello.py",
+ "environment_vars": ["HELLO_USER=packeruser"],
+ "execute_command": [
+ "/bin/sh",
+ "-c",
+ "{{.Vars}} /usr/local/bin/python {{.Script}}"
+ ]
+}
+```
+
+
+
+
+```text
+Where "hello.py" contains:
+
+ import os
+
+ print('Hello, %s!' % os.getenv("HELLO_USER"))
+```
diff --git a/content/packer/v1.10.x/content/docs/provisioners/breakpoint.mdx b/content/packer/v1.10.x/content/docs/provisioners/breakpoint.mdx
new file mode 100644
index 0000000000..b7585fd678
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/breakpoint.mdx
@@ -0,0 +1,113 @@
+---
+description: >
+ The breakpoint provisioner will pause until the user presses "enter" to resume
+
+ the build. This is intended for debugging purposes, and allows you to halt at
+ a
+
+ particular part of the provisioning process.
+page_title: breakpoint - Provisioners
+---
+
+
+
+
+
+# Breakpoint Provisioner
+
+Type: `breakpoint`
+
+The breakpoint provisioner will pause until the user presses "enter" to resume
+the build. This is intended for debugging purposes, and allows you to halt at a
+particular part of the provisioning process.
+
+This is independent of the `-debug` flag, which will instead halt at every step
+and between every provisioner.
+
+## Basic Example
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "inline": "echo hi"
+ },
+ {
+ "type": "breakpoint",
+ "disable": false,
+ "note": "this is a breakpoint"
+ },
+ {
+ "type": "shell-local",
+ "inline": "echo hi 2"
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+source "null" "example" {
+ communicator = "none"
+}
+
+build {
+ sources = ["source.null.example"]
+
+ provisioner "shell-local" {
+ inline = ["echo hi"]
+ }
+ provisioner "breakpoint" {
+ disable = false
+ note = "this is a breakpoint"
+ }
+ provisioner "shell-local" {
+ inline = ["echo hi 2"]
+ }
+}
+```
+
+
+
+
+## Configuration Reference
+
+### Optional
+
+- `disable` (boolean) - If `true`, skip the breakpoint. Useful for when you
+ have set multiple breakpoints and want to toggle them off or on. Default:
+ `false`
+
+- `note` (string) - a string to include explaining the purpose or location of
+ the breakpoint. For example, you may find it useful to number your
+ breakpoints or label them with information about where in the build they
+ occur
+
+@include 'provisioners/common-config.mdx'
+
+## Usage
+
+Insert this provisioner wherever you want the build to pause. You'll see ui
+output prompting you to press "enter" to continue the build when you are ready.
+
+For example:
+
+```shell-session
+==> docker: Pausing at breakpoint provisioner with note "foo bar baz".
+==> docker: Press enter to continue.
+```
+
+Once you press enter, the build will resume and run normally until it either
+completes or errors.
diff --git a/content/packer/v1.10.x/content/docs/provisioners/community-supported.mdx b/content/packer/v1.10.x/content/docs/provisioners/community-supported.mdx
new file mode 100644
index 0000000000..1cb14aa97d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/community-supported.mdx
@@ -0,0 +1,14 @@
+---
+description: |
+ Community-maintained provisioners are not part of the core Packer binary, but
+ can run alongside Packer with minimal extra effort.
+page_title: Community - Provisioners
+---
+
+# Community Provisioners
+
+The following provisioners are developed and maintained by various members of the
+Packer community, not by HashiCorp. For more information on how to use community
+provisioners, see our docs on [extending Packer](/packer/docs/plugins/creation).
+
+@include 'provisioners/community_provisioners.mdx'
diff --git a/content/packer/v1.10.x/content/docs/provisioners/custom.mdx b/content/packer/v1.10.x/content/docs/provisioners/custom.mdx
new file mode 100644
index 0000000000..5606844347
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/custom.mdx
@@ -0,0 +1,16 @@
+---
+description: |
+ Packer is extensible, allowing you to write new provisioners without having to
+ modify the core source code of Packer itself. Documentation for creating new
+ provisioners is covered in the custom provisioners page of the Packer plugin
+ section.
+page_title: Custom - Provisioners
+---
+
+# Custom Provisioner
+
+Packer is extensible, allowing you to write new provisioners without having to
+modify the core source code of Packer itself. Documentation for creating new
+provisioners is covered in the [custom
+provisioners](/packer/docs/plugins/creation/custom-provisioners) page of the Packer
+plugin section.
diff --git a/content/packer/v1.10.x/content/docs/provisioners/file.mdx b/content/packer/v1.10.x/content/docs/provisioners/file.mdx
new file mode 100644
index 0000000000..e123be997c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/file.mdx
@@ -0,0 +1,192 @@
+---
+description: |
+ The file Packer provisioner uploads files to machines built by Packer. The
+ recommended usage of the file provisioner is to use it to upload files, and
+ then use shell provisioner to move them to the proper place, set permissions,
+ etc.
+page_title: File - Provisioners
+---
+
+
+
+
+
+# File Provisioner
+
+Type: `file`
+
+The file Packer provisioner uploads files to machines built by Packer. The
+recommended usage of the file provisioner is to use it to upload files, and
+then use [shell provisioner](/packer/docs/provisioners/shell) to move them to the
+proper place, set permissions, etc.
+
+Warning: You can only upload files to locations that the provisioning user
+(generally not root) has permission to access. Creating files in /tmp and
+using a shell provisioner to move them into the final location is the only
+way to upload files to root owned locations.
+
+The file provisioner can upload both single files and complete directories.
+
+## Basic Example
+
+
+
+
+```json
+{
+ "type": "file",
+ "source": "app.tar.gz",
+ "destination": "/tmp/app.tar.gz"
+}
+```
+
+
+
+
+```hcl
+provisioner "file" {
+ source = "app.tar.gz"
+ destination = "/tmp/app.tar.gz"
+}
+```
+
+
+
+
+## Configuration Reference
+
+The available configuration options are listed below.
+
+## Configuration Reference
+
+Required Parameters:
+
+@include 'provisioner/file/Config-required.mdx'
+
+Optional Parameters:
+
+@include '/provisioner/file/Config-not-required.mdx'
+
+@include 'provisioners/common-config.mdx'
+
+## Directory Uploads
+
+The file provisioner is also able to upload a complete directory to the remote
+machine. When uploading a directory, there are a few important things you
+should know.
+
+First, the destination directory must already exist. If you need to create it,
+use a shell provisioner just prior to the file provisioner in order to create
+the directory. If the destination directory does not exist, the file
+provisioner may succeed, but it will have undefined results.
+
+Next, the existence of a trailing slash on the source path will determine
+whether the directory name will be embedded within the destination, or whether
+the destination will be created. An example explains this best:
+
+If the source is `/foo` (no trailing slash), and the destination is `/tmp`,
+then the contents of `/foo` on the local machine will be uploaded to `/tmp/foo`
+on the remote machine. The `foo` directory on the remote machine will be
+created by Packer.
+
+If the source, however, is `/foo/` (a trailing slash is present), and the
+destination is `/tmp`, then the contents of `/foo` will be uploaded into `/tmp`
+directly.
+
+This behavior was adopted from the standard behavior of rsync. Note that under
+the covers, rsync may or may not be used.
+
+## Uploading files that don't exist before Packer starts
+
+In general, local files used as the source **must** exist before Packer is run.
+This is great for catching typos and ensuring that once a build is started,
+that it will succeed. However, this also means that you can't generate a file
+during your build and then upload it using the file provisioner later. A
+convenient workaround is to upload a directory instead of a file. The directory
+still must exist, but its contents don't. You can write your generated file to
+the directory during the Packer run, and have it be uploaded later.
+
+## Symbolic link uploads
+
+The behavior when uploading symbolic links depends on the communicator. The
+Docker communicator will preserve symlinks, but all other communicators will
+treat local symlinks as regular files. If you wish to preserve symlinks when
+uploading, it's recommended that you use `tar`. Below is an example of what
+that might look like:
+
+```shell-session
+$ ls -l files
+total 16
+drwxr-xr-x 3 mwhooker staff 102 Jan 27 17:10 a
+lrwxr-xr-x 1 mwhooker staff 1 Jan 27 17:10 b -> a
+-rw-r--r-- 1 mwhooker staff 0 Jan 27 17:10 file1
+lrwxr-xr-x 1 mwhooker staff 5 Jan 27 17:10 file1link -> file1
+$ ls -l toupload
+total 0
+-rw-r--r-- 1 mwhooker staff 0 Jan 27 17:10 files.tar
+```
+
+
+
+
+```json
+{
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "command": "tar cf toupload/files.tar files"
+ },
+ {
+ "destination": "/tmp/",
+ "source": "./toupload",
+ "type": "file"
+ },
+ {
+ "inline": [
+ "cd /tmp && tar xf toupload/files.tar",
+ "rm toupload/files.tar"
+ ],
+ "type": "shell"
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+build {
+ sources = [
+ "source.docker.example"
+ ]
+
+ provisioner "shell-local" {
+ command = "tar cf toupload/files.tar files"
+ }
+ provisioner "file" {
+ destination = "/tmp/"
+ source = "./toupload"
+ }
+ provisioner "shell" {
+ inline = [
+ "cd /tmp && tar xf toupload/files.tar",
+ "rm toupload/files.tar"
+ ]
+ }
+}
+```
+
+
+
+
+## Slowness when transferring large files over WinRM.
+
+Because of the way our WinRM transfers works, it can take a very long time to
+upload and download even moderately sized files. If you're experiencing slowness
+using the file provisioner on Windows, it's suggested that you set up an SSH
+server and use the [ssh communicator](/packer/docs/communicators/ssh). If you only want
+to transfer files to your guest, and if your builder supports it, you may also
+use the `http_directory` or `http_content` directives. This will cause that
+directory to be available to the guest over HTTP, and set the environment
+variable `PACKER_HTTP_ADDR` to the address.
diff --git a/content/packer/v1.10.x/content/docs/provisioners/index.mdx b/content/packer/v1.10.x/content/docs/provisioners/index.mdx
new file mode 100644
index 0000000000..e9fb2f8669
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/index.mdx
@@ -0,0 +1,19 @@
+---
+description: |
+ Provisioners use builtin and third-party software to install and configure the
+ machine image after booting.
+page_title: Provisioners
+---
+
+# Provisioners
+
+Provisioners use built-in and third-party software to install and configure the
+machine image after booting. Provisioners prepare the system, so you may want to use them for the following use cases:
+
+- installing packages
+- patching the kernel
+- creating users
+- downloading application code
+
+Refer to the [`provisioner`](/packer/docs/templates/hcl_templates/blocks/build/provisioner) block documentation to learn more
+about working with provisioners. The documentation includes details about each type of provisioner.
diff --git a/content/packer/v1.10.x/content/docs/provisioners/powershell.mdx b/content/packer/v1.10.x/content/docs/provisioners/powershell.mdx
new file mode 100644
index 0000000000..c50b8515c9
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/powershell.mdx
@@ -0,0 +1,483 @@
+---
+description: |
+ The PowerShell Packer provisioner runs PowerShell scripts on Windows machines.
+ It assumes that the communicator in use is WinRM.
+page_title: PowerShell - Provisioners
+---
+
+
+
+
+
+# PowerShell Provisioner
+
+Type: `powershell`
+
+The PowerShell Packer provisioner runs PowerShell scripts on Windows machines.
+It assumes that the communicator in use is WinRM. However, the provisioner can
+work equally well (with a few caveats) when combined with the SSH communicator.
+See the [section
+below](#combining-the-powershell-provisioner-with-the-ssh-communicator) for
+details.
+
+`@include 'path/separator-note.mdx'`
+
+## Basic Example
+
+The example below is fully functional.
+
+
+
+
+```hcl
+provisioner "powershell" {
+ inline = ["dir c:/"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "powershell",
+ "inline": ["dir c:/"]
+}
+```
+
+
+
+
+## Configuration Reference
+
+@include 'provisioners/shell-config.mdx'
+
+- `debug_mode` - If set, sets PowerShell's [PSDebug mode](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/set-psdebug?view=powershell-7)
+ in order to make script debugging easier. For instance, setting the value to 1
+ results in adding this to the execute command:
+
+ ```powershell
+ Set-PSDebug -Trace 1
+ ```
+
+- `elevated_execute_command` (string) - The command to use to execute the
+ elevated script. By default this is as follows:
+
+ ```powershell
+ powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }"
+ ```
+
+ This is a [template engine](/packer/docs/templates/legacy_json_templates/engine).
+ Therefore, you may use user variables and template functions in this field. In
+ addition, you may use two extra variables:
+
+ - `Path`: The path to the script to run
+ - `Vars`: The location of a temp file containing the list of
+ `environment_vars`, if configured.
+
+- `env` (map of strings) - A map of key/value pairs to inject prior to the
+ execute_command. Packer injects some environmental variables by default into
+ the environment, as well, which are covered in the section below. Duplicate
+ `env` settings override `environment_vars` settings. This is not a JSON
+ template engine enabled function. HCL interpolation works as usual.
+
+- `environment_vars` (array of strings) - An array of key/value pairs to
+ inject prior to the execute_command. The format should be `key=value`.
+ Packer injects some environmental variables by default into the
+ environment, as well, which are covered in the section below.
+
+- `use_pwsh` (boolean) - Run `pwsh.exe` instead of `powershell.exe`. Defaults to false.
+
+ This is a [template engine](/packer/docs/templates/legacy_json_templates/engine). Therefore, you
+ may use user variables and template functions in this field. If you are
+ running on AWS, Azure, Google Compute, or OpenStack and would like to access
+ the autogenerated password that Packer uses to connect to the instance via
+ WinRM, you can use the `build` template engine to inject it using
+ `` {{ build `Password` }} ``. In HCL templates, you can do the same thing by
+ accessing the `build` variables For example:
+
+
+
+
+```hcl
+provisioner "powershell" {
+ environment_vars = ["WINRMPASS=${build.Password}"]
+ inline = ["Write-Host \"Automatically generated aws password is: $Env:WINRMPASS\""]
+}
+```
+
+
+
+
+```json
+{
+ "type": "powershell",
+ "environment_vars": ["WINRMPASS={{ build `Password` }}"],
+ "inline": ["Write-Host \"Automatically generated aws password is: $Env:WINRMPASS\""]
+},
+```
+
+
+
+
+- `execute_command` (string) - The command to use to execute the script. By
+ default this is as follows:
+
+ ```powershell
+ powershell -executionpolicy bypass "& { if (Test-Path variable:global:ProgressPreference){$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit $LastExitCode }"
+ ```
+
+ This is a [template engine](/packer/docs/templates/legacy_json_templates/engine).
+ Therefore, you may use user variables and template functions in this field. In
+ addition, you may use two extra variables:
+
+ - `Path`: The path to the script to run
+ - `Vars`: The location of a temp file containing the list of
+ `environment_vars`, if configured.
+ The value of both `Path` and `Vars` can be manually configured by setting
+ the values for `remote_path` and `remote_env_var_path` respectively.
+
+ If you use the SSH communicator and have changed your default shell, you
+ may need to modify your `execute_command` to make sure that the command is
+ valid and properly escaped; the default assumes that you have not changed
+ the default shell away from cmd.
+
+- `elevated_user` and `elevated_password` (string) - If specified, the
+ PowerShell script will be run with elevated privileges using the given
+ Windows user.
+
+ This is a [template engine](/packer/docs/templates/legacy_json_templates/engine). Therefore, you
+ may use user variables and template functions in this field. If you are
+ running on AWS, Azure, Google Compute, or OpenStack and would like to access
+ the autogenerated password that Packer uses to connect to the instance via
+ WinRM, you can use the `build` template engine to inject it using
+ `` {{ build `Password` }} ``. In HCL templates, you can do the same thing by
+ accessing the `build` variables For example:
+
+
+
+
+```hcl
+provisioner "powershell" {
+ elevated_user = "Administrator"
+ elevated_password = build.Password
+}
+```
+
+
+
+
+```json
+{
+ "type": "powershell",
+ "elevated_user": "Administrator",
+ "elevated_password": "{{ build `Password` }}",
+ ...
+},
+```
+
+
+
+
+If you specify an empty `elevated_password` value then the PowerShell
+script is run as a service account. For example:
+
+
+
+
+```hcl
+provisioner "powershell" {
+ elevated_user = "SYSTEM"
+ elevated_password = ""
+}
+```
+
+
+
+
+```json
+{
+ "type": "powershell",
+ "elevated_user": "SYSTEM",
+ "elevated_password": "",
+ ...
+},
+```
+
+
+
+
+- `execution_policy` - To run ps scripts on Windows, Packer defaults this to
+ "bypass" and wraps the command to run. Setting this to "none" will prevent
+ wrapping, allowing to see exit codes on Docker for Windows. Possible values
+ are `bypass`, `allsigned`, `default`, `remotesigned`, `restricted`,
+ `undefined`, `unrestricted`, and `none`.
+
+- `remote_path` (string) - The path where the PowerShell script will be
+ uploaded to within the target build machine. This defaults to
+ `C:/Windows/Temp/script-UUID.ps1` where UUID is replaced with a dynamically
+ generated string that uniquely identifies the script.
+
+ This setting allows users to override the default upload location. The
+ value must be a writable location and any parent directories must already
+ exist.
+
+- `remote_env_var_path` (string) - Environment variables required within the
+ remote environment are uploaded within a PowerShell script and then enabled
+ by 'dot sourcing' the script immediately prior to execution of the main
+ command or script.
+
+ The path the environment variables script will be uploaded to defaults to
+ `C:/Windows/Temp/packer-ps-env-vars-UUID.ps1` where UUID is replaced with a
+ dynamically generated string that uniquely identifies the script.
+
+ This setting allows users to override the location the environment variable
+ script is uploaded to. The value must be a writable location and any parent
+ directories must already exist.
+
+- `skip_clean` (bool) - Whether to clean scripts up after executing the provisioner.
+ Defaults to false. When true any script created by a non-elevated Powershell
+ provisioner will be removed from the remote machine. Elevated scripts,
+ along with the scheduled tasks, will always be removed regardless of the
+ value set for `skip_clean`.
+
+- `start_retry_timeout` (string) - The amount of time to attempt to _start_
+ the remote process. By default this is `5m` or 5 minutes. This setting
+ exists in order to deal with times when SSH may restart, such as a system
+ reboot. Set this to a higher value if reboots take a longer amount of time.
+
+- `pause_after` (string) - Wait the amount of time after provisioning a PowerShell
+ script, this pause be taken if all previous steps were successful.
+
+@include 'provisioners/common-config.mdx'
+
+## Default Environmental Variables
+
+In addition to being able to specify custom environmental variables using the
+`environment_vars` configuration, the provisioner automatically defines certain
+commonly useful environmental variables:
+
+- `PACKER_BUILD_NAME` is set to the [name of the
+ build](/packer/docs/templates/legacy_json_templates/builders#named-builds) that Packer is running.
+ This is most useful when Packer is making multiple builds and you want to
+ distinguish them slightly from a common provisioning script.
+
+- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
+ the machine that the script is running on. This is useful if you want to
+ run only certain parts of the script on systems built with certain
+ builders.
+
+- `PACKER_HTTP_ADDR` If using a builder that provides an HTTP server for file
+ transfer (such as `hyperv`, `parallels`, `qemu`, `virtualbox`, and `vmware`), this
+ will be set to the address. You can use this address in your provisioner to
+ download large files over HTTP. This may be useful if you're experiencing
+ slower speeds using the default file provisioner. A file provisioner using
+ the `winrm` communicator may experience these types of difficulties.
+
+## Combining the PowerShell Provisioner with the SSH Communicator
+
+The good news first. If you are using the [Microsoft port of
+OpenSSH](https://github.com/PowerShell/Win32-OpenSSH/wiki) then the provisioner
+should just work as expected - no extra configuration effort is required.
+
+Now the caveats. If you are using an alternative configuration, and your SSH
+connection lands you in a \*nix shell on the remote host, then you will most
+likely need to manually set the `execute_command`; The default
+`execute_command` used by Packer will not work for you. When configuring the
+command you will need to ensure that any dollar signs or other characters that
+may be incorrectly interpreted by the remote shell are escaped accordingly.
+
+The following example shows how the standard `execute_command` can be
+reconfigured to work on a remote system with
+[Cygwin/OpenSSH](https://cygwin.com/) installed. The `execute_command` has each
+dollar sign backslash escaped so that it is not interpreted by the remote Bash
+shell - Bash being the default shell for Cygwin environments.
+
+
+
+
+```hcl
+provisioner "powershell" {
+ execute_command = "powershell -executionpolicy bypass \"& { if (Test-Path variable:global:ProgressPreference){\\$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit \\$LastExitCode }\""
+ inline = [ "Write-Host \"Hello from PowerShell\""]
+}
+```
+
+
+
+
+```json
+"provisioners": [
+ {
+ "type": "powershell",
+ "execute_command": "powershell -executionpolicy bypass \"& { if (Test-Path variable:global:ProgressPreference){\\$ProgressPreference='SilentlyContinue'};. {{.Vars}}; &'{{.Path}}'; exit \\$LastExitCode }\"",
+ "inline": ["Write-Host \"Hello from PowerShell\""]
+ }
+]
+```
+
+
+
+
+## Packer's Handling of Characters Special to PowerShell
+
+The escape character in PowerShell is the `backtick`, also sometimes referred
+to as the `grave accent`. When, and when not, to escape characters special to
+PowerShell is probably best demonstrated with a series of examples.
+
+### When To Escape...
+
+Users need to deal with escaping characters special to PowerShell when they
+appear _directly_ in commands used in the `inline` PowerShell provisioner and
+when they appear _directly_ in the users own scripts. Note that where double
+quotes appear within double quotes, the addition of a backslash escape is
+required for the JSON template to be parsed correctly.
+
+
+
+
+```hcl
+provisioner "powershell" {
+ inline = [
+ "Write-Host \"A literal dollar `$ must be escaped\"",
+ "Write-Host \"A literal backtick `` must be escaped\"",
+ "Write-Host \"Here `\"double quotes`\" must be escaped\"",
+ "Write-Host \"Here `'single quotes`' don`'t really need to be\"",
+ "Write-Host \"escaped... but it doesn`'t hurt to do so.\"",
+ ]
+}
+```
+
+
+
+
+```json
+ "provisioners": [
+ {
+ "type": "powershell",
+ "inline": [
+ "Write-Host \"A literal dollar `$ must be escaped\"",
+ "Write-Host \"A literal backtick `` must be escaped\"",
+ "Write-Host \"Here `\"double quotes`\" must be escaped\"",
+ "Write-Host \"Here `'single quotes`' don`'t really need to be\"",
+ "Write-Host \"escaped... but it doesn`'t hurt to do so.\""
+ ]
+ }
+ ]
+```
+
+
+
+
+The above snippet should result in the following output on the Packer console:
+
+```shell-session
+==> amazon-ebs: Provisioning with Powershell...
+==> amazon-ebs: Provisioning with PowerShell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner508190439
+ amazon-ebs: A literal dollar $ must be escaped
+ amazon-ebs: A literal backtick ` must be escaped
+ amazon-ebs: Here "double quotes" must be escaped
+ amazon-ebs: Here 'single quotes' don't really need to be
+ amazon-ebs: escaped... but it doesn't hurt to do so.
+```
+
+### When Not To Escape...
+
+Special characters appearing in user environment variable values and in the
+`elevated_user` and `elevated_password` fields will be automatically dealt with
+for the user. There is no need to use escapes in these instances.
+
+
+
+
+```hcl
+variable "psvar" {
+ type = string
+ default = "My$tring"
+}
+
+build {
+ sources = ["source.amazon-ebs.example"]
+
+ provisioner "powershell" {
+ elevated_user = "Administrator"
+ elevated_password = "Super$3cr3t!"
+ inline = ["Write-Output \"The dollar in the elevated_password is interpreted correctly\""]
+ }
+ provisioner "powershell" {
+ environment_vars = [
+ "VAR1=A$Dollar",
+ "VAR2=A`Backtick",
+ "VAR3=A'SingleQuote",
+ "VAR4=A\"DoubleQuote",
+ "VAR5=${var.psvar}",
+ ]
+ inline = [
+ "Write-Output \"In the following examples the special character is interpreted correctly:\"",
+ "Write-Output \"The dollar in VAR1: $Env:VAR1\"",
+ "Write-Output \"The backtick in VAR2: $Env:VAR2\"",
+ "Write-Output \"The single quote in VAR3: $Env:VAR3\"",
+ "Write-Output \"The double quote in VAR4: $Env:VAR4\"",
+ "Write-Output \"The dollar in VAR5 (expanded from a user var): $Env:VAR5\"",
+ ]
+ }
+}
+```
+
+
+
+
+```json
+{
+ "variables": {
+ "psvar": "My$tring"
+ },
+ ...
+ "provisioners": [
+ {
+ "type": "powershell",
+ "elevated_user": "Administrator",
+ "elevated_password": "Super$3cr3t!",
+ "inline": "Write-Output \"The dollar in the elevated_password is interpreted correctly\""
+ },
+ {
+ "type": "powershell",
+ "environment_vars": [
+ "VAR1=A$Dollar",
+ "VAR2=A`Backtick",
+ "VAR3=A'SingleQuote",
+ "VAR4=A\"DoubleQuote",
+ "VAR5={{user `psvar`}}"
+ ],
+ "inline": [
+ "Write-Output \"In the following examples the special character is interpreted correctly:\"",
+ "Write-Output \"The dollar in VAR1: $Env:VAR1\"",
+ "Write-Output \"The backtick in VAR2: $Env:VAR2\"",
+ "Write-Output \"The single quote in VAR3: $Env:VAR3\"",
+ "Write-Output \"The double quote in VAR4: $Env:VAR4\"",
+ "Write-Output \"The dollar in VAR5 (expanded from a user var): $Env:VAR5\""
+ ]
+ }
+ ]
+ ...
+}
+```
+
+
+
+
+The above snippet should result in the following output on the Packer console:
+
+```shell-session
+==> amazon-ebs: Provisioning with Powershell...
+==> amazon-ebs: Provisioning with PowerShell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner961728919
+ amazon-ebs: The dollar in the elevated_password is interpreted correctly
+==> amazon-ebs: Provisioning with Powershell...
+==> amazon-ebs: Provisioning with PowerShell script: /var/folders/15/d0f7gdg13rnd1cxp7tgmr55c0000gn/T/packer-powershell-provisioner142826554
+ amazon-ebs: In the following examples the special character is interpreted correctly:
+ amazon-ebs: The dollar in VAR1: A$Dollar
+ amazon-ebs: The backtick in VAR2: A`Backtick
+ amazon-ebs: The single quote in VAR3: A'SingleQuote
+ amazon-ebs: The double quote in VAR4: A"DoubleQuote
+ amazon-ebs: The dollar in VAR5 (expanded from a user var): My$tring
+```
diff --git a/content/packer/v1.10.x/content/docs/provisioners/shell-local.mdx b/content/packer/v1.10.x/content/docs/provisioners/shell-local.mdx
new file mode 100644
index 0000000000..a8bbea4131
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/shell-local.mdx
@@ -0,0 +1,576 @@
+---
+description: |
+ shell-local will run a shell script of your choosing on the machine where
+ Packer is being run - in other words, shell-local will run the shell script on
+ your build server, or your desktop, etc., rather than the remote/guest machine
+ being provisioned by Packer.
+page_title: Shell (Local) - Provisioners
+---
+
+
+
+
+
+# Local Shell Provisioner
+
+Type: `shell-local`
+
+shell-local will run a shell script of your choosing on the machine where
+Packer is being run - in other words, shell-local will run the shell script on
+your build server, or your desktop, etc., rather than the remote/guest machine
+being provisioned by Packer.
+
+The [remote shell](/packer/docs/provisioners/shell) provisioner executes shell
+scripts on a remote machine.
+
+## Basic Example
+
+The example below is fully functional.
+
+
+
+
+```hcl
+source "file" "example" {
+ content = "example content"
+}
+
+build {
+ source "source.file.example" {
+ target = "./test_artifact.txt"
+ }
+
+ provisioner "shell-local" {
+ inline = ["echo foo"]
+ }
+}
+```
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "file",
+ "name": "example",
+ "target": "./test_artifact.txt",
+ "content": "example content"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "inline": ["echo foo"]
+ }
+ ]
+}
+```
+
+
+
+
+## Configuration Reference
+
+The reference of available configuration options is listed below. The only
+required element is `command`.
+
+Exactly _one_ of the following is required:
+
+- `command` (string) - This is a single command to execute. It will be
+ written to a temporary file and run using the `execute_command` call below.
+ If you are building a Windows VM on AWS, Azure, Google Compute, or OpenStack
+ and would like to access the generated password that Packer uses to connect
+ to the instance via WinRM, you can use the template variable `{{.WinRMPassword}}`
+ to set this as an environment variable.
+
+- `inline` (array of strings) - This is an array of commands to execute. The
+ commands are concatenated by newlines and turned into a single file, so
+ they are all executed within the same context. This allows you to change
+ directories in one command and use something in the directory in the next
+ and so on. Inline scripts are the easiest way to pull off simple tasks
+ within the machine in which Packer is running.
+
+- `script` (string) - The path to a script to execute. This path can be
+ absolute or relative. If it is relative, it is relative to the working
+ directory when Packer is executed.
+
+- `scripts` (array of strings) - An array of scripts to execute. The scripts
+ will be executed in the order specified. Each script is executed in
+ isolation, so state such as variables from one script won't carry on to the
+ next.
+
+Optional parameters:
+
+- `env` (map of strings) - A map of key/value pairs to inject prior to the
+ execute_command. Packer injects some environmental variables by default into
+ the environment, as well, which are covered in the section below. Duplicate
+ `env` settings override `environment_vars` settings.
+
+- `environment_vars` (array of strings) - An array of key/value pairs to
+ inject prior to the `execute_command`. The format should be `key=value`.
+ Packer injects some environmental variables by default into the
+ environment, as well, which are covered in the section below. If you are
+ building a Windows VM on AWS, Azure, Google Compute, or OpenStack and would
+ like to access the generated password that Packer uses to connect to the
+ instance via WinRM, you can use the template variable `{{.WinRMPassword}}`
+ to set this as an environment variable. For example:
+ `"environment_vars": "WINRMPASS={{.WinRMPassword}}"`
+
+- `env_var_format` (string) - When we parse the environment_vars that you
+ provide, this gives us a string template to use in order to make sure that
+ we are setting the environment vars correctly. By default on Windows hosts
+ this format is `set %s=%s &&` and on Unix, it is `%s='%s'`. You probably
+ won't need to change this format, but you can see usage examples for where
+ it is necessary below.
+
+- `execute_command` (array of strings) - The command used to execute the
+ script. By default this is `["/bin/sh", "-c", "{{.Vars}}", "{{.Script}}"]`
+ on Unix and `["cmd", "/c", "{{.Vars}}", "{{.Script}}"]` on Windows. This is
+ treated as a [template engine](/packer/docs/templates/legacy_json_templates/engine). There are two
+ available variables: `Script`, which is the path to the script to run, and
+ `Vars`, which is the list of `environment_vars`, if configured.
+
+ If you choose to set this option, make sure that the first element in the
+ array is the shell program you want to use (for example, "sh"), and a later
+ element in the array must be `{{.Script}}`.
+
+ This option provides you a great deal of flexibility. You may choose to
+ provide your own shell program, for example "/usr/local/bin/zsh" or even
+ "powershell.exe". However, with great power comes great responsibility -
+ these commands are not officially supported and things like environment
+ variables may not work if you use a different shell than the default.
+
+ For backwards compatibility, you may also use `{{.Command}}`, but it is
+ decoded the same way as `{{.Script}}`. We recommend using `{{.Script}}` for the
+ sake of clarity, as even when you set only a single `command` to run,
+ Packer writes it to a temporary file and then runs it as a script.
+
+ If you are building a Windows VM on AWS, Azure, Google Compute, or OpenStack
+ and would like to access the generated password that Packer uses to connect
+ to the instance via WinRM, you can use the template variable `{{.WinRMPassword}}`
+ to set this as an environment variable.
+
+- `inline_shebang` (string) - The
+ [shebang](http://en.wikipedia.org/wiki/Shebang_%28Unix%29) value to use
+ when running commands specified by `inline`. By default, this is
+ `/bin/sh -e`. If you're not using `inline`, then this configuration has no
+ effect. **Important:** If you customize this, be sure to include something
+ like the `-e` flag, otherwise individual steps failing won't fail the
+ provisioner.
+
+- `only_on` (array of strings) - This is an array of [runtime operating
+ systems](https://go.dev/doc/install/source#environment) where
+ `shell-local` will execute. This allows you to execute `shell-local` _only_
+ on specific operating systems. By default, shell-local will always run if
+ `only_on` is not set."
+
+- `use_linux_pathing` (bool) - This is only relevant to Windows hosts. If you
+ are running Packer in a Windows environment with the Windows Subsystem for
+ Linux feature enabled, and would like to invoke a bash script rather than
+ invoking a Cmd script, you'll need to set this flag to true; it tells
+ Packer to use the Linux subsystem path for your script rather than the
+ Windows path. (e.g. /mnt/c/path/to/your/file instead of
+ C:/path/to/your/file). Please see the example below for more guidance on
+ how to use this feature. If you are not on a Windows host, or you do not
+ intend to use the shell-local provisioner to run a bash script, please
+ ignore this option.
+
+- `valid_exit_codes` (list of ints) - Valid exit codes for the script. By
+ default this is `0`.
+
+@include 'provisioners/common-config.mdx'
+
+## Execute Command
+
+To many new users, the `execute_command` is puzzling. However, it provides an
+important function: customization of how the command is executed. The most
+common use case for this is dealing with **sudo password prompts**. You may
+also need to customize this if you use a non-POSIX shell, such as `tcsh` on
+FreeBSD.
+
+### The Windows Linux Subsystem
+
+The shell-local provisioner was designed with the idea of allowing you to run
+commands in your local operating system's native shell. For Windows, we've
+assumed in our defaults that this is Cmd. However, it is possible to run a bash
+script as part of the Windows Linux Subsystem from the shell-local provisioner,
+by modifying the `execute_command` and the `use_linux_pathing` options in the
+provisioner config.
+
+The example below is a fully functional test config.
+
+One limitation of this offering is that "inline" and "command" options are not
+available to you; please limit yourself to using the "script" or "scripts"
+options instead.
+
+Please note that the WSL is a beta feature, and this tool is not guaranteed to
+work as you expect it to.
+
+
+
+
+```hcl
+source "null" "example" {
+ communicator = "none"
+}
+
+build {
+ sources = [
+ "source.null.example"
+ ]
+
+ provisioner "shell-local"{
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
+ execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
+ use_linux_pathing = true
+ scripts = ["C:/Users/me/scripts/example_bash.sh"]
+ }
+ provisioner "shell-local"{
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
+ execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
+ use_linux_pathing = true
+ script = "C:/Users/me/scripts/example_bash.sh"
+ }
+}
+```
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
+ "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
+ "use_linux_pathing": true,
+ "scripts": ["C:/Users/me/scripts/example_bash.sh"]
+ },
+ {
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
+ "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
+ "use_linux_pathing": true,
+ "script": "C:/Users/me/scripts/example_bash.sh"
+ }
+ ]
+}
+```
+
+
+
+
+## Default Environmental Variables
+
+In addition to being able to specify custom environmental variables using the
+`environment_vars` configuration, the provisioner automatically defines certain
+commonly useful environmental variables:
+
+- `PACKER_BUILD_NAME` is set to the name of the build that Packer is running.
+ This is most useful when Packer is making multiple builds and you want to
+ distinguish them slightly from a common provisioning script.
+
+- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
+ the machine that the script is running on. This is useful if you want to
+ run only certain parts of the script on systems built with certain
+ builders.
+
+- `PACKER_HTTP_ADDR` If using a builder that provides an HTTP server for file
+ transfer (such as `hyperv`, `parallels`, `qemu`, `virtualbox`, and `vmware`), this
+ will be set to the address. You can use this address in your provisioner to
+ download large files over HTTP. This may be useful if you're experiencing
+ slower speeds using the default file provisioner. A file provisioner using
+ the `winrm` communicator may experience these types of difficulties.
+
+## Safely Writing A Script
+
+Whether you use the `inline` option, or pass it a direct `script` or `scripts`,
+it is important to understand a few things about how the `shell-local`
+provisioner works to run it safely and easily. This understanding will save you
+much time in the process.
+
+### Once Per Builder
+
+The `shell-local` script(s) you pass are run once per builder. That means that
+if you have an `amazon-ebs` builder and a `docker` builder, your script will be
+run twice. If you have 3 builders, it will run 3 times, once for each builder.
+
+### Always Exit Intentionally
+
+If any provisioner fails, the `packer build` stops and all interim artifacts
+are cleaned up.
+
+For a shell script, that means the script **must** exit with a zero code. You
+_must_ be extra careful to `exit 0` when necessary.
+
+## Usage Examples:
+
+### Windows Host
+
+Example of running a .cmd file on Windows:
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest1"]
+ scripts = ["./scripts/test_cmd.cmd"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest1"],
+ "scripts": ["./scripts/test_cmd.cmd"]
+}
+```
+
+
+
+
+Contents of "test_cmd.cmd":
+
+ echo %SHELLLOCALTEST%
+
+Example of running an inline command on Windows: Required customization:
+tempfile_extension
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest2"],
+ tempfile_extension = ".cmd",
+ inline = [echo "%SHELLLOCALTEST%"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest2"],
+ "tempfile_extension": ".cmd",
+ "inline": ["echo %SHELLLOCALTEST%"]
+}
+```
+
+
+
+
+Example of running a bash command on Windows using WSL: Required
+customizations: use_linux_pathing and execute_command
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest3"],
+ execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
+ use_linux_pathing = true
+ script = "./scripts/example_bash.sh"
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest3"],
+ "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
+ "use_linux_pathing": true,
+ "script": "./scripts/example_bash.sh"
+}
+```
+
+
+
+
+Contents of `example_bash.sh`:
+
+ #!/bin/bash
+ echo $SHELLLOCALTEST
+
+Example of running a PowerShell script on Windows: Required customizations:
+`env_var_format` and `execute_command`
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ environment_vars = ["SHELLLOCALTEST=ShellTest4"]
+ execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
+ env_var_format = "$env:%s=\"%s\"; "
+ script = "./scripts/example_ps.ps1"
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest4"],
+ "execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
+ "env_var_format": "$env:%s=\"%s\"; ",
+ "script": "./scripts/example_ps.ps1"
+}
+```
+
+
+
+
+Example of running a PowerShell script on Windows as "inline": Required
+customizations: `env_var_format`, `tempfile_extension`, and `execute_command`
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ tempfile_extension = ".ps1"
+ environment_vars = ["SHELLLOCALTEST=ShellTest5"]
+ execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
+ env_var_format = "$env:%s=\"%s\"; "
+ inline = ["write-output $env:SHELLLOCALTEST"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "tempfile_extension": ".ps1",
+ "environment_vars": ["SHELLLOCALTEST=ShellTest5"],
+ "execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
+ "env_var_format": "$env:%s=\"%s\"; ",
+ "inline": ["write-output $env:SHELLLOCALTEST"]
+}
+```
+
+
+
+
+### Unix Host
+
+Example of running a Shell script on Unix:
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
+ scripts = ["./scripts/example_bash.sh"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
+ "scripts": ["./scripts/example_bash.sh"]
+}
+```
+
+
+
+
+Example of running a Shell script "inline" on Unix:
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
+ inline = ["echo hello", "echo $PROVISIONERTEST"]
+}
+
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
+ "inline": ["echo hello", "echo $PROVISIONERTEST"]
+}
+```
+
+
+
+
+Example of running a Python script on Unix:
+
+
+
+
+```hcl
+provisioner "shell-local" {
+ script = "hello.py"
+ environment_vars = ["HELLO_USER=packeruser"]
+ execute_command = [
+ "/bin/sh",
+ "-c",
+ "{{.Vars}} /usr/local/bin/python {{.Script}}"
+ ]
+}
+
+```
+
+
+
+
+```json
+{
+ "type": "shell-local",
+ "script": "hello.py",
+ "environment_vars": ["HELLO_USER=packeruser"],
+ "execute_command": [
+ "/bin/sh",
+ "-c",
+ "{{.Vars}} /usr/local/bin/python {{.Script}}"
+ ]
+}
+```
+
+
+
+
+```text
+Where "hello.py" contains:
+
+ import os
+
+ print('Hello, %s!' % os.getenv("HELLO_USER"))
+```
diff --git a/content/packer/v1.10.x/content/docs/provisioners/shell.mdx b/content/packer/v1.10.x/content/docs/provisioners/shell.mdx
new file mode 100644
index 0000000000..ca10852cf6
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/shell.mdx
@@ -0,0 +1,413 @@
+---
+description: |
+ The shell Packer provisioner provisions machines built by Packer using shell
+ scripts. Shell provisioning is the easiest way to get software installed and
+ configured on a machine.
+page_title: Shell - Provisioners
+---
+
+
+
+
+
+# Shell Provisioner
+
+Type: `shell`
+
+The shell Packer provisioner provisions machines built by Packer using shell
+scripts. Shell provisioning is the easiest way to get software installed and
+configured on a machine.
+
+-> **Building Windows images?** You probably want to use the
+[PowerShell](/packer/docs/provisioners/powershell) or [Windows
+Shell](/packer/docs/provisioners/windows-shell) provisioners.
+
+## Basic Example
+
+The example below is fully functional.
+
+
+
+
+```hcl
+provisioner "shell" {
+ inline = ["echo foo"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell",
+ "inline": ["echo foo"]
+}
+```
+
+
+
+
+## Configuration Reference
+
+@include 'provisioners/shell-config.mdx'
+
+- `env` (map of strings) - A map of key/value pairs to inject prior to the
+ execute_command. Packer injects some environmental variables by default into
+ the environment, as well, which are covered in the section below. Duplicate
+ `env` settings override `environment_vars` settings.
+
+- `environment_vars` (array of strings) - An array of key/value pairs to
+ inject prior to the execute_command. The format should be `key=value`.
+ Packer injects some environmental variables by default into the
+ environment, as well, which are covered in the section below.
+
+- `env_var_format` (string) - When we parse the environment_vars that you
+ provide, this gives us a string template to use in order to make sure that
+ we are setting the environment vars correctly. By default it is `"%s='%s' "`.
+ When used in conjunction with `use_env_var_file` the default is `"export %s='%s'\n"`
+
+- `use_env_var_file` (boolean) - If true, Packer will write your environment
+ variables to a tempfile and source them from that file, rather than
+ declaring them inline in our execute_command. The default
+ `execute_command` will be
+ `chmod +x {{.Path}}; . {{.EnvVarFile}} && {{.Path}}`. This option is
+ unnecessary for most cases, but if you have extra quoting in your custom
+ `execute_command`, then this may be required for proper script
+ execution. Default: `false`.
+
+- `execute_command` (string) - The command to use to execute the script. By
+ default this is `chmod +x {{ .Path }}; {{ .Vars }} {{ .Path }}`, unless the
+ user has set `"use_env_var_file": true` -- in that case, the default
+ `execute_command` is `chmod +x {{.Path}}; . {{.EnvVarFile}} && {{.Path}}`.
+ This is a [template engine](/packer/docs/templates/legacy_json_templates/engine). Therefore, you may
+ use user variables and template functions in this field. In addition, there
+ are three available extra variables:
+
+ - `Path` is the path to the script to run
+ - `Vars` is the list of `environment_vars`, if configured.
+ - `EnvVarFile` is the path to the file containing env vars, if
+ `use_env_var_file` is true.
+
+- `expect_disconnect` (boolean) - Defaults to `false`. When `true`, allow the
+ server to disconnect from Packer without throwing an error. A disconnect
+ might happen if you restart the SSH server or reboot the host.
+
+- `inline_shebang` (string) - The
+ [shebang](https://en.wikipedia.org/wiki/Shebang_%28Unix%29) value to use
+ when running commands specified by `inline`. By default, this is
+ `/bin/sh -e`. If you're not using `inline`, then this configuration has no
+ effect. **Important:** If you customize this, be sure to include something
+ like the `-e` flag, otherwise individual steps failing won't fail the
+ provisioner.
+
+- `remote_folder` (string) - The folder where the uploaded script will reside
+ on the machine. This defaults to `/tmp`.
+
+- `remote_file` (string) - The filename the uploaded script will have on the
+ machine. This defaults to `script_nnn.sh`.
+
+- `remote_path` (string) - The full path to the uploaded script will have on
+ the machine. By default this is `remote_folder/remote_file`, if set this
+ option will override both `remote_folder` and `remote_file`.
+
+- `skip_clean` (boolean) - If true, specifies that the helper scripts
+ uploaded to the system will not be removed by Packer. This defaults to
+ `false` (clean scripts from the system).
+
+- `start_retry_timeout` (string) - The amount of time to attempt to _start_
+ the remote process. By default this is `5m` or 5 minutes. This setting
+ exists in order to deal with times when SSH may restart, such as a system
+ reboot. Set this to a higher value if reboots take a longer amount of time.
+
+- `pause_after` (string) - Wait the amount of time after provisioning a shell
+ script, this pause be taken if all previous steps were successful.
+
+@include 'provisioners/common-config.mdx'
+
+## Execute Command Example
+
+To many new users, the `execute_command` is puzzling. However, it provides an
+important function: customization of how the command is executed. The most
+common use case for this is dealing with **sudo password prompts**. You may
+also need to customize this if you use a non-POSIX shell, such as `tcsh` on
+FreeBSD.
+
+### Sudo Example
+
+Some operating systems default to a non-root user. For example if you login as
+`ubuntu` and can sudo using the password `packer`, then you'll want to change
+`execute_command` to be:
+
+```text
+"echo 'packer' | sudo -S sh -c '{{ .Vars }} {{ .Path }}'"
+```
+
+The `-S` flag tells `sudo` to read the password from stdin, which in this case
+is being piped in with the value of `packer`.
+
+The above example won't work if your environment vars contain spaces or single
+quotes; in these cases try removing the single quotes:
+
+```text
+"echo 'packer' | sudo -S env {{ .Vars }} {{ .Path }}"
+```
+
+By setting the `execute_command` to this, your script(s) can run with root
+privileges without worrying about password prompts.
+
+### FreeBSD Example
+
+FreeBSD's default shell is `tcsh`, which deviates from POSIX semantics. In
+order for packer to pass environment variables you will need to change the
+`execute_command` to:
+
+```text
+chmod +x {{ .Path }}; env {{ .Vars }} {{ .Path }}
+```
+
+Note the addition of `env` before `{{ .Vars }}`.
+
+## Default Environmental Variables
+
+In addition to being able to specify custom environmental variables using the
+`environment_vars` configuration, the provisioner automatically defines certain
+commonly useful environmental variables:
+
+- `PACKER_BUILD_NAME` is set to the [name of the
+ build](/packer/docs/templates/legacy_json_templates/builders#named-builds) that Packer is running.
+ This is most useful when Packer is making multiple builds and you want to
+ distinguish them slightly from a common provisioning script.
+
+- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
+ the machine that the script is running on. This is useful if you want to
+ run only certain parts of the script on systems built with certain
+ builders.
+
+- `PACKER_HTTP_ADDR` If using a builder that provides an HTTP server for file
+ transfer (such as `hyperv`, `parallels`, `qemu`, `virtualbox`, and `vmware`), this
+ will be set to the address. You can use this address in your provisioner to
+ download large files over HTTP. This may be useful if you're experiencing
+ slower speeds using the default file provisioner. A file provisioner using
+ the `winrm` communicator may experience these types of difficulties.
+
+## Handling Reboots
+
+Provisioning sometimes involves restarts, usually when updating the operating
+system. Packer is able to tolerate restarts via the shell provisioner.
+
+Packer handles this by retrying to start scripts for a period of time before
+failing. This allows time for the machine to start up and be ready to run
+scripts. The amount of time the provisioner will wait is configured using
+`start_retry_timeout`, which defaults to a few minutes.
+
+Sometimes, when executing a command like `reboot`, the shell script will return
+and Packer will start executing the next one before SSH actually quits and the
+machine restarts. For this, use `pause_before` to make Packer wait before
+executing the next script:
+
+
+
+
+```hcl
+provisioner "shell" {
+ script = "script.sh"
+ pause_before = "10s"
+ timeout = "10s"
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh",
+ "pause_before": "10s",
+ "timeout": "10s"
+}
+```
+
+
+
+
+Some OS configurations don't properly kill all network connections on reboot,
+causing the provisioner to hang despite a reboot occurring. In this case, make
+sure you shut down the network interfaces on reboot or in your shell script.
+For example, on Gentoo:
+
+```text
+/etc/init.d/net.eth0 stop
+```
+
+## SSH Agent Forwarding
+
+Some provisioning requires connecting to remote SSH servers from within the
+packer instance. The below example is for pulling code from a private git
+repository utilizing openssh on the client. Make sure you are running
+`ssh-agent` and add your git repo SSH keys into it using
+`ssh-add /path/to/key`. When the Packer instance needs access to the SSH keys
+the agent will forward the request back to your `ssh-agent`.
+
+Note: when provisioning via git you should add the git server keys into the
+`~/.ssh/known_hosts` file otherwise the git command could hang awaiting input.
+This can be done by copying the file in via the [file
+provisioner](/packer/docs/provisioners/file) (more secure) or using `ssh-keyscan`
+to populate the file (less secure). An example of the latter accessing github
+would be:
+
+
+
+
+```hcl
+provisioner "shell" {
+ inline = [
+ "sudo apt-get install -y git",
+ "ssh-keyscan github.com >> ~/.ssh/known_hosts",
+ "git clone git@github.com:exampleorg/myprivaterepo.git"
+ ]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell",
+ "inline": [
+ "sudo apt-get install -y git",
+ "ssh-keyscan github.com >> ~/.ssh/known_hosts",
+ "git clone git@github.com:exampleorg/myprivaterepo.git"
+ ]
+}
+```
+
+
+
+
+## Troubleshooting
+
+_My shell script doesn't work correctly on Ubuntu_
+
+- On Ubuntu, the `/bin/sh` shell is
+ [dash](https://en.wikipedia.org/wiki/Debian_Almquist_shell). If your script
+ has [bash]()-specific
+ commands in it, then put `#!/bin/bash -e` at the top of your script.
+ Differences between dash and bash can be found on the
+ [DashAsBinSh](https://wiki.ubuntu.com/DashAsBinSh) Ubuntu wiki page.
+
+_My shell works when I login but fails with the shell provisioner_
+
+- See the above tip. More than likely, your login shell is using `/bin/bash`
+ while the provisioner is using `/bin/sh`.
+
+_My installs hang when using `apt-get` or `yum`_
+
+- Make sure you add a `-y` to the command to prevent it from requiring user
+ input before proceeding.
+
+_How do I tell what my shell script is doing?_
+
+- Adding a `-x` flag to the shebang at the top of the script (`#!/bin/sh -x`)
+ will echo the script statements as it is executing.
+
+_My builds don't always work the same_
+
+- Some distributions start the SSH daemon before other core services which
+ can create race conditions. Your first provisioner can tell the machine to
+ wait until it completely boots.
+
+
+
+
+```hcl
+provisioner "shell" {
+ inline = ["sleep 10"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "shell",
+ "inline": ["sleep 10"]
+}
+```
+
+
+
+
+## Quoting Environment Variables
+
+Packer manages quoting for you, so you shouldn't have to worry about it. Below
+is an example of Packer template inputs and what you should expect to get out:
+
+
+
+
+```hcl
+provisioner "shell" {
+ environment_vars = [
+ "FOO=foo",
+ "BAR=bar's",
+ "BAZ=baz=baz",
+ "QUX==qux",
+ "FOOBAR=foo bar",
+ "FOOBARBAZ='foo bar baz'",
+ "QUX2=\"qux\""
+ ]
+ inline = [
+ "echo \"FOO is $FOO\"",
+ "echo \"BAR is $BAR\"",
+ "echo \"BAZ is $BAZ\"",
+ "echo \"QUX is $QUX\"",
+ "echo \"FOOBAR is $FOOBAR\"",
+ "echo \"FOOBARBAZ is $FOOBARBAZ\"",
+ "echo \"QUX2 is $QUX2\""
+ ]
+}
+```
+
+
+
+
+```json
+"provisioners": [
+ {
+ "type": "shell",
+ "environment_vars": ["FOO=foo",
+ "BAR=bar's",
+ "BAZ=baz=baz",
+ "QUX==qux",
+ "FOOBAR=foo bar",
+ "FOOBARBAZ='foo bar baz'",
+ "QUX2=\"qux\""],
+ "inline": ["echo \"FOO is $FOO\"",
+ "echo \"BAR is $BAR\"",
+ "echo \"BAZ is $BAZ\"",
+ "echo \"QUX is $QUX\"",
+ "echo \"FOOBAR is $FOOBAR\"",
+ "echo \"FOOBARBAZ is $FOOBARBAZ\"",
+ "echo \"QUX2 is $QUX2\""]
+ }
+]
+```
+
+
+
+
+Output:
+
+```text
+docker: FOO is foo
+docker: BAR is bar's
+docker: BAZ is baz=baz
+docker: QUX is =qux
+docker: FOOBAR is foo bar
+docker: FOOBARBAZ is 'foo bar baz'
+docker: QUX2 is "qux"
+```
diff --git a/content/packer/v1.10.x/content/docs/provisioners/windows-restart.mdx b/content/packer/v1.10.x/content/docs/provisioners/windows-restart.mdx
new file mode 100644
index 0000000000..9c78bced5c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/windows-restart.mdx
@@ -0,0 +1,112 @@
+---
+description: |
+ The Windows restart provisioner restarts a Windows machine and waits for it to
+ come back up.
+page_title: Windows Restart - Provisioners
+---
+
+
+
+
+
+# Windows Restart Provisioner
+
+Type: `windows-restart`
+
+The Windows restart provisioner initiates a reboot on a Windows machine and
+waits for the machine to come back online.
+
+The Windows provisioning process often requires multiple reboots, and this
+provisioner helps to ease that process.
+
+Packer expects the machine to be ready to continue provisioning after it
+reboots. Packer detects that the reboot has completed by making an RPC call
+through the Windows Remote Management (WinRM) service, not by ACPI functions,
+so Windows must be completely booted in order to continue.
+
+## Basic Example
+
+The example below is fully functional.
+
+
+
+
+```hcl
+provisioner "windows-restart" {}
+```
+
+
+
+
+```json
+{
+ "type": "windows-restart"
+}
+```
+
+
+
+
+## Configuration Reference
+
+The reference of available configuration options is listed below.
+
+Optional parameters:
+
+- `check_registry` (bool) - if `true`, checks for several registry keys that
+ indicate that the system is going to reboot. This is useful if an
+ installation kicks off a reboot and you want the provisioner to wait for
+ that reboot to complete before reconnecting. Please note that this option
+ is a beta feature, and we generally recommend that you finish installs that
+ auto-reboot (like Windows Updates) during your _autounattend_ phase before
+ the `winrm` provisioner connects.
+
+- `registry_keys` (array of strings) - if `check-registry` is `true`,
+ `windows-restart` will not reconnect until after all of the listed keys are
+ no longer present in the registry.
+
+```
+ default:
+
+ var DefaultRegistryKeys = []string{
+ "HKLM:SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending",
+ "HKLM:SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\PackagesPending",
+ "HKLM:Software\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootInProgress",
+ }
+```
+
+- `restart_command` (string) - The command to execute to initiate the
+ restart. By default this is `shutdown /r /f /t 0 /c "packer restart"`.
+
+- `restart_check_command` (string) - The command to run after executing `restart_command`
+ to check if the guest machine has restarted. This command will retry until the connection
+ to the guest machine has been restored or `restart_timeout` has exceeded.
+
+
+
+
+```hcl
+provisioner "windows-restart" {
+ restart_check_command = "powershell -command \"& {Write-Output 'restarted.'}\""
+}
+```
+
+
+
+
+```json
+{
+ "type": "windows-restart",
+ "restart_check_command": "powershell -command \"& {Write-Output 'restarted.'}\""
+}
+```
+
+
+
+
+- `restart_timeout` (string) - The timeout to wait for the restart. By
+ default this is 5 minutes. Example value: `5m`. If you are installing
+ updates or have a lot of startup services, you will probably need to
+ increase this duration.
+
+@include 'provisioners/common-config.mdx'
diff --git a/content/packer/v1.10.x/content/docs/provisioners/windows-shell.mdx b/content/packer/v1.10.x/content/docs/provisioners/windows-shell.mdx
new file mode 100644
index 0000000000..2663aedf7c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/provisioners/windows-shell.mdx
@@ -0,0 +1,101 @@
+---
+description: |
+ The windows-shell Packer provisioner runs commands on Windows using the cmd
+ shell.
+page_title: Windows Shell - Provisioners
+---
+
+
+
+
+
+# Windows Shell Provisioner
+
+Type: `windows-shell`
+
+The windows-shell Packer provisioner runs commands on a Windows machine using
+`cmd`. It assumes it is running over WinRM.
+
+## Basic Example
+
+The example below is fully functional.
+
+
+
+
+```hcl
+provisioner "windows-shell" {
+ inline = ["dir c:\\"]
+}
+```
+
+
+
+
+```json
+{
+ "type": "windows-shell",
+ "inline": ["dir c:\\"]
+}
+```
+
+
+
+
+## Configuration Reference
+
+@include 'provisioners/shell-config.mdx'
+
+- `env` (map of strings) - A map of key/value pairs to inject prior to the
+ execute_command. Packer injects some environmental variables by default into
+ the environment, as well, which are covered in the section below. Duplicate
+ `env` settings override `environment_vars` settings.
+
+- `environment_vars` (array of strings) - An array of key/value pairs to
+ inject prior to the execute_command. The format should be `key=value`.
+ Packer injects some environmental variables by default into the
+ environment, as well, which are covered in the section below.
+
+- `execute_command` (string) - The command to use to execute the script. By
+ default this is `{{ .Vars }}"{{ .Path }}"`. The value of this is treated as
+ [template engine](/packer/docs/templates/legacy_json_templates/engine). This is a
+ [template engine](/packer/docs/templates/legacy_json_templates/engine). Therefore, you may
+ use user variables and template functions in this field. In addition, there
+ are two available extra variables:
+
+ - `Path` is the path to the script to run
+ - `Vars` is the list of `environment_vars`, if configured.
+
+- `remote_path` (string) - The path where the script will be uploaded to in
+ the machine. This defaults to "c:/Windows/Temp/script.bat". This value must
+ be a writable location and any parent directories must already exist.
+
+- `start_retry_timeout` (string) - The amount of time to attempt to _start_
+ the remote process. By default this is "5m" or 5 minutes. This setting
+ exists in order to deal with times when SSH may restart, such as a system
+ reboot. Set this to a higher value if reboots take a longer amount of time.
+
+@include 'provisioners/common-config.mdx'
+
+## Default Environmental Variables
+
+In addition to being able to specify custom environmental variables using the
+`environment_vars` configuration, the provisioner automatically defines certain
+commonly useful environmental variables:
+
+- `PACKER_BUILD_NAME` is set to the [name of the
+ build](/packer/docs/templates/legacy_json_templates/builders#named-builds) that Packer is running.
+ This is most useful when Packer is making multiple builds and you want to
+ distinguish them slightly from a common provisioning script.
+
+- `PACKER_BUILDER_TYPE` is the type of the builder that was used to create
+ the machine that the script is running on. This is useful if you want to
+ run only certain parts of the script on systems built with certain
+ builders.
+
+- `PACKER_HTTP_ADDR` If using a builder that provides an HTTP server for file
+ transfer (such as `hyperv`, `parallels`, `qemu`, `virtualbox`, and `vmware`), this
+ will be set to the address. You can use this address in your provisioner to
+ download large files over HTTP. This may be useful if you're experiencing
+ slower speeds using the default file provisioner. A file provisioner using
+ the `winrm` communicator may experience these types of difficulties.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx
new file mode 100644
index 0000000000..e374af650e
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/hcp_packer_registry.mdx
@@ -0,0 +1,79 @@
+---
+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
+
+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.
+
+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).
+
+## Usage
+
+This block is available from version 1.7.7 of Packer.
+
+The presence of a `hcp_packer_registry` block in a build block will enable HCP
+Packer mode. Packer will push all builds within that build block to the remote
+registry if the appropriate HCP credentials are set (`HCP_CLIENT_ID` and
+`HCP_CLIENT_SECRET`). If no HCP credentials are set, Packer will fail the build
+and exit immediately to avoid any potential artifact drift between the defined
+builders (source blocks) and the HCP Packer registry.
+
+~> **Note:** You will receive an error if you try to reference metadata from a deactivated or deleted registry. An administrator can manually deactivate or delete a registry, and HCP Packer automatically deactivates registries with billing issues. Contact [HashiCorp Support](https://support.hashicorp.com/) with questions.
+
+```hcl
+# file: builds.pkr.hcl
+source "happycloud" "macos" {
+ os = "macos_amd64"
+}
+
+build {
+ hcp_packer_registry {
+ bucket_name = "ios-dev"
+
+ description = < packer build ./folder
+Build 'a.null.first-example' finished.
+Build 'a.null.second-example' finished.
+Build 'null.second-example' finished.
+
+==> Builds finished. The artifacts of successful builds are:
+--> a.null.first-example: Did not export anything. This is the null builder
+--> a.null.second-example: Did not export anything. This is the null builder
+--> null.second-example: Did not export anything. This is the null builder
+```
+
+### Running only specific builds
+
+The `-only`/`-except` flags will match a source's `type.name` and run 'only'
+matching **builders** (source) or all referenced builders 'except' the matching
+ones, for example with the same config file:
+
+```shell-session
+> packer build -only "*.second-example" ./folder
+Build 'null.second-example' finished.
+Build 'a.null.second-example' finished.
+
+==> Builds finished. The artifacts of successful builds are:
+--> a.null.second-example: Did not export anything. This is the null builder
+--> null.second-example: Did not export anything. This is the null builder
+```
+
+Here `'a.null.first-example'` was skipped.
+
+-> Note: It is not yet possible to match a named `build` block to do this, but
+this is soon going to be possible. So here "a.\*" will match nothing.
+
+## Related
+
+- A list of [community
+ builders](https://packer.io/community-tools#community-builders) is available.
+
+- Create your own [custom builder](/packer/docs/plugins/creation/custom-builders) !
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx
new file mode 100644
index 0000000000..9f7e981c5f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/post-processor.mdx
@@ -0,0 +1,108 @@
+---
+description: |
+ The post-processor block defines how a post-processor is configured.
+page_title: post-processor - build - Blocks
+---
+
+# 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 {
+ # ... build image
+ post-processor "checksum" { # checksum image
+ checksum_types = [ "md5", "sha512" ] # checksum the artifact
+ keep_input_artifact = true # keep the artifact
+ }
+
+ post-processor "amazon-import" { # upload image to amazon
+ }
+}
+```
+
+Each `post-processor` runs after each defined build. A post-processor takes the
+`Artifact` from a build. 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](/packer/docs/post-processors) section.
+
+A `post-processor` can also take the `Artifact` from another post-processor
+when it is defined in a [`post-processors`
+block](/packer/docs/templates/hcl_templates/blocks/build/post-processor) list, that is a list of
+chained post processors.
+
+-> Note: The input 'artifact' received by a post-processor will be automatically
+deleted by default.
+
+# Keep an input artifact
+
+To prevent an input artifact from being deleted, you can set the
+`keep_input_artifact` field to true to make Packer keep both artifacts. For
+example if we want to checksum an artifact and keep the artifact:
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ...
+ post-processor "checksum" {
+ checksum_types = [ "md5", "sha512" ]
+ keep_input_artifact = true
+ }
+}
+```
+
+# Run on Specific Builds
+
+You can use the `only` or `except` configurations to run a post-processor only
+with specific sources. These two configurations do what you expect: `only` will
+only run the post-processor on the specified sources and `except` will run the
+post-processor on anything other than the specified sources.
+
+An example of `only` being used is shown below, but the usage of `except` is
+effectively the same:
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ...
+ post-processor "checksum" {
+ checksum_types = [ "md5", "sha512" ]
+ keep_input_artifact = true
+ only = ["amazon-ebs.example"]
+ }
+}
+```
+
+The values within `only` or `except` are _source names_, not builder types.
+
+If you want to exclude certain post-processors when running `packer build`
+from the command line, you can do so:
+
+`packer build --except=checksum mytemplate.pkr.hcl` will not run the checksum
+post-processor. This command line exclusion works by referencing post-processor
+_name_. By default, the post-processor is named after is its type, as
+demonstrated above in the `checksum` example. You can make a post-processor's
+name unique by adding a "name" field to each post-processor block.
+
+While the `-except` flag can be used to filter out post-processors on the
+command line, the `-only` flag does not work for post-processors. If you wish
+to only run a post-processor for a given source build you must use the
+`only=[source]` syntax inside of your hcl templates, as described above.
+
+
+## Build Contextual Variables
+
+Packer allows to access connection information and basic instance state
+information from a post-processor. These information are stored in the `build`
+variable. Check out the [Contextual
+Variables](/packer/docs/templates/hcl_templates/contextual-variables) documentation to learn more
+about and see some examples of how to use them.
+
+### Related
+
+- The [`post-processors` block](/packer/docs/templates/hcl_templates/blocks/build/post-processors)
+ allows to define one or more chain of `post-processor`s that will take the
+ output from the build and provision steps.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx
new file mode 100644
index 0000000000..181ac03a18
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/post-processors.mdx
@@ -0,0 +1,85 @@
+---
+description: >
+ The post-processors block allows to define lists of post-processors to apply
+ to an artifact.
+page_title: post-processors - build - Blocks
+---
+
+# The `post-processors` block
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+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.
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ...
+ post-processors {
+ post-processor "shell-local" { # create an artifice.txt file containing "hello"
+ inline = [ "echo hello > artifice.txt" ]
+ }
+ post-processor "artifice" { # tell packer this is now the new artifact
+ files = ["artifice.txt"]
+ }
+ post-processor "checksum" { # checksum artifice.txt
+ checksum_types = [ "md5", "sha512" ] # checksum the artifact
+ keep_input_artifact = true # keep the artifact
+ }
+ }
+
+}
+```
+
+The [`post-processor` block](/packer/docs/templates/hcl_templates/blocks/build/post-processor)
+allows to define multiple post-processors that will run from the `Artifact` of
+each build. Read the `post-processor` documentation to know how to use a
+post-processor.
+
+### Difference between a `post-processor` and a `post-processors` block
+
+These two templates are doing the same thing:
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ... build image
+ post-processor "checksum" { # checksum image
+ checksum_types = [ "md5", "sha512" ] # checksum the artifact
+ }
+
+ post-processor "amazon-import" { # upload image to AWS
+ }
+
+ post-processor "googlecompute-import" { # upload image to GCP
+ }
+}
+```
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ... build image
+ post-processors {
+ post-processor "checksum" { # checksum image
+ checksum_types = [ "md5", "sha512" ] # checksum the artifact
+ }
+ }
+
+ post-processors {
+ post-processor "amazon-import" { # upload image to AWS
+ }
+ }
+
+ post-processors {
+ post-processor "googlecompute-import" { # upload image to GCP
+ }
+ }
+}
+```
+
+Each of these `post-processors` will start after each build -- that is, after
+each provision step has run on each source --. In all cases the source image is
+going to be deleted.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx
new file mode 100644
index 0000000000..fdf3648300
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/provisioner.mdx
@@ -0,0 +1,262 @@
+---
+description: |
+ The provisioner block defines how a provisioner is configured.
+page_title: provisioner - build - Blocks
+---
+
+# 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](/packer/docs/provisioners) section.
+
+## Run on Specific Sources
+
+You can use the `only` or `except` configurations to run a provisioner only
+with specific sources. These two configurations do what you expect: `only` will
+only run the provisioner on the specified sources and `except` will run the
+provisioner on anything other than the specified sources.
+
+An example of `only` being used is shown below, but the usage of `except` is
+effectively the same:
+
+```hcl
+# builds.pkr.hcl
+
+source "amazon-ebs" "first-example" {
+ #...
+}
+
+source "amazon-ebs" "second-example" {
+ #...
+}
+
+build {
+ sources = [
+ "source.amazon-ebs.first-example",
+ "source.amazon-ebs.second-example",
+ ]
+ provisioner "shell" {
+ # This provisioner only runs for the 'first-example' source.
+ only = ["amazon-ebs.first-example"]
+
+ inline = [
+ "echo provisioning all the things",
+ "echo the value of 'foo' is '${var.foo}'",
+ ]
+ }
+ provisioner "shell" {
+ # This runs with all sources.
+ inline = [
+ "echo Hi World!"
+ ]
+ }
+}
+```
+
+The source names within `only` and `except` must suppress `source.` prefix.
+
+The values within `only` or `except` are _source names_, not builder types nor build names.
+
+-> Note: In the cli `only` and `except` will match against **build names** (for
+example:`my_build.amazon-ebs.first-example`) but in a provisioner they will
+match on the **source name** (for example:`amazon-ebs.third-example`).
+
+## Build-Specific Overrides
+
+While the goal of Packer is to produce identical machine images, it sometimes
+requires periods of time where the machines are different before they
+eventually converge to be identical. In these cases, different configurations
+for provisioners may be necessary depending on the build. This can be done
+using build-specific overrides.
+
+An example of where this might be necessary is when building both an EC2 AMI
+and a VMware machine. The source EC2 AMI may setup a user with administrative
+privileges by default, whereas the VMware machine doesn't have these
+privileges. In this case, the shell script may need to be executed differently.
+Of course, the goal is that hopefully the shell script converges these two
+images to be identical. However, they may initially need to be run differently.
+
+This example is shown below:
+
+```hcl
+source "null" "example1" {
+ communicator = "none"
+}
+
+source "null" "example2" {
+ communicator = "none"
+}
+
+source "null" "example3" {
+ communicator = "none"
+}
+
+build {
+ sources = ["source.null.example2", "source.null.example3"]
+
+ source "source.null.example1" {
+ // Give a name to this source
+ name = "renamed"
+ }
+
+ provisioner "shell-local" {
+ inline = ["echo not overridden"]
+ override = {
+ example3 = {
+ inline = ["echo overrides for example3"]
+ }
+ // Refer to the source with the given name
+ renamed = {
+ inline = ["echo overrides for renamed"]
+ }
+ }
+ }
+}
+```
+
+As you can see, the `override` key is used. The value of this key is another
+HCL attribute map where the key is the name of a [source
+definition](/packer/docs/templates/hcl_templates/blocks/source). The value of this is in turn
+another HCL attribute map. This HCL attribute map simply contains the provisioner
+configuration as normal. This configuration is merged into the default
+provisioner configuration.
+
+## On Error Provisioner
+
+You can optionally create a single specialized provisioner called an
+`error-cleanup-provisioner`. This provisioner will not run unless the normal
+provisioning run fails. If the normal provisioning run does fail, this special
+error provisioner will run _before the instance is shut down_. This allows you
+to make last minute changes and clean up behaviors that Packer may not be able
+to clean up on its own.
+
+For examples, users may use this provisioner to make sure that the instance is
+properly unsubscribed from any services that it connected to during the build
+run.
+
+Toy usage example for the error cleanup script:
+
+```hcl
+source "null" "example" {
+ communicator = "none"
+}
+
+build {
+ sources = ["source.null.example"]
+
+ provisioner "shell-local" {
+ inline = ["exit 2"]
+ }
+
+ error-cleanup-provisioner "shell-local" {
+ inline = ["echo 'rubber ducky'> ducky.txt"]
+ }
+}
+```
+
+## Pausing Before Running
+
+With certain provisioners it is sometimes desirable to pause for some period of
+time before running it. Specifically, in cases where a provisioner reboots the
+machine, you may want to wait for some period of time before starting the next
+provisioner.
+
+Every provisioner definition in a Packer template can take a special
+configuration `pause_before` that is the amount of time to pause before running
+that provisioner. By default, there is no pause. An example is shown below:
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ...
+ provisioner "shell" {
+ inline = [
+ "echo provisioning all the things",
+ "echo the value of 'foo' is '${var.foo}'",
+ ]
+ pause_before = "10s"
+ }
+}
+```
+
+For the above provisioner, Packer will wait 10 seconds before uploading and
+executing the shell script.
+
+## Retry on error
+
+With certain provisioners it is sometimes desirable to retry when it fails.
+Specifically, in cases where the provisioner depends on external processes that are not done yet.
+
+Every provisioner definition in a Packer template can take a special
+configuration `max_retries` that is the maximum number of times a provisioner will retry on error.
+By default, there `max_retries` is zero and there is no retry on error. An example is shown below:
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ...
+ provisioner "shell" {
+ inline = [
+ "echo provisioning all the things",
+ "echo the value of 'foo' is '${var.foo}'",
+ ]
+ max_retries = 5
+ }
+}
+```
+
+For the above provisioner, Packer will retry maximum five times until stops failing.
+If after five retries the provisioner still fails, then the complete build will fail.
+
+## Timeout
+
+Sometimes a command can take much more time than expected
+
+Every provisioner definition in a Packer template can take a special
+configuration `timeout` that is the amount of time to wait before
+considering that the provisioner failed. By default, there is no timeout. An
+example is shown below:
+
+```hcl
+# builds.pkr.hcl
+build {
+ # ...
+ provisioner "shell" {
+ inline = [
+ "echo provisioning all the things",
+ "echo the value of 'foo' is '${var.foo}'",
+ ]
+ timeout = "5m"
+ }
+}
+```
+
+For the above provisioner, Packer will cancel the script if it takes more than
+5 minutes.
+
+Timeout has no effect in debug mode.
+
+## Build Contextual Variables
+
+Packer allows to access connection information and basic instance state information from a provisioner. These information are stored in the `build` variable.
+Check out the [Contextual Variables](/packer/docs/templates/hcl_templates/contextual-variables) documentation to learn more about and see some examples of how to use them.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/source.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/source.mdx
new file mode 100644
index 0000000000..07663f8e3b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/build/source.mdx
@@ -0,0 +1,56 @@
+---
+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
+---
+
+# The `source` block
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+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_.
+
+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
+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.
+
+```hcl
+# file: builds.pkr.hcl
+source "lxd" "arch" {
+ image = "archlinux"
+}
+
+build {
+ # Use the singular `source` block set specific fields.
+ # Note that fields cannot be overwritten, in other words, you cannot
+ # set the 'image' field from the top-level source block in here, as well as
+ # the 'name' and 'output_image' fields cannot be set in the top-level source block.
+ source "lxd.arch" {
+ # Setting the name field allows to rename the source only for this build section.
+ name = "nomad"
+ output_image = "nomad"
+ }
+
+ provisioner "shell" {
+ inline = [ "echo installing nomad" ]
+ }
+}
+
+build {
+ source "lxd.arch" {
+ name = "consul"
+ output_image = "consul"
+ }
+
+ provisioner "shell" {
+ inline = [ "echo installing consul" ]
+ }
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/data.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/data.mdx
new file mode 100644
index 0000000000..b5a8e0f890
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/data.mdx
@@ -0,0 +1,16 @@
+---
+description: >
+ The data block defines data sources within your Packer configuration.
+page_title: data - Blocks
+---
+
+# The `data` block
+
+The `data` block defines data sources within your Packer configuration.
+
+`@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.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/index.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/index.mdx
new file mode 100644
index 0000000000..9d2cb2fae7
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/index.mdx
@@ -0,0 +1,62 @@
+---
+page_title: Blocks - Configuration Language
+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 to configure builds. A block is a container for configuration.
+
+The most important blocks can be broken into a couple of major types:
+
+- `build` blocks contain configuration for a specific combination of builders,
+ provisioners, and post-processors used to create a specific image artifact.
+- `source` blocks contain configuration for builder plugins. Once defined,
+ sources can be used and further configured by the "build" block.
+- `provisioner` blocks contain configuration for provisioner plugins. These
+ blocks are nested inside of a build block.
+- `post-processor` and `post-processors` blocks contain configuration for
+ post-processor plugins and post-processor plugin sequences. They are also
+ nested within `build` blocks.
+- `variable` blocks contain configuration for variables that can either be
+ defaulted in configuration or set by the user at runtime.
+- `locals` blocks contain configuration for variables that can be created using
+ HCL functions or data sources, or composited from variables created in the
+ variables blocks.
+
+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
+Packer core
+
+Blocks can be defined in multiple files and `packer build folder` will build
+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:
+
+`@include 'from-1.5/variables/foo-block.mdx'`
+
+- [Variable block documentation](/packer/docs/templates/hcl_templates/blocks/variable).
+
+`@include 'from-1.5/locals/example-block.mdx'`
+
+- [Locals block documentation](/packer/docs/templates/hcl_templates/blocks/locals).
+
+`@include 'from-1.5/sources/example-block.mdx'`
+
+- [source block documentation](/packer/docs/templates/hcl_templates/blocks/source).
+
+`@include 'from-1.5/builds/example-block.mdx'`
+
+- [build block documentation](/packer/docs/templates/hcl_templates/blocks/build).
+
+`@include 'from-1.5/datasources/example-block.mdx'`
+
+- [data block documentation](/packer/docs/templates/hcl_templates/blocks/data).
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/locals.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/locals.mdx
new file mode 100644
index 0000000000..be45efb7e7
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/locals.mdx
@@ -0,0 +1,21 @@
+---
+description: >
+ The locals block also called the local-variable block defines locals within
+ your Packer configuration.
+page_title: locals - Blocks
+---
+
+# 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'`
+
+# More on variables
+
+- 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.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/packer.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/packer.mdx
new file mode 100644
index 0000000000..b3e590e93c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/packer.mdx
@@ -0,0 +1,121 @@
+---
+page_title: packer - Blocks
+description: |-
+ The "packer" configuration section is used to configure some behaviors
+ of Packer itself.
+---
+
+# Packer Settings
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+-> **Note:** The `packer` block is only available in Packer v1.6.5 and later.
+
+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.
+
+## Packer Block Syntax
+
+Packer settings are gathered together into `packer` blocks:
+
+```hcl
+packer {
+ # ...
+}
+```
+
+Each `packer` block can contain a number of settings related to Packer's
+behavior. Within a `packer` block, only constant values can be used;
+arguments may not refer to named objects such as resources, input variables,
+etc, and may not use any of the Packer language built-in functions.
+
+The various options supported within a `packer` block are described in the
+following sections.
+
+## Specifying a Required Packer Version
+
+The `required_version` setting accepts a [version constraint
+string,](#version-constraints) which specifies which versions of Packer
+can be used with your configuration.
+
+If the running version of Packer doesn't match the constraints specified,
+Packer will produce an error and exit without taking any further actions.
+
+Use Packer version constraints in a collaborative environment to
+ensure that everyone is using a specific Packer version, or using at least
+a minimum Packer version that has behavior expected by the configuration.
+
+## Specifying Plugin Requirements
+
+-> **Note:** The `required_plugins` block is only available in Packer v1.7.0 and
+later.
+
+The `required_plugins` block specifies all of the plugins required by the
+current config, mapping each local plugin name to a source address and a
+version constraint.
+
+```hcl
+packer {
+ required_plugins {
+ happycloud = {
+ version = ">= 2.7.0"
+ source = "github.com/hashicorp/happycloud"
+ }
+ }
+}
+```
+
+For more information, see [Plugins](/packer/docs/plugins).
+
+## Version Constraints
+
+Anywhere that Packer lets you specify a range of acceptable versions for
+something, it expects a specially formatted string known as a version
+constraint.
+
+### Version Constraint Syntax
+
+Packer's syntax for version constraints is very similar to the syntax used by
+other dependency management systems like Bundler and NPM.
+
+```hcl
+required_version = ">= 1.2.0, < 2.0.0"
+```
+
+A version constraint is a [string literal](/packer/docs/templates/hcl_templates/expressions#string-literals)
+containing one or more conditions, which are separated by commas.
+
+Each condition consists of an operator and a version number.
+
+Version numbers should be a series of numbers separated by periods (like
+`1.2.0`), optionally with a suffix to indicate a beta release.
+
+The following operators are valid:
+
+- `=` (or no operator): Allows only one exact version number. Cannot be combined
+ with other conditions.
+
+- `!=`: Excludes an exact version number.
+
+- `>`, `>=`, `<`, `<=`: Comparisons against a specified version, allowing
+ versions for which the comparison is true. "Greater-than" requests newer
+ versions, and "less-than" requests older versions.
+
+- `~>`: Allows the specified version, plus newer versions that only
+ increase the _most specific_ segment of the specified version number. For
+ example, `~> 0.9` is equivalent to `>= 0.9, < 1.0`, and `~> 0.8.4`, is
+ equivalent to `>= 0.8.4, < 0.9`. This is usually called the pessimistic
+ constraint operator.
+
+### Version Constraint Behavior
+
+A version number that meets every applicable constraint is considered acceptable.
+
+Packer consults version constraints to determine whether it has acceptable
+versions of itself.
+
+A prerelease version is a version number that contains a suffix introduced by
+a dash, like `1.2.0-beta`. A prerelease version can be selected only by an
+_exact_ version constraint (the `=` operator or no operator). Prerelease
+versions do not match inexact operators such as `>=`, `~>`, etc.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/source.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/source.mdx
new file mode 100644
index 0000000000..d4b1070809
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/source.mdx
@@ -0,0 +1,61 @@
+---
+description: |
+ The top-level source block defines reusable builder configuration blocks
+page_title: source - Blocks
+---
+
+# The `source` block
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+The top-level `source` block defines reusable builder configuration blocks:
+
+`@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.
+
+You can start builders by referring to those source blocks from a [`build`
+block](/packer/docs/templates/hcl_templates/blocks/build) :
+
+```hcl
+build {
+ sources = [
+ # Here Packer will use a default ami_name when saving the image.
+ "source.happycloud.example",
+ "source.happycloud.foo",
+ ]
+}
+```
+
+The build-level [`source`
+block](/packer/docs/templates/hcl_templates/blocks/build/source) allows to set specific
+source fields. Each field must be defined only once and it is currently not
+allowed to override a value.
+
+```hcl
+build {
+ source "source.happycloud.example" {
+ # Here Packer will use the provided image_name instead of defaulting it.
+ # Note that fields cannot be overwritten, in other words, you cannot
+ # set the 'image_name' field in the top-level source block and here at the
+ # same time
+ image_name = "build_specific_field"
+ }
+}
+```
+
+`@include 'from-1.5/contextual-source-variables.mdx'`
+
+## Related
+
+- The list of available builders can be found in the [builders](/packer/docs/builders)
+ section.
+
+- A list of [community
+ builders](https://packer.io/community-tools#community-builders) is available.
+
+- Create your own [custom builder](/packer/docs/plugins/creation/custom-builders) !
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/variable.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/variable.mdx
new file mode 100644
index 0000000000..38b21aae6d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/blocks/variable.mdx
@@ -0,0 +1,39 @@
+---
+description: >
+ The variable block, also called the input-variable block, defines variables
+ within your Packer configuration.
+page_title: variable - Blocks
+---
+
+# 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](/packer/docs/templates/hcl_templates/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'`
+
+`@include 'from-1.5/variables/custom-validation.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'`
+
+`@include 'from-1.5/variables/sensitive.mdx'`
+
+# More on variables
+
+- Read the [full variables](/packer/docs/templates/hcl_templates/variables) description for a more
+ thorough read.
+- Read the [variables guide](/packer/guides/hcl/variables) for more examples.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/contextual-variables.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/contextual-variables.mdx
new file mode 100644
index 0000000000..03c04d82c8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/contextual-variables.mdx
@@ -0,0 +1,235 @@
+---
+page_title: Contextual Variables - HCL Configuration Language
+description: >-
+ Special variables provide connection information and basic instance state
+ information.
+
+ This page covers all existing special variables.
+---
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+`@include 'from-1.5/contextual-source-variables.mdx'`
+
+# 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:
+
+```hcl
+source "null" "first-example" {
+ communicator = "none"
+}
+
+build {
+ name = "my-build-name"
+ sources = ["null.first-example"]
+
+ provisioner "shell-local" {
+ environment_vars = ["TESTVAR=${build.PackerRunUUID}"]
+ inline = ["echo source.name is ${source.name}.",
+ "echo build.name is ${build.name}.",
+ "echo build.PackerRunUUID is $TESTVAR"]
+ }
+}
+```
+
+Here is the list of available build variables:
+
+- **name** Represents the name of the build block being run. This is different
+ than the name of the source block being run.
+
+- **ID**: Represents the VM being provisioned. For example, in Amazon it is the instance ID; in DigitalOcean,
+ it is the Droplet ID; in VMware, it is the VM name.
+
+- **Host**, **Port**, **User** and **Password**: The host, port, user, and password that Packer uses to access the machine.
+ Useful for using the shell local provisioner to run Ansible or Inspec against the provisioned instance.
+
+- **ConnType**: Type of communicator being used. For example, for SSH communicator this will be "ssh".
+
+- **PackerRunUUID**: Current build's unique ID. Can be used to specify build artifacts.
+ An example of that, is when multiple builds runs at the same time producing the same artifact.
+ It's possible to differentiate these artifacts by naming them with the builds' unique IDs.
+
+- **PackerHTTPIP**, **PackerHTTPPort**, and **PackerHTTPAddr**: HTTP IP, port, and address of the file server Packer creates to serve items in the "http" dir to the VM. The HTTP address is displayed in the format `IP:PORT`.
+
+- **SSHPublicKey** and **SSHPrivateKey**: The public and private key that Packer uses to connect to the instance.
+ These are unique to the SSH communicator and are unset when using other communicators.
+ **SSHPublicKey** and **SSHPrivateKey** can have escape sequences and special characters so their output should be single quoted to avoid surprises. For example:
+
+ ```hcl
+ provisioner "shell" {
+ inline = ["echo '${build.SSHPrivateKey}' > /tmp/packer-session.pem"]
+ }
+ ```
+
+For backwards compatibility, `WinRMPassword` is also available through this
+engine, though it is no different than using the more general `Password`.
+
+All build variables are valid to use with any of the [HCL2 functions](/packer/docs/templates/hcl_templates/functions).
+Example of using [upper](/packer/docs/templates/hcl_templates/functions/string/upper) to upper case the build ID:
+
+```hcl
+ post-processor "shell-local" {
+ inline = ["echo ${upper(build.ID)}"]
+ }
+```
+
+For builder-specific builder variables, please also refer to the builder docs:
+
+- Amazon EC2: [chroot](/packer/plugins/builders/amazon/chroot#build-shared-information-variables),
+ [EBS Volume](/packer/plugins/builders/amazon/ebsvolume#build-shared-information-variables),
+ [EBS](/packer/plugins/builders/amazon/ebs#build-shared-information-variables),
+ [EBS Surrogate](/packer/plugins/builders/amazon/ebssurrogate#build-shared-information-variables),
+ [Instance](/packer/plugins/builders/amazon/instance#build-shared-information-variables).
+
+The HCL2 Special Build Variables is in beta; please report any issues or requests on the Packer
+issue tracker on GitHub.
+
+# Packer Version
+
+This variable is set to the Packer version currently running.
+
+```hcl
+source "null" "first-example" {
+ communicator = "none"
+}
+
+build {
+ sources = ["null.first-example"]
+
+ provisioner "shell-local" {
+ inline = ["echo packer_version is '${packer.version}'"]
+ }
+}
+```
+
+If you are running a development version of Packer, the version variable will
+contain the released version number, dev flag, and current commit.
+
+```shell-session
+PACKER_LOG=0 packer build packer_version_demo.pkr.hcl
+null.first-example: output will be in this color.
+
+==> null.first-example: Running local shell script: /var/folders/8t/0yb5q0_x6mb2jldqq_vjn3lr0000gn/T/packer-shell083160352
+ null.first-example: packer_version is 1.6.5-dev (a69392129+CHANGES)
+```
+
+If you are running a released version of Packer, the version variable will
+contain the released version number only:
+
+```shell-session
+PACKER_LOG=0 packer build packer_version_demo.pkr.hcl
+null.first-example: output will be in this color.
+
+==> null.first-example: Running local shell script: /var/folders/8t/0yb5q0_x6mb2jldqq_vjn3lr0000gn/T/packer-shell718995312
+ null.first-example: packer_version is 1.6.5
+```
+
+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
+
+~> **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.
+
+If your build is pushing metadata to the HCP Packer registry, this variable is
+set to the value of the Iteration ID associated with this run.
+
+```hcl
+source "null" "example" {
+ communicator = "none"
+}
+
+data "hcp-packer-version" "hardened-source" {
+ bucket_name = "example"
+ channel_name = "latest"
+}
+
+data "hcp-packer-artifact" "file" {
+ bucket_name = "example"
+ version_fingerprint = "${data.hcp-packer-version.hardened-source.fingerprint}"
+ platform = "aws"
+ region = "us-east-1"
+}
+
+build {
+ hcp_packer_registry {
+ bucket_name = "simple"
+ }
+ sources = [
+ "source.null.example"
+ ]
+
+ provisioner "shell-local" {
+ inline = [
+ "echo data is ${packer.iterationID}"
+ ]
+ }
+}
+
+```
+
+```shell-session
+==> mybuild.null.example: Running local shell script: /var/folders/cz/q3cr3tld2457gtlgw7qs1kqc0000gq/T/packer-shell842419427
+ mybuild.null.example: data is 01HN3KCRPVKR5PBQ28TS6B12W0
+```
+
+# 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.
+
+```hcl
+source "null" "example" {
+ communicator = "none"
+}
+
+data "hcp-packer-version" "hardened-source" {
+ bucket_name = "example"
+ channel_name = "latest"
+}
+
+data "hcp-packer-artifact" "file" {
+ bucket_name = "example"
+ version_fingerprint = "${data.hcp-packer-version.hardened-source.fingerprint}"
+ platform = "aws"
+ region = "us-east-1"
+}
+
+build {
+ hcp_packer_registry {
+ bucket_name = "simple"
+ }
+ sources = [
+ "source.null.example"
+ ]
+
+ provisioner "shell-local" {
+ inline = [
+ "echo data is ${packer.versionFingerprint}"
+ ]
+ }
+}
+
+```
+
+```shell-session
+==> mybuild.null.example: Running local shell script: /var/folders/cz/q3cr3tld2457gtlgw7qs1kqc0000gq/T/packer-shell842419427
+ mybuild.null.example: data is 01HN3KCRPVKR5PBQ28TS6B12W0
+```
+
+You can also add this value to post-processors, for example to add to a manifest file:
+
+```hcl
+ post-processor "manifest" {
+ output = "manifest.json"
+ strip_path = true
+ custom_data = {
+ version_fingerprint = "${packer.versionFingerprint}"
+ iteration = "${packer.iterationID}"
+ }
+ }
+
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/datasources.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/datasources.mdx
new file mode 100644
index 0000000000..d596c61fc0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/datasources.mdx
@@ -0,0 +1,86 @@
+---
+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.
+---
+
+# Data Sources
+
+-> **Note:** Data Sources is a feature included in Packer 1.7 and later.
+
+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
+
+A data source is declared using a data block, and the configuration looks like the following:
+
+```hcl
+data "amazon-ami" "example" {
+ filters = {
+ virtualization-type = "hvm"
+ name = "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*"
+ root-device-type = "ebs"
+ }
+ owners = ["099720109477"]
+ most_recent = true
+}
+```
+
+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.
+
+Within the block (the `{ }`) is the configuration for the data instance. The configuration is dependent on the data source type,
+and is documented for each data source. For example the configuration of the `amazon-ami` data source can be found at [plugins/datasources/amazon/ami](/packer/plugins/datasources/amazon/ami#configuration-reference).
+
+A data source can output one or more attributes, which can be used by adding their key name to the data source unique
+identifier, like `data...`.
+
+The output from the `amazon-ami.example` above can be accessed as follows:
+
+Output data:
+
+```
+"data.amazon-ami.example" {
+ id = "ami12345"
+ name = "MyAMI"
+ creation_date = "01/01/2021"
+ owner = "123456789"
+ owner_name = "Some Name"
+ tags = {"tag1": "value"}
+}
+```
+
+Usage:
+
+```hcl
+// in a local
+locals {
+ source_ami_id = data.amazon-ami.example.id
+ source_ami_name = data.amazon-ami.example.name
+ }
+```
+
+```hcl
+// in a source
+source "amazon-ebs" "basic-example" {
+ source_ami = locals.source_ami
+ // ...
+}
+```
+
+## Known Limitations
+`@include 'datasources/local-dependency-limitation.mdx'`
+
+
+## Related
+
+- The list of available data sources can be found in the [data sources](/packer/docs/datasources)
+ section.
+- Create your own [custom data source](/packer/docs/plugins/creation/custom-datasources) !
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/expressions.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/expressions.mdx
new file mode 100644
index 0000000000..4fb50126c0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/expressions.mdx
@@ -0,0 +1,431 @@
+---
+page_title: Expressions - Configuration Language
+description: |-
+ HCL allows the use of expressions to access data exported
+ by sources and to transform and combine that data to produce other values.
+---
+
+# Expressions
+
+`@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
+HCL also allows more complex expressions such as references to data exported by
+sources, arithmetic, conditional evaluation, and a number of built-in
+functions.
+
+Expressions can be used in a number of places in HCL, but some contexts limit
+which expression constructs are allowed, such as requiring a literal value of a
+particular type or forbidding. Each language feature's documentation describes
+any restrictions it places on expressions.
+
+The rest of this page describes all of the features of Packer's
+expression syntax.
+
+## Types and Values
+
+The result of an expression is a _value_. All values have a _type_, which
+dictates where that value can be used and what transformations can be
+applied to it.
+
+HCL uses the following types for its values:
+
+- `string`: a sequence of Unicode characters representing some text, like
+ `"hello"`.
+- `number`: a numeric value. The `number` type can represent both whole
+ numbers like `15` and fractional values like `6.283185`.
+- `bool`: either `true` or `false`. `bool` values can be used in conditional
+ logic.
+- `list` (or `tuple`): a sequence of values, like
+ `["us-west-1a", "us-west-1c"]`. Elements in a list or tuple are identified by
+ consecutive whole numbers, starting with zero.
+- `map` (or `object`): a group of values identified by named labels, like
+ `{name = "Mabel", age = 52}`.
+
+Strings, numbers, and bools are sometimes called _primitive types._
+Lists/tuples and maps/objects are sometimes called _complex types,_ _structural
+types,_ or _collection types._
+
+Finally, there is one special value that has _no_ type:
+
+- `null`: a value that represents _absence_ or _omission._ If you set an
+ argument of a source or module to `null`, Packer behaves as though you
+ had completely omitted it — it will use the argument's default value if it has
+ one, or raise an error if the argument is mandatory. `null` is most useful in
+ conditional expressions, so you can dynamically omit an argument if a
+ condition isn't met.
+
+### Advanced Type Details
+
+In most situations, lists and tuples behave identically, as do maps and objects.
+Whenever the distinction isn't relevant, the Packer documentation uses each
+pair of terms interchangeably (with a historical preference for "list" and
+"map").
+
+However, plugin authors should understand the differences between these similar
+types (and the related `set` type), since they offer different ways to restrict
+the allowed values for input variables and source arguments.
+
+### Type Conversion
+
+Expressions are most often used to set values for arguments. In these cases,
+the argument has an expected type and the given expression must produce a value
+of that type.
+
+Where possible, Packer automatically converts values from one type to
+another in order to produce the expected type. If this isn't possible, Packer
+will produce a type mismatch error and you must update the configuration with a
+more suitable expression.
+
+Packer automatically converts number and bool values to strings when needed.
+It also converts strings to numbers or bools, as long as the string contains a
+valid representation of a number or bool value.
+
+- `true` converts to `"true"`, and vice-versa
+- `false` converts to `"false"`, and vice-versa
+- `15` converts to `"15"`, and vice-versa
+
+## Literal Expressions
+
+A _literal expression_ is an expression that directly represents a particular
+constant value. Packer has a literal expression syntax for each of the value
+types described above:
+
+- Strings are usually represented by a double-quoted sequence of Unicode
+ characters, `"like this"`. There is also a "heredoc" syntax for more complex
+ strings. String literals are the most complex kind of literal expression in
+ Packer, and have additional documentation on this page:
+ - See [String Literals](#string-literals) below for information about escape
+ sequences and the heredoc syntax.
+ - See [String Templates](#string-templates) below for information about
+ interpolation and template directives.
+- Numbers are represented by unquoted sequences of digits with or without a
+ decimal point, like `15` or `6.283185`.
+- Bools are represented by the unquoted symbols `true` and `false`.
+- The null value is represented by the unquoted symbol `null`.
+- Lists/tuples are represented by a pair of square brackets containing a
+ comma-separated sequence of values, like `["a", 15, true]`.
+
+ List literals can be split into multiple lines for readability, but always
+ require a comma between values. A comma after the final value is allowed,
+ but not required. Values in a list can be arbitrary expressions.
+
+- Maps/objects are represented by a pair of curly braces containing a series of
+ ` = ` pairs:
+
+ ```hcl
+ {
+ name = "John"
+ age = 52
+ }
+ ```
+
+ Key/value pairs can be separated by either a comma or a line break. Values
+ can be arbitrary expressions. Keys are strings; they can be left unquoted if
+ they are a valid [identifier](/packer/docs/templates/hcl_templates/syntax#identifiers), but must be quoted
+ otherwise. You can use a non-literal expression as a key by wrapping it in
+ parentheses, like `(var.business_unit_tag_name) = "SRE"`.
+
+## References to Named Values
+
+Packer makes one named values available.
+
+The following named values are available:
+
+- `source..` is an object representing a
+ [source](/packer/docs/templates/hcl_templates/blocks/source) of the given type
+ and name.
+
+### Available Functions
+
+For a full list of available functions, see [the function
+reference](/packer/docs/templates/hcl_templates/functions).
+
+## `for` Expressions
+
+A _`for` expression_ creates a complex type value by transforming
+another complex type value. Each element in the input value
+can correspond to either one or zero values in the result, and an arbitrary
+expression can be used to transform each input element into an output element.
+
+For example, if `var.list` is a list of strings, then the following expression
+produces a list of strings with all-uppercase letters:
+
+```hcl
+[for s in var.list : upper(s)]
+```
+
+This `for` expression iterates over each element of `var.list`, and then
+evaluates the expression `upper(s)` with `s` set to each respective element.
+It then builds a new tuple value with all of the results of executing that
+expression in the same order.
+
+The type of brackets around the `for` expression decide what type of result
+it produces. The above example uses `[` and `]`, which produces a tuple. If
+`{` and `}` are used instead, the result is an object, and two result
+expressions must be provided separated by the `=>` symbol:
+
+```hcl
+{for s in var.list : s => upper(s)}
+```
+
+This expression produces an object whose attributes are the original elements
+from `var.list` and their corresponding values are the uppercase versions.
+
+A `for` expression can also include an optional `if` clause to filter elements
+from the source collection, which can produce a value with fewer elements than
+the source:
+
+```text
+[for s in var.list : upper(s) if s != ""]
+```
+
+The source value can also be an object or map value, in which case two
+temporary variable names can be provided to access the keys and values
+respectively:
+
+```text
+[for k, v in var.map : length(k) + length(v)]
+```
+
+Finally, if the result type is an object (using `{` and `}` delimiters) then
+the value result expression can be followed by the `...` symbol to group
+together results that have a common key:
+
+```text
+{for s in var.list : substr(s, 0, 1) => s... if s != ""}
+```
+
+## Splat Expressions
+
+A _splat expression_ provides a more concise way to express a common operation
+that could otherwise be performed with a `for` expression.
+
+If `var.list` is a list of objects that all have an attribute `id`, then a list
+of the IDs could be produced with the following `for` expression:
+
+```hcl
+[for o in var.list : o.id]
+```
+
+This is equivalent to the following _splat expression:_
+
+```hcl
+var.list[*].id
+```
+
+The special `[*]` symbol iterates over all of the elements of the list given to
+its left and accesses from each one the attribute name given on its right. A
+splat expression can also be used to access attributes and indexes from lists
+of complex types by extending the sequence of operations to the right of the
+symbol:
+
+```hcl
+var.list[*].interfaces[0].name
+```
+
+The above expression is equivalent to the following `for` expression:
+
+```hcl
+[for o in var.list : o.interfaces[0].name]
+```
+
+Splat expressions are for lists only (and thus cannot be used [to reference
+resources created with
+`for_each`](/terraform/docs/configuration/resources#referring-to-instances), which
+are represented as maps). However, if a splat expression is applied to a value
+that is _not_ a list or tuple then the value is automatically wrapped in a
+single-element list before processing.
+
+For example, `var.single_object[*].id` is equivalent to
+`[var.single_object][*].id`, or effectively `[var.single_object.id]`. This
+behavior is not interesting in most cases, but it is particularly useful when
+referring to resources that may or may not have `count` set, and thus may or
+may not produce a tuple value:
+
+```hcl
+aws_instance.example[*].id
+```
+
+The above will produce a list of IDs whether `aws_instance.example` has `count`
+set or not, avoiding the need to revise various other expressions in the
+configuration when a particular resource switches to and from having `count`
+set.
+
+## `dynamic` blocks
+
+Within top-level block constructs like [source](/packer/docs/templates/hcl_templates/blocks/source), expressions
+can usually be used only when assigning a value to an argument using the `name = expression` or `key = expression` form.
+This covers many uses, but some source types include repeatable _nested blocks_ in their arguments, which do not accept expressions:
+
+```hcl
+source "amazon-ebs" "example" {
+ name = "pkr-test-name" # can use expressions here
+
+ tag {
+ # but the "tag" block is always a literal block
+ }
+}
+```
+
+You can dynamically construct repeatable nested blocks like `tag` using a
+special `dynamic` block type, which is supported in top-level block constructs, example:
+
+```hcl
+locals {
+ standard_tags = {
+ Component = "user-service"
+ Environment = "production"
+ }
+}
+
+source "amazon-ebs" "example" {
+ # ...
+
+ tag {
+ key = "Name"
+ value = "example-asg-name"
+ }
+
+ dynamic "tag" {
+ for_each = local.standard_tags
+
+ content {
+ key = tag.key
+ value = tag.value
+ }
+ }
+}
+```
+
+A `dynamic` block acts much like a `for` expression, but produces nested blocks
+instead of a complex typed value. It iterates over a given complex value, and
+generates a nested block for each element of that complex value.
+
+- The label of the dynamic block (`"tag"` in the example above) specifies
+ what kind of nested block to generate.
+- The `for_each` argument provides the complex value to iterate over.
+- The `iterator` argument (optional) sets the name of a temporary variable
+ that represents the current element of the complex value. If omitted, the name
+ of the variable defaults to the label of the `dynamic` block (`"tag"` in
+ the example above).
+- The `labels` argument (optional) is a list of strings that specifies the block
+ labels, in order, to use for each generated block. You can use the temporary
+ iterator variable in this value.
+- The nested `content` block defines the body of each generated block. You can
+ use the temporary iterator variable inside this block.
+
+Since the `for_each` argument accepts any collection or structural value,
+you can use a `for` expression or splat expression to transform an existing
+collection.
+
+The iterator object (`tag` in the example above) has two attributes:
+
+- `key` is the map key or list element index for the current element. If the
+ `for_each` expression produces a _set_ value then `key` is identical to
+ `value` and should not be used.
+- `value` is the value of the current element.
+
+A `dynamic` block can only generate arguments for nested blocks that belong to
+the source type, data source, or provisioner being configured.
+
+The `for_each` value must be a map or set with one element per desired nested
+block. If you need to declare resource instances based on a nested data
+structure or combinations of elements from multiple data structures you can use
+expressions and functions to derive a suitable value. For some common examples
+of such situations, see the
+[`flatten`](/packer/docs/templates/hcl_templates/functions/collection/flatten) and
+[`setproduct`](/packer/docs/templates/hcl_templates/functions/collection/setproduct)
+functions.
+
+### Best Practices for `dynamic` Blocks
+
+Overuse of `dynamic` blocks can make configuration hard to read and maintain,
+so we recommend using them only when you need to hide details in order to build
+a clean user interface for a re-usable code. Always write nested blocks out
+literally where possible.
+
+## String Literals
+
+HCL has two different syntaxes for string literals. The
+most common is to delimit the string with quote characters (`"`), like
+`"hello"`. In quoted strings, the backslash character serves as an escape
+sequence, with the following characters selecting the escape behavior:
+
+| Sequence | Replacement |
+| ------------ | ----------------------------------------------------------------------------- |
+| `\n` | Newline |
+| `\r` | Carriage Return |
+| `\t` | Tab |
+| `\"` | Literal quote (without terminating the string) |
+| `\\` | Literal backslash |
+| `\uNNNN` | Unicode character from the basic multilingual plane (NNNN is four hex digits) |
+| `\UNNNNNNNN` | Unicode character from supplementary planes (NNNNNNNN is eight hex digits) |
+
+The alternative syntax for string literals is the so-called Here Documents or
+"heredoc" style, inspired by Unix shell languages. This style allows multi-line
+strings to be expressed more clearly by using a custom delimiter word on a line
+of its own to close the string:
+
+```hcl
+< chunklist(["a", "b", "c", "d", "e"], 2)
+[
+ ["a", "b"],
+ ["c", "d"],
+ ["e"]
+]
+> chunklist(["a", "b", "c", "d", "e"], 1)
+[
+ ["a"],
+ ["b"],
+ ["c"],
+ ["d"],
+ ["e"]
+]
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/coalesce.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/coalesce.mdx
new file mode 100644
index 0000000000..f46673c49d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/coalesce.mdx
@@ -0,0 +1,35 @@
+---
+page_title: coalesce - Functions - Configuration Language
+description: |-
+ The coalesce function takes any number of arguments and returns the
+ first one that isn't null nor empty.
+---
+
+# `coalesce` Function
+
+`coalesce` takes any number of arguments and returns the first one
+that isn't null or an empty string.
+
+## Examples
+
+```shell-session
+> coalesce("a", "b")
+a
+> coalesce("", "b")
+b
+> coalesce(1,2)
+1
+```
+
+To perform the `coalesce` operation with a list of strings, use the `...`
+symbol to expand the list as arguments:
+
+```shell-session
+> coalesce(["", "b"]...)
+b
+```
+
+## Related Functions
+
+- [`coalescelist`](/packer/docs/templates/hcl_templates/functions/collection/coalescelist) performs a similar operation with
+ list arguments rather than individual arguments.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/coalescelist.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/coalescelist.mdx
new file mode 100644
index 0000000000..79d9d85c8d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/coalescelist.mdx
@@ -0,0 +1,42 @@
+---
+page_title: coalescelist - Functions - Configuration Language
+description: |-
+ The coalescelist function takes any number of list arguments and returns the
+ first one that isn't empty.
+---
+
+# `coalescelist` Function
+
+`coalescelist` takes any number of list arguments and returns the first one
+that isn't empty.
+
+## Examples
+
+```shell-session
+> coalescelist(["a", "b"], ["c", "d"])
+[
+ "a",
+ "b",
+]
+> coalescelist([], ["c", "d"])
+[
+ "c",
+ "d",
+]
+```
+
+To perform the `coalescelist` operation with a list of lists, use the `...`
+symbol to expand the outer list as arguments:
+
+```shell-session
+> coalescelist([[], ["c", "d"]]...)
+[
+ "c",
+ "d",
+]
+```
+
+## Related Functions
+
+- [`coalesce`](/packer/docs/templates/hcl_templates/functions/collection/coalesce) performs a similar operation with string
+ arguments rather than list arguments.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/compact.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/compact.mdx
new file mode 100644
index 0000000000..df8b79e752
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/compact.mdx
@@ -0,0 +1,20 @@
+---
+page_title: compact - Functions - Configuration Language
+description: The compact function removes empty string elements from a list.
+---
+
+# `compact` Function
+
+`compact` takes a list of strings and returns a new list with any empty string
+elements removed.
+
+## Examples
+
+```shell-session
+> compact(["a", "", "b", "c"])
+[
+ "a",
+ "b",
+ "c",
+]
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/concat.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/concat.mdx
new file mode 100644
index 0000000000..318b72fa0b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/concat.mdx
@@ -0,0 +1,20 @@
+---
+page_title: concat - Functions - Configuration Language
+description: The concat function combines two or more lists into a single list.
+---
+
+# `concat` Function
+
+`concat` takes two or more lists and combines them into a single list.
+
+## Examples
+
+```shell-session
+> concat(["a", ""], ["b", "c"])
+[
+ "a",
+ "",
+ "b",
+ "c",
+]
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/contains.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/contains.mdx
new file mode 100644
index 0000000000..43cdd5c5da
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/contains.mdx
@@ -0,0 +1,22 @@
+---
+page_title: contains - Functions - Configuration Language
+description: The contains function determines whether a list or set contains a given value.
+---
+
+# `contains` Function
+
+`contains` determines whether a given list or set contains a given single value
+as one of its elements.
+
+```hcl
+contains(list, value)
+```
+
+## Examples
+
+```shell-session
+> contains(["a", "b", "c"], "a")
+true
+> contains(["a", "b", "c"], "d")
+false
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/distinct.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/distinct.mdx
new file mode 100644
index 0000000000..28fe7a4489
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/distinct.mdx
@@ -0,0 +1,24 @@
+---
+page_title: distinct - Functions - Configuration Language
+description: The distinct function removes duplicate elements from a list.
+---
+
+# `distinct` Function
+
+`distinct` takes a list and returns a new list with any duplicate elements
+removed.
+
+The first occurrence of each value is retained and the relative ordering of
+these elements is preserved.
+
+## Examples
+
+```shell-session
+> distinct(["a", "b", "a", "c", "d", "b"])
+[
+ "a",
+ "b",
+ "c",
+ "d",
+]
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/element.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/element.mdx
new file mode 100644
index 0000000000..6373cc3940
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/element.mdx
@@ -0,0 +1,38 @@
+---
+page_title: element - Functions - Configuration Language
+description: The element function retrieves a single element from a list.
+---
+
+# `element` Function
+
+`element` retrieves a single element from a list.
+
+```hcl
+element(list, index)
+```
+
+The index is zero-based. This function produces an error if used with an
+empty list.
+
+Use the built-in index syntax `list[index]` in most cases. Use this function
+only for the special additional "wrap-around" behavior described below.
+
+## Examples
+
+```shell-session
+> element(["a", "b", "c"], 1)
+b
+```
+
+If the given index is greater than the length of the list then the index is
+"wrapped around" by taking the index modulo the length of the list:
+
+```shell-session
+> element(["a", "b", "c"], 3)
+a
+```
+
+## Related Functions
+
+- [`index`](/packer/docs/templates/hcl_templates/functions/collection/index-fn) finds the index for a particular element value.
+- [`lookup`](/packer/docs/templates/hcl_templates/functions/collection/lookup) retrieves a value from a _map_ given its _key_.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/flatten.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/flatten.mdx
new file mode 100644
index 0000000000..a3bc2f4423
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/flatten.mdx
@@ -0,0 +1,108 @@
+---
+page_title: flatten - Functions - Configuration Language
+description: The flatten function eliminates nested lists from a list.
+---
+
+# `flatten` Function
+
+`flatten` takes a list and replaces any elements that are lists with a
+flattened sequence of the list contents.
+
+## Examples
+
+```shell-session
+> flatten([["a", "b"], [], ["c"]])
+["a", "b", "c"]
+```
+
+If any of the nested lists also contain directly-nested lists, these too are
+flattened recursively:
+
+```shell-session
+> flatten([[["a", "b"], []], ["c"]])
+["a", "b", "c"]
+```
+
+Indirectly-nested lists, such as those in maps, are _not_ flattened.
+
+## Flattening nested structures for `for_each`
+
+The
+[resource `for_each`](/terraform/docs/configuration/resources#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
+and
+[`dynamic` block](/packer/docs/templates/hcl_templates/expressions#dynamic-blocks)
+language features both require a collection value that has one element for
+each repetition.
+
+Sometimes your input data structure isn't naturally in a suitable shape for
+use in a `for_each` argument, and `flatten` can be a useful helper function
+when reducing a nested data structure into a flat one.
+
+For example, consider a folder that declares a variable like the following:
+
+```hcl
+variable "networks" {
+ type = map(object({
+ cidr_block = string
+ subnets = map(object({
+ cidr_block = string
+ })
+ })
+}
+```
+
+The above is a reasonable way to model objects that naturally form a tree,
+such as top-level networks and their subnets. The repetition for the top-level
+networks can use this variable directly, because it's already in a form
+where the resulting instances match one-to-one with map elements:
+
+```hcl
+resource "aws_vpc" "example" {
+ for_each = var.networks
+
+ cidr_block = each.value.cidr_block
+}
+```
+
+However, in order to declare all of the _subnets_ with a single `resource`
+block, we must first flatten the structure to produce a collection where each
+top-level element represents a single subnet:
+
+```hcl
+locals {
+ # flatten ensures that this local value is a flat list of objects, rather
+ # than a list of lists of objects.
+ network_subnets = flatten([
+ for network_key, network in var.networks : [
+ for subnet_key, subnet in network.subnets : {
+ network_key = network_key
+ subnet_key = subnet_key
+ network_id = aws_vpc.example[network_key].id
+ cidr_block = subnet.cidr_block
+ }
+ ]
+ ])
+}
+
+resource "aws_subnet" "example" {
+ # local.network_subnets is a list, so we must now project it into a map
+ # where each key is unique. We'll combine the network and subnet keys to
+ # produce a single unique key per instance.
+ for_each = {
+ for subnet in local.network_subnets : "${subnet.network_key}.${subnet.subnet_key}" => subnet
+ }
+
+ vpc_id = each.value.network_id
+ availability_zone = each.value.subnet_key
+ cidr_block = each.value_cidr_block
+}
+```
+
+The above results in one subnet instance per subnet object, while retaining
+the associations between the subnets and their containing networks.
+
+## Related Functions
+
+- [`setproduct`](/packer/docs/templates/hcl_templates/functions/collection/setproduct) finds all of the combinations of multiple
+ lists or sets of values, which can also be useful when preparing collections
+ for use with `for_each` constructs.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/index-fn.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/index-fn.mdx
new file mode 100644
index 0000000000..80c80ca056
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/index-fn.mdx
@@ -0,0 +1,27 @@
+---
+page_title: index - Functions - Configuration Language
+description: The index function finds the element index for a given value in a list.
+---
+
+# `index` Function
+
+`index` finds the element index for a given value in a list.
+
+```hcl
+index(list, value)
+```
+
+The returned index is zero-based. This function produces an error if the given
+value is not present in the list.
+
+## Examples
+
+```shell-session
+> index(["a", "b", "c"], "b")
+1
+```
+
+## Related Functions
+
+- [`element`](/packer/docs/templates/hcl_templates/functions/collection/element) retrieves a particular element from a list given
+ its index.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/keys.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/keys.mdx
new file mode 100644
index 0000000000..cd955f9dfb
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/keys.mdx
@@ -0,0 +1,26 @@
+---
+page_title: keys - Functions - Configuration Language
+description: The keys function returns a list of the keys in a given map.
+---
+
+# `keys` Function
+
+`keys` takes a map and returns a list containing the keys from that map.
+
+The keys are returned in lexicographical order, ensuring that the result will
+be identical as long as the keys in the map don't change.
+
+## Examples
+
+```shell-session
+> keys({a=1, c=2, d=3})
+[
+ "a",
+ "c",
+ "d",
+]
+```
+
+## Related Functions
+
+- [`values`](/packer/docs/templates/hcl_templates/functions/collection/values) returns a list of the _values_ from a map.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/length.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/length.mdx
new file mode 100644
index 0000000000..71eacc8dc3
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/length.mdx
@@ -0,0 +1,39 @@
+---
+page_title: length - Functions - Configuration Language
+description: The length function determines the length of a collection or string.
+---
+
+# `length` Function
+
+`length` determines the length of a given list, map, or string.
+
+If given a list or map, the result is the number of elements in that collection.
+If given a string, the result is the number of characters in the string.
+
+## Examples
+
+```shell-session
+> length([])
+0
+> length(["a", "b"])
+2
+> length({"a" = "b"})
+1
+> length("hello")
+5
+```
+
+When given a string, the result is the number of characters, rather than the
+number of bytes or Unicode sequences that form them:
+
+```shell-session
+> length("👾🕹️")
+2
+```
+
+A "character" is a _grapheme cluster_, as defined by
+[Unicode Standard Annex #29](http://unicode.org/reports/tr29/). Note that
+remote APIs may have a different definition of "character" for the purpose of
+length limits on string arguments; a Packer provider is responsible for
+translating Packer's string representation into that used by its respective
+remote system and applying any additional validation rules to it.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/lookup.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/lookup.mdx
new file mode 100644
index 0000000000..0eb686063f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/lookup.mdx
@@ -0,0 +1,26 @@
+---
+page_title: lookup - Functions - Configuration Language
+description: The lookup function retrieves an element value from a map given its key.
+---
+
+# `lookup` Function
+
+`lookup` retrieves the value of a single element from a map, given its key.
+If the given key does not exist, the given default value is returned instead.
+
+```hcl
+lookup(map, key, default)
+```
+
+## Examples
+
+```shell-session
+> lookup({a="ay", b="bee"}, "a", "what?")
+ay
+> lookup({a="ay", b="bee"}, "c", "what?")
+what?
+```
+
+## Related Functions
+
+- [`element`](/packer/docs/templates/hcl_templates/functions/collection/element) retrieves a value from a _list_ given its _index_.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/merge.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/merge.mdx
new file mode 100644
index 0000000000..e6ac8b7a6c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/merge.mdx
@@ -0,0 +1,25 @@
+---
+page_title: merge - Functions - Configuration Language
+description: |-
+ The merge function takes an arbitrary number of maps and returns a single
+ map after merging the keys from each argument.
+---
+
+# `merge` Function
+
+`merge` takes an arbitrary number of maps and returns a single map that
+contains a merged set of elements from all of the maps.
+
+If more than one given map defines the same key then the one that is later
+in the argument sequence takes precedence.
+
+## Examples
+
+```shell-session
+> merge({"a"="b", "c"="d"}, {"e"="f", "c"="z"})
+{
+ "a" = "b"
+ "c" = "z"
+ "e" = "f"
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/range.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/range.mdx
new file mode 100644
index 0000000000..9ddf0af0e3
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/range.mdx
@@ -0,0 +1,139 @@
+---
+page_title: range - Functions - Configuration Language
+description: The range function generates sequences of numbers.
+---
+
+# `range` Function
+
+`range` generates a list of numbers using a start value, a limit value,
+and a step value.
+
+```hcl
+range(max)
+range(start, limit)
+range(start, limit, step)
+```
+
+The `start` and `step` arguments can be omitted, in which case `start` defaults
+to zero and `step` defaults to either one or negative one depending on whether
+`limit` is greater than or less than `start`.
+
+The resulting list is created by starting with the given `start` value and
+repeatedly adding `step` to it until the result is equal to or beyond `limit`.
+
+The interpretation of `limit` depends on the direction of `step`: for a positive
+step, the sequence is complete when the next number is greater than or equal
+to `limit`. For a negative step, it's complete when less than or equal.
+
+The sequence-building algorithm follows the following pseudocode:
+
+```text
+let num = start
+while num < limit: (or, for negative step, num >= limit)
+ append num to the sequence
+ num = num + step
+return the sequence
+```
+
+Because the sequence is created as a physical list in memory, Packer imposes
+an artificial limit of 1024 numbers in the resulting sequence in order to avoid
+unbounded memory usage if, for example, a very large value were accidentally
+passed as the limit or a very small value as the step. If the algorithm above
+would append the 1025th number to the sequence, the function immediately exits
+with an error.
+
+We recommend iterating over existing collections where possible, rather than
+creating ranges. However, creating small numerical sequences can sometimes
+be useful when combined with other collections in collection-manipulation
+functions or `for` expressions.
+
+## Examples
+
+```shell-session
+> range(3)
+[
+ 0,
+ 1,
+ 2,
+]
+
+> range(1, 4)
+[
+ 1,
+ 2,
+ 3,
+]
+
+> range(1, 8, 2)
+[
+ 1,
+ 3,
+ 5,
+ 7,
+]
+
+> range(1, 4, 0.5)
+[
+ 1,
+ 1.5,
+ 2,
+ 2.5,
+ 3,
+ 3.5,
+]
+
+> range(4, 1)
+[
+ 4,
+ 3,
+ 2,
+]
+
+> range(10, 5, -2)
+[
+ 10,
+ 8,
+ 6,
+]
+```
+
+The `range` function is primarily useful when working with other collections
+to produce a certain number of instances of something. For example:
+
+```hcl
+variable "name_counts" {
+ type = map(number)
+ default = {
+ "foo" = 2
+ "bar" = 4
+ }
+}
+
+locals {
+ expanded_names = {
+ for name, count in var.name_counts : name => [
+ for i in range(count) : format("%s%02d", name, i)
+ ]
+ }
+}
+
+output "expanded_names" {
+ value = local.expanded_names
+}
+
+# Produces the following expanded_names value when run with the default
+# "name_counts":
+#
+# {
+# "bar" = [
+# "bar00",
+# "bar01",
+# "bar02",
+# "bar03",
+# ]
+# "foo" = [
+# "foo00",
+# "foo01",
+# ]
+# }
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/reverse.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/reverse.mdx
new file mode 100644
index 0000000000..743a97a5d8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/reverse.mdx
@@ -0,0 +1,24 @@
+---
+page_title: reverse - Functions - Configuration Language
+description: The reverse function reverses a sequence.
+---
+
+# `reverse` Function
+
+`reverse` takes a sequence and produces a new sequence of the same length
+with all of the same elements as the given sequence but in reverse order.
+
+## Examples
+
+```shell-session
+> reverse([1, 2, 3])
+[
+ 3,
+ 2,
+ 1,
+]
+```
+
+## Related Functions
+
+- [`strrev`](/packer/docs/templates/hcl_templates/functions/string/strrev) reverses a string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setintersection.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setintersection.mdx
new file mode 100644
index 0000000000..924b9a8b09
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setintersection.mdx
@@ -0,0 +1,38 @@
+---
+page_title: setintersection - Functions - Configuration Language
+description: |-
+ The setintersection function takes multiple sets and produces a single set
+ containing only the elements that all of the given sets have in common.
+---
+
+# `setintersection` Function
+
+The `setintersection` function takes multiple sets and produces a single set
+containing only the elements that all of the given sets have in common.
+In other words, it computes the
+[intersection]() of the sets.
+
+```hcl
+setintersection(sets...)
+```
+
+## Examples
+
+```shell-session
+> setintersection(["a", "b"], ["b", "c"], ["b", "d"])
+[
+ "b",
+]
+```
+
+The given arguments are converted to sets, so the result is also a set and
+the ordering of the given elements is not preserved.
+
+## Related Functions
+
+- [`contains`](/packer/docs/templates/hcl_templates/functions/collection/contains) tests whether a given list or set contains
+ a given element value.
+- [`setproduct`](/packer/docs/templates/hcl_templates/functions/collection/setproduct) computes the _Cartesian product_ of multiple
+ sets.
+- [`setunion`](/packer/docs/templates/hcl_templates/functions/collection/setunion) computes the _union_ of
+ multiple sets.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setproduct.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setproduct.mdx
new file mode 100644
index 0000000000..d9425f1202
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setproduct.mdx
@@ -0,0 +1,222 @@
+---
+page_title: setproduct - Functions - Configuration Language
+description: |-
+ The setproduct function finds all of the possible combinations of elements
+ from all of the given sets by computing the cartesian product.
+---
+
+# `setproduct` Function
+
+The `setproduct` function finds all of the possible combinations of elements
+from all of the given sets by computing the
+[Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product).
+
+```hcl
+setproduct(sets...)
+```
+
+This function is particularly useful for finding the exhaustive set of all
+combinations of members of multiple sets, such as per-application-per-environment
+resources.
+
+```shell-session
+> setproduct(["development", "staging", "production"], ["app1", "app2"])
+[
+ [
+ "development",
+ "app1",
+ ],
+ [
+ "development",
+ "app2",
+ ],
+ [
+ "staging",
+ "app1",
+ ],
+ [
+ "staging",
+ "app2",
+ ],
+ [
+ "production",
+ "app1",
+ ],
+ [
+ "production",
+ "app2",
+ ],
+]
+```
+
+You must past at least two arguments to this function.
+
+Although defined primarily for sets, this function can also work with lists.
+If all of the given arguments are lists then the result is a list, preserving
+the ordering of the given lists. Otherwise the result is a set. In either case,
+the result's element type is a list of values corresponding to each given
+argument in turn.
+
+## Examples
+
+There is an example of the common usage of this function above. There are some
+other situations that are less common when hand-writing but may arise in
+reusable folder situations.
+
+If any of the arguments is empty then the result is always empty itself,
+similar to how multiplying any number by zero gives zero:
+
+```shell-session
+> setproduct(["development", "staging", "production"], [])
+[]
+```
+
+Similarly, if all of the arguments have only one element then the result has
+only one element, which is the first element of each argument:
+
+```shell-session
+> setproduct(["a"], ["b"])
+[
+ [
+ "a",
+ "b",
+ ],
+]
+```
+
+Each argument must have a consistent type for all of its elements. If not,
+Packer will attempt to convert to the most general type, or produce an
+error if such a conversion is impossible. For example, mixing both strings and
+numbers results in the numbers being converted to strings so that the result
+elements all have a consistent type:
+
+```shell-session
+> setproduct(["staging", "production"], ["a", 2])
+[
+ [
+ "staging",
+ "a",
+ ],
+ [
+ "staging",
+ "2",
+ ],
+ [
+ "production",
+ "a",
+ ],
+ [
+ "production",
+ "2",
+ ],
+]
+```
+
+## Finding combinations for `for_each`
+
+The
+[resource `for_each`](/terraform/docs/configuration/resources#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
+and
+[`dynamic` block](/packer/docs/templates/hcl_templates/expressions/#dynamic-blocks)
+language features both require a collection value that has one element for
+each repetition.
+
+Sometimes your input data comes in separate values that cannot be directly
+used in a `for_each` argument, and `setproduct` can be a useful helper function
+for the situation where you want to find all unique combinations of elements in
+a number of different collections.
+
+For example, consider a folder that declares variables like the following:
+
+```hcl
+variable "networks" {
+ type = map(object({
+ base_cidr_block = string
+ }))
+}
+
+variable "subnets" {
+ type = map(object({
+ number = number
+ }))
+}
+```
+
+If the goal is to create each of the defined subnets per each of the defined
+networks, creating the top-level networks can directly use `var.networks`
+because it's already in a form where the resulting instances match one-to-one
+with map elements:
+
+```hcl
+resource "aws_vpc" "example" {
+ for_each = var.networks
+
+ cidr_block = each.value.base_cidr_block
+}
+```
+
+However, in order to declare all of the _subnets_ with a single `resource`
+block, we must first produce a collection whose elements represent all of
+the combinations of networks and subnets, so that each element itself
+represents a subnet:
+
+```hcl
+locals {
+ # setproduct works with sets and lists, but our variables are both maps
+ # so we'll need to convert them first.
+ networks = [
+ for key, network in var.networks : {
+ key = key
+ cidr_block = network.cidr_block
+ }
+ ]
+ subnets = [
+ for key, subnet in var.subnets : {
+ key = key
+ number = subnet.number
+ }
+ ]
+
+ network_subnets = [
+ # in pair, element zero is a network and element one is a subnet,
+ # in all unique combinations.
+ for pair in setproduct(local.networks, local.subnets) : {
+ network_key = pair[0].key
+ subnet_key = pair[1].key
+ network_id = aws_vpc.example[pair[0].key].id
+
+ # The cidr_block is derived from the corresponding network. See the
+ # cidrsubnet function for more information on how this calculation works.
+ cidr_block = cidrsubnet(pair[0].cidr_block, 4, pair[1].number)
+ }
+ ]
+}
+
+resource "aws_subnet" "example" {
+ # local.network_subnets is a list, so we must now project it into a map
+ # where each key is unique. We'll combine the network and subnet keys to
+ # produce a single unique key per instance.
+ for_each = {
+ for subnet in local.network_subnets : "${subnet.network_key}.${subnet.subnet_key}" => subnet
+ }
+
+ vpc_id = each.value.network_id
+ availability_zone = each.value.subnet_key
+ cidr_block = each.value_cidr_block
+}
+```
+
+The above results in one subnet instance per combination of network and subnet
+elements in the input variables.
+
+## Related Functions
+
+- [`contains`](/packer/docs/templates/hcl_templates/functions/collection/contains) tests whether a given list or set contains
+ a given element value.
+- [`flatten`](/packer/docs/templates/hcl_templates/functions/collection/flatten) is useful for flattening hierarchical data
+ into a single list, for situations where the relationships between two
+ object types are defined explicitly.
+- [`setintersection`](/packer/docs/templates/hcl_templates/functions/collection/setintersection) computes the _intersection_ of
+ multiple sets.
+- [`setunion`](/packer/docs/templates/hcl_templates/functions/collection/setunion) computes the _union_ of multiple
+ sets.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setunion.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setunion.mdx
new file mode 100644
index 0000000000..a78e2d4896
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/setunion.mdx
@@ -0,0 +1,41 @@
+---
+page_title: setunion - Functions - Configuration Language
+description: |-
+ The setunion function takes multiple sets and produces a single set
+ containing the elements from all of the given sets.
+---
+
+# `setunion` Function
+
+The `setunion` function takes multiple sets and produces a single set
+containing the elements from all of the given sets. In other words, it
+computes the [union]() of
+the sets.
+
+```hcl
+setunion(sets...)
+```
+
+## Examples
+
+```shell-session
+> setunion(["a", "b"], ["b", "c"], ["d"])
+[
+ "d",
+ "b",
+ "c",
+ "a",
+]
+```
+
+The given arguments are converted to sets, so the result is also a set and
+the ordering of the given elements is not preserved.
+
+## Related Functions
+
+- [`contains`](/packer/docs/templates/hcl_templates/functions/collection/contains) tests whether a given list or set contains
+ a given element value.
+- [`setintersection`](/packer/docs/templates/hcl_templates/functions/collection/setintersection) computes the _intersection_ of
+ multiple sets.
+- [`setproduct`](/packer/docs/templates/hcl_templates/functions/collection/setproduct) computes the _Cartesian product_ of multiple
+ sets.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/slice.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/slice.mdx
new file mode 100644
index 0000000000..f92ebc2ea9
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/slice.mdx
@@ -0,0 +1,31 @@
+---
+page_title: slice - Functions - Configuration Language
+description: The slice function extracts some consecutive elements from within a list.
+---
+
+# `slice` Function
+
+`slice` extracts some consecutive elements from within a list.
+
+```hcl
+slice(list, startindex, endindex)
+```
+
+`startindex` is inclusive, while `endindex` is exclusive. This function returns
+an error if either index is outside the bounds of valid indices for the given
+list.
+
+## Examples
+
+```shell-session
+> slice(["a", "b", "c", "d"], 1, 3)
+[
+ "b",
+ "c",
+]
+```
+
+## Related Functions
+
+- [`substr`](/packer/docs/templates/hcl_templates/functions/string/substr) performs a similar function for characters in a
+ string, although it uses a length instead of an end index.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/sort.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/sort.mdx
new file mode 100644
index 0000000000..edc3dd99fd
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/sort.mdx
@@ -0,0 +1,26 @@
+---
+page_title: sort - Functions - Configuration Language
+description: |-
+ The sort function takes a list of strings and returns a new list with those
+ strings sorted lexicographically.
+---
+
+# `sort` Function
+
+`sort` takes a list of strings and returns a new list with those strings
+sorted lexicographically.
+
+The sort is in terms of Unicode codepoints, with higher codepoints appearing
+after lower ones in the result.
+
+## Examples
+
+```shell-session
+> sort(["e", "d", "a", "x"])
+[
+ "a",
+ "d",
+ "e",
+ "x",
+]
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/values.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/values.mdx
new file mode 100644
index 0000000000..0fced24da2
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/values.mdx
@@ -0,0 +1,28 @@
+---
+page_title: values - Functions - Configuration Language
+description: The values function returns a list of the element values in a given map.
+---
+
+# `values` Function
+
+`values` takes a map and returns a list containing the values of the elements
+in that map.
+
+The values are returned in lexicographical order by their corresponding _keys_,
+so the values will be returned in the same order as their keys would be
+returned from [`keys`](/packer/docs/templates/hcl_templates/functions/collection/keys).
+
+## Examples
+
+```shell-session
+> values({a=3, c=2, d=1})
+[
+ 3,
+ 2,
+ 1,
+]
+```
+
+## Related Functions
+
+- [`keys`](/packer/docs/templates/hcl_templates/functions/collection/keys) returns a list of the _keys_ from a map.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/zipmap.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/zipmap.mdx
new file mode 100644
index 0000000000..fbdcb6a75f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/collection/zipmap.mdx
@@ -0,0 +1,33 @@
+---
+page_title: zipmap - Functions - Configuration Language
+description: |-
+ The zipmap function constructs a map from a list of keys and a corresponding
+ list of values.
+---
+
+# `zipmap` Function
+
+`zipmap` constructs a map from a list of keys and a corresponding list of
+values.
+
+```hcl
+zipmap(keyslist, valueslist)
+```
+
+Both `keyslist` and `valueslist` must be of the same length. `keyslist` must
+be a list of strings, while `valueslist` can be a list of any type.
+
+Each pair of elements with the same index from the two lists will be used
+as the key and value of an element in the resulting map. If the same value
+appears multiple times in `keyslist` then the value with the highest index
+is used in the resulting map.
+
+## Examples
+
+```shell-session
+> zipmap(["a", "b"], [1, 2])
+{
+ "a" = 1,
+ "b" = 2,
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/aws_secretsmanager.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/aws_secretsmanager.mdx
new file mode 100644
index 0000000000..73d5b06fcf
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/aws_secretsmanager.mdx
@@ -0,0 +1,91 @@
+---
+page_title: aws_secretsmanager - Functions - Configuration Language
+description: >-
+ The aws_secretsmanager function retrieves secrets from Amazon secretsmanager
+ stores.
+---
+
+# `aws_secretsmanager` Function
+
+Secrets can be read from the [AWS Secrets
+Manager](https://aws.amazon.com/secrets-manager/) and used within your template
+as locals.
+
+~> Note: Support for AWS secrets will always obtain the latest version of a secret, essentially
+AWSCURRENT. Support for previous versions of a secret is not supported.
+
+```hcl
+aws_secretsmanager(name, key)
+```
+
+When key is not set (`null` or empty: `""`) then `aws_secretsmanager` returns
+the first secret key stored in secret `name`.
+
+You can either use this function in a `locals` block or directly inline where
+you want to use the value.
+
+```hcl
+locals {
+ secret = aws_secretsmanager("my_secret", null)
+}
+
+source "null" "first-example" {
+ communicator = "none"
+}
+
+build {
+ name = "my-build-name"
+ sources = ["null.first-example"]
+
+ provisioner "shell-local" {
+ environment_vars = ["TESTVAR=${build.PackerRunUUID}"]
+ inline = ["echo my_secret is '${local.secret}'",
+ "echo my_secret using an inline call is '${aws_secretsmanager("my_secret", null)}'."]
+ }
+}
+```
+
+This will load the key stored behind `my_secret` from aws secrets manager.
+
+The retrieval of single key secrets or plaintext secrets can be obtained by specifying (`null` or empty: `""`) as the `key`.
+
+When obtaining secrets that have multiple keys you can set `key` to the specific key you would like
+to fetch. For example, given the following secret with two keys if `key` is set to "shell" `aws_secretsmanager` will
+return only its value.
+
+```json
+{
+ "test": "kitchen",
+ "shell": "powershell"
+}
+```
+
+```hcl
+locals {
+ secret = aws_secretsmanager("multikey/secret", "shell")
+}
+
+source "null" "first-example" {
+ communicator = "none"
+}
+
+build {
+ name = "my-build-name"
+ sources = ["null.first-example"]
+
+ provisioner "shell-local" {
+ environment_vars = ["TESTVAR=${build.PackerRunUUID}"]
+ inline = ["echo my_secret is '${local.secret}'"]
+ }
+}
+```
+
+This will load the value `"powershell"` stored in the key `"shell"` behind `multikey/secret`.
+
+In order to use this function you have to configure valid AWS credentials using
+one of the following methods:
+
+- [Environment Variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
+- [CLI Configuration Files](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+- [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)
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/consul.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/consul.mdx
new file mode 100644
index 0000000000..fff91894f2
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/consul.mdx
@@ -0,0 +1,39 @@
+---
+page_title: consul - Functions - Configuration Language
+description: The consul function retrieves secrets from HashiCorp consul KV stores.
+---
+
+# `consul_key` Function
+
+[Consul](https://www.consul.io/) keys can be used within your template using the
+`consul_key` function.
+
+You can either use this function in a locals block or directly inline where you
+want to use the value.
+
+```hcl
+locals {
+ my_version = "${consul_key("myservice/version")}"
+}
+
+source "null" "first-example" {
+ communicator = "none"
+}
+
+build {
+ name = "my-build-name"
+ sources = ["null.first-example"]
+
+ provisioner "shell-local" {
+ environment_vars = ["TESTVAR=${build.PackerRunUUID}"]
+ inline = ["echo my_version is '${local.my_version}'",
+ "echo version is '${consul_key("myservice/version")}'."]
+ }
+}
+```
+
+This will load the key stored at the path `myservice/version` from consul.
+
+The configuration for consul (address, tokens, ...) must be specified as
+environment variables, as specified in the
+[Documentation](/consul/commands#environment-variables).
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/env.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/env.mdx
new file mode 100644
index 0000000000..3749e899df
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/contextual/env.mdx
@@ -0,0 +1,49 @@
+---
+page_title: env - Functions - Configuration Language
+description: The env function retrieves environment values for input variables.
+---
+
+# `env` Function
+
+```hcl
+variable "aws_region" {
+ default = env("AWS_DEFAULT_REGION")
+}
+```
+
+`env` allows you to get the value for an environment variable inside input
+variables _only_. This is the only function that is callable from a variable
+block and it can only be used in the default input. `env` cannot be called from
+other places.
+
+In the previous example, the value of `aws_region` will be what's stored in the
+`AWS_DEFAULT_REGION` env var, unless aws_region is also set in a [manner that takes
+precedence](/packer/docs/templates/hcl_templates/variables#variable-definition-precedence).
+
+-> **Why can't I use environment variables elsewhere?** User variables are the
+single source of configurable input. We felt that having environment variables
+used _anywhere_ in a configuration would confuse the user about the possible inputs
+to a template. By allowing environment variables only within default values for
+input variables, input variables remain as the single source of input to a
+template that a user can easily discover using `packer inspect`.
+
+When the environment variable is not set at all -- not even with the empty
+string -- the value returned by `env` will be an empty string. It will still
+be possible to set it using other means but you could use [custom validation
+rules](/packer/docs/templates/hcl_templates/variables#custom-validation-rules) to error in that case
+to make sure it is set, for example:
+
+```hcl
+variable "aws_region" {
+ default = env("AWS_DEFAULT_REGION")
+
+ validation {
+ condition = length(var.aws_region) > 0
+ error_message = <`. See [Local Values](/packer/docs/templates/hcl_templates/locals) for more details.
+
+
+## Usage
+
+In order for the Vault function to work, you must set the environment variables `VAULT_TOKEN`
+and `VAULT_ADDR` to valid values.
+
+-> **NOTE:** HCL functions can be used in local variable definitions or inline
+with a provisioner/post-processor. They cannot be used in global variable definitions.
+
+The api tool we use allows for more custom configuration of the Vault client via
+environment variables.
+
+The full list of available environment variables is:
+
+```text
+"VAULT_ADDR"
+"VAULT_AGENT_ADDR"
+"VAULT_CACERT"
+"VAULT_CAPATH"
+"VAULT_CLIENT_CERT"
+"VAULT_CLIENT_KEY"
+"VAULT_CLIENT_TIMEOUT"
+"VAULT_SKIP_VERIFY"
+"VAULT_NAMESPACE"
+"VAULT_TLS_SERVER_NAME"
+"VAULT_WRAP_TTL"
+"VAULT_MAX_RETRIES"
+"VAULT_TOKEN"
+"VAULT_MFA"
+"VAULT_RATE_LIMIT"
+```
+
+and detailed documentation for usage of each of those variables can be found
+[here](/vault/docs/commands#environment-variables).
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/can.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/can.mdx
new file mode 100644
index 0000000000..4272cbbcbe
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/can.mdx
@@ -0,0 +1,57 @@
+---
+page_title: can - Functions - Configuration Language
+description: |-
+ The can function tries to evaluate an expression given as an argument and
+ indicates whether the evaluation succeeded.
+---
+
+# `can` Function
+
+`can` evaluates the given expression and returns a boolean value indicating
+whether the expression produced a result without any errors.
+
+This is a special function that is able to catch errors produced when evaluating
+its argument. For most situations where you could use `can` it's better to use
+[`try`](/packer/docs/templates/hcl_templates/functions/conversion/try) instead, because it allows for more concise definition of
+fallback values for failing expressions.
+
+The `can` function can only catch and handle _dynamic_ errors resulting from
+access to data that isn't known until runtime. It will not catch errors
+relating to expressions that can be proven to be invalid for any input, such
+as a malformed resource reference.
+
+~> **Warning:** The `can` function is intended only for simple tests in
+variable validation rules. Although it can technically accept any sort of
+expression and be used elsewhere in the configuration, we recommend against
+using it in other contexts. For error handling elsewhere in the configuration,
+prefer to use [`try`](/packer/docs/templates/hcl_templates/functions/conversion/try).
+
+## Examples
+
+```shell-session
+> local.foo
+{
+ "bar" = "baz"
+}
+> can(local.foo.bar)
+true
+> can(local.foo.boop)
+false
+```
+
+The `can` function will _not_ catch errors relating to constructs that are
+provably invalid even before dynamic expression evaluation, such as a malformed
+reference or a reference to a top-level object that has not been declared:
+
+```shell-session
+> can(local.nonexist)
+
+Error: Reference to undeclared local value
+
+A local value with the name "nonexist" has not been declared.
+```
+
+## Related Functions
+
+- [`try`](/packer/docs/templates/hcl_templates/functions/conversion/try), which tries evaluating a sequence of expressions and
+ returns the result of the first one that succeeds.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/convert.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/convert.mdx
new file mode 100644
index 0000000000..5cb90d1576
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/convert.mdx
@@ -0,0 +1,52 @@
+---
+page_title: convert - Functions - Configuration Language
+description: 'The convert function converts a value or an expression to a given type. '
+---
+
+# `convert` Function
+
+`convert` converts a value or an expression to a given type.
+
+Explicit type conversions are rarely necessary in HCL because it will convert
+types automatically where required. Use the explicit type conversion functions
+only to normalize types returned in outputs.
+
+Only numbers and strings containing decimal representations of numbers can be
+converted to number. All other values will produce an error.
+
+Only boolean values and the exact strings "true" and "false" can be converted
+to boolean. All other values will produce an error.
+
+Only the primitive types (string, number, and bool) can be converted to string.
+All other values will produce an error.
+
+`convert(value, type_constraint)`
+
+## Examples
+
+```shell-session
+> convert(3, string)
+"3"
+> convert("3", number)
+3
+> convert("false", bool)
+false
+> convert(false, string)
+"false"
+> convert(["a", "b", 3], list)
+[
+ "a",
+ "b",
+ "3",
+]
+> convert(["c", "b", "b"], set)
+[
+ "b",
+ "c",
+]
+> convert({"a" = "foo", "b" = true}, map)
+{
+ "a" = "foo"
+ "b" = "true"
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/try.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/try.mdx
new file mode 100644
index 0000000000..a34e6e293c
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/conversion/try.mdx
@@ -0,0 +1,111 @@
+---
+page_title: try - Functions - Configuration Language
+description: |-
+ The try function tries to evaluate a sequence of expressions given as
+ arguments and returns the result of the first one that does not produce
+ any errors.
+---
+
+# `try` Function
+
+`try` evaluates all of its argument expressions in turn and returns the result
+of the first one that does not produce any errors.
+
+This is a special function that is able to catch errors produced when evaluating
+its arguments, which is particularly useful when working with complex data
+structures whose shape is not well-known at implementation time.
+
+For example, if some data is retrieved from an external system in JSON or YAML
+format and then decoded, the result may have attributes that are not guaranteed
+to be set. We can use `try` to produce a normalized data structure which has
+a predictable type that can therefore be used more conveniently elsewhere in
+the configuration:
+
+```hcl
+locals {
+ raw_value = yamldecode("${path.folder}/example.yaml")
+ normalized_value = {
+ name = tostring(try(local.raw_value.name, null))
+ groups = try(local.raw_value.groups, [])
+ }
+}
+```
+
+With the above local value expressions, configuration elsewhere in the folder
+can refer to `local.normalized_value` attributes without the need to repeatedly
+check for and handle absent attributes that would otherwise produce errors.
+
+We can also use `try` to deal with situations where a value might be provided
+in two different forms, allowing us to normalize to the most general form:
+
+```hcl
+variable "example" {
+ type = any
+}
+
+locals {
+ example = try(
+ [tostring(var.example)],
+ tolist(var.example),
+ )
+}
+```
+
+The above permits `var.example` to be either a list or a single string. If it's
+a single string then it'll be normalized to a single-element list containing
+that string, again allowing expressions elsewhere in the configuration to just
+assume that `local.example` is always a list.
+
+This second example contains two expressions that can both potentially fail.
+For example, if `var.example` were set to `{}` then it could be converted to
+neither a string nor a list. If `try` exhausts all of the given expressions
+without any succeeding, it will return an error describing all of the problems
+it encountered.
+
+We strongly suggest using `try` only in special local values whose expressions
+perform normalization, so that the error handling is confined to a single
+location in the folder and the rest of the folder can just use straightforward
+references to the normalized structure and thus be more readable for future
+maintainers.
+
+The `try` function can only catch and handle _dynamic_ errors resulting from
+access to data that isn't known until runtime. It will not catch errors
+relating to expressions that can be proven to be invalid for any input, such
+as a malformed resource reference.
+
+~> **Warning:** The `try` function is intended only for concise testing of the
+presence of and types of object attributes. Although it can technically accept
+any sort of expression, we recommend using it only with simple attribute
+references and type conversion functions as shown in the examples above.
+Overuse of `try` to suppress errors will lead to a configuration that is hard
+to understand and maintain.
+
+## Examples
+
+```shell-session
+> local.foo
+{
+ "bar" = "baz"
+}
+> try(local.foo.bar, "fallback")
+baz
+> try(local.foo.boop, "fallback")
+fallback
+```
+
+The `try` function will _not_ catch errors relating to constructs that are
+provably invalid even before dynamic expression evaluation, such as a malformed
+reference or a reference to a top-level object that has not been declared:
+
+```shell-session
+> try(local.nonexist, "fallback")
+
+Error: Reference to undeclared local value
+
+A local value with the name "nonexist" has not been declared.
+```
+
+## Related Functions
+
+- [`can`](/packer/docs/templates/hcl_templates/functions/conversion/can), which tries evaluating an expression and returns a
+ boolean value indicating whether it succeeded.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/bcrypt.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/bcrypt.mdx
new file mode 100644
index 0000000000..c49779c2c3
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/bcrypt.mdx
@@ -0,0 +1,36 @@
+---
+page_title: bcrypt - Functions - Configuration Language
+description: |-
+ The bcrypt function computes a hash of the given string using the Blowfish
+ cipher.
+---
+
+# `bcrypt` Function
+
+`bcrypt` computes a hash of the given string using the Blowfish cipher,
+returning a string in [the _Modular Crypt
+Format_](https://passlib.readthedocs.io/en/stable/modular_crypt_format.html)
+usually expected in the shadow password file on many Unix systems.
+
+```hcl
+bcrypt(string, cost)
+```
+
+The `cost` argument is optional and will default to 10 if unspecified.
+
+Since a bcrypt hash value includes a randomly selected salt, each call to this
+function will return a different value, even if the given string and cost are
+the same. Using this function directly with resource arguments will therefore
+cause spurious diffs. We recommend using this function only in `provisioner` or
+`post-processor` blocks, or in data resources whose results are only used in
+those blocks.
+
+The version prefix on the generated string (e.g. `$2a$`) may change in future
+versions of Packer.
+
+## Examples
+
+```shell-session
+> bcrypt("hello world")
+$2a$10$D5grTTzcsqyvAeIAnY/mYOIqliCoG7eAMX0/oFcuD.iErkksEbcAa
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/md5.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/md5.mdx
new file mode 100644
index 0000000000..f777aa65d0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/md5.mdx
@@ -0,0 +1,26 @@
+---
+page_title: md5 - Functions - Configuration Language
+description: |-
+ The md5 function computes the MD5 hash of a given string and encodes it
+ with hexadecimal digits.
+---
+
+# `md5` Function
+
+`md5` computes the MD5 hash of a given string and encodes it with
+hexadecimal digits.
+
+The given string is first encoded as UTF-8 and then the MD5 algorithm is applied
+as defined in [RFC 1321](https://tools.ietf.org/html/rfc1321). The raw hash is
+then encoded to lowercase hexadecimal digits before returning.
+
+Before using this function for anything security-sensitive, refer to
+[RFC 6151](https://tools.ietf.org/html/rfc6151) for updated security
+considerations applying to the MD5 algorithm.
+
+## Examples
+
+```shell-session
+> md5("hello world")
+5eb63bbbe01eeed093cb22bb8f5acdc3
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/rsadecrypt.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/rsadecrypt.mdx
new file mode 100644
index 0000000000..59339c6515
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/rsadecrypt.mdx
@@ -0,0 +1,31 @@
+---
+page_title: rsadecrypt - Functions - Configuration Language
+description: The rsadecrypt function decrypts an RSA-encrypted message.
+---
+
+# `rsadecrypt` Function
+
+`rsadecrypt` decrypts an RSA-encrypted ciphertext, returning the corresponding
+cleartext.
+
+```hcl
+rsadecrypt(ciphertext, privatekey)
+```
+
+`ciphertext` must be a base64-encoded representation of the ciphertext, using
+the PKCS #1 v1.5 padding scheme. Packer uses the "standard" Base64 alphabet
+as defined in [RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4).
+
+`privatekey` must be a PEM-encoded RSA private key that is not itself
+encrypted.
+
+Packer has no corresponding function for _encrypting_ a message. Use this
+function to decrypt ciphertexts returned by remote services using a keypair
+negotiated out-of-band.
+
+## Examples
+
+```shell-session
+> rsadecrypt(base64(file("${path.folder}/ciphertext")), file("privatekey.pem"))
+Hello, world!
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha1.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha1.mdx
new file mode 100644
index 0000000000..a001654fa5
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha1.mdx
@@ -0,0 +1,26 @@
+---
+page_title: sha1 - Functions - Configuration Language
+description: |-
+ The sha1 function computes the SHA1 hash of a given string and encodes it
+ with hexadecimal digits.
+---
+
+# `sha1` Function
+
+`sha1` computes the SHA1 hash of a given string and encodes it with
+hexadecimal digits.
+
+The given string is first encoded as UTF-8 and then the SHA1 algorithm is applied
+as defined in [RFC 3174](https://tools.ietf.org/html/rfc3174). The raw hash is
+then encoded to lowercase hexadecimal digits before returning.
+
+Collision attacks have been successfully performed against this hashing
+function. Before using this function for anything security-sensitive, review
+relevant literature to understand the security implications.
+
+## Examples
+
+```shell-session
+> sha1("hello world")
+2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha256.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha256.mdx
new file mode 100644
index 0000000000..06133dba33
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha256.mdx
@@ -0,0 +1,22 @@
+---
+page_title: sha256 - Functions - Configuration Language
+description: |-
+ The sha256 function computes the SHA256 hash of a given string and encodes it
+ with hexadecimal digits.
+---
+
+# `sha256` Function
+
+`sha256` computes the SHA256 hash of a given string and encodes it with
+hexadecimal digits.
+
+The given string is first encoded as UTF-8 and then the SHA256 algorithm is applied
+as defined in [RFC 4634](https://tools.ietf.org/html/rfc4634). The raw hash is
+then encoded to lowercase hexadecimal digits before returning.
+
+## Examples
+
+```shell-session
+> sha256("hello world")
+b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha512.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha512.mdx
new file mode 100644
index 0000000000..3d58ecf900
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/crypto/sha512.mdx
@@ -0,0 +1,22 @@
+---
+page_title: sha512 - Functions - Configuration Language
+description: |-
+ The sha512 function computes the SHA512 hash of a given string and encodes it
+ with hexadecimal digits.
+---
+
+# `sha512` Function
+
+`sha512` computes the SHA512 hash of a given string and encodes it with
+hexadecimal digits.
+
+The given string is first encoded as UTF-8 and then the SHA512 algorithm is applied
+as defined in [RFC 4634](https://tools.ietf.org/html/rfc4634). The raw hash is
+then encoded to lowercase hexadecimal digits before returning.
+
+## Examples
+
+```shell-session
+> sha512("hello world")
+309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/formatdate.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/formatdate.mdx
new file mode 100644
index 0000000000..708b6a6842
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/formatdate.mdx
@@ -0,0 +1,105 @@
+---
+page_title: formatdate - Functions - Configuration Language
+description: The formatdate function converts a timestamp into a different time format.
+---
+
+# `formatdate` Function
+
+`formatdate` converts a timestamp into a different time format.
+
+```hcl
+formatdate(spec, timestamp)
+```
+
+In Packer, timestamps are conventionally represented as strings using [RFC
+3339](https://tools.ietf.org/html/rfc3339) "Date and Time format" syntax.
+`formatdate` requires the `timestamp` argument to be a string conforming to
+this syntax.
+
+## Examples
+
+```shell-session
+> formatdate("DD MMM YYYY hh:mm ZZZ", "2018-01-02T23:12:01Z")
+02 Jan 2018 23:12 UTC
+> formatdate("EEEE, DD-MMM-YY hh:mm:ss ZZZ", "2018-01-02T23:12:01Z")
+Tuesday, 02-Jan-18 23:12:01 UTC
+> formatdate("EEE, DD MMM YYYY hh:mm:ss ZZZ", "2018-01-02T23:12:01-08:00")
+Tue, 02 Jan 2018 23:12:01 -0800
+> formatdate("MMM DD, YYYY", "2018-01-02T23:12:01Z")
+Jan 02, 2018
+> formatdate("HH:mmaa", "2018-01-02T23:12:01Z")
+11:12pm
+```
+
+## Specification Syntax
+
+The format specification is a string that includes formatting sequences from
+the following table. This function is intended for producing common
+_machine-oriented_ timestamp formats such as those defined in RFC822, RFC850,
+and RFC1123. It is not suitable for truly human-oriented date formatting
+because it is not locale-aware. In particular, it can produce month and day
+names only in English.
+
+The specification may contain the following sequences:
+
+| Sequence | Result |
+| -------- | ----------------------------------------------------------------------- |
+| `YYYY` | Four (or more) digit year, like "2006". |
+| `YY` | The year modulo 100, zero padded to at least two digits, like "06". |
+| `MMMM` | English month name unabbreviated, like "January". |
+| `MMM` | English month name abbreviated to three letters, like "Jan". |
+| `MM` | Month number zero-padded to two digits, like "01" for January. |
+| `M` | Month number with no padding, like "1" for January. |
+| `DD` | Day of month number zero-padded to two digits, like "02". |
+| `D` | Day of month number with no padding, like "2". |
+| `EEEE` | English day of week name unabbreviated, like "Monday". |
+| `EEE` | English day of week name abbreviated to three letters, like "Mon". |
+| `hh` | 24-hour number zero-padded to two digits, like "02". |
+| `h` | 24-hour number unpadded, like "2". |
+| `HH` | 12-hour number zero-padded to two digits, like "02". |
+| `H` | 12-hour number unpadded, like "2". |
+| `AA` | Hour AM/PM marker in uppercase, like "AM". |
+| `aa` | Hour AM/PM marker in lowercase, like "am". |
+| `mm` | Minute within hour zero-padded to two digits, like "05". |
+| `m` | Minute within hour unpadded, like "5". |
+| `ss` | Second within minute zero-padded to two digits, like "09". |
+| `s` | Second within minute, like "9". |
+| `ZZZZZ` | Timezone offset with colon separating hours and minutes, like "-08:00". |
+| `ZZZZ` | Timezone offset with just sign and digit, like "-0800". |
+| `ZZZ` | Like `ZZZZ` but with a special case "UTC" for UTC. |
+| `Z` | Like `ZZZZZ` but with a special case "Z" for UTC. |
+
+Any non-letter characters, such as punctuation, are reproduced verbatim in the
+output. To include literal letters in the format string, enclose them in single
+quotes `'`. To include a literal quote, escape it by doubling the quotes.
+
+```shell-session
+> formatdate("h'h'mm", "2018-01-02T23:12:01-08:00")
+23h12
+> formatdate("H 'o''clock'", "2018-01-02T23:12:01-08:00")
+11 o'clock
+```
+
+This format specification syntax is intended to make it easy for a reader
+to guess which format will result even if they are not experts on the syntax.
+Therefore there are no predefined shorthands for common formats, but format
+strings for various RFC-specified formats are given below to be copied into your
+configuration as needed:
+
+- [RFC 822](https://tools.ietf.org/html/rfc822#section-5) and
+ [RFC RFC 2822](https://tools.ietf.org/html/rfc2822#section-3.3):
+ `"DD MMM YYYY hh:mm ZZZ"`
+- [RFC 850](https://tools.ietf.org/html/rfc850#section-2.1.4):
+ `"EEEE, DD-MMM-YY hh:mm:ss ZZZ"`
+- [RFC 1123](https://tools.ietf.org/html/rfc1123#section-5.2.14):
+ `"EEE, DD MMM YYYY hh:mm:ss ZZZ"`
+- [RFC 3339](https://tools.ietf.org/html/rfc3339):
+ `"YYYY-MM-DD'T'hh:mm:ssZ"` (but this is also the input format, so such a
+ conversion is redundant.)
+
+## Related Functions
+
+- [`format`](/packer/docs/templates/hcl_templates/functions/string/format) is a more general formatting function for arbitrary
+ data.
+- [`timestamp`](/packer/docs/templates/hcl_templates/functions/datetime/timestamp) returns the current date and time in a format
+ suitable for input to `formatdate`.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/legacy_isotime.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/legacy_isotime.mdx
new file mode 100644
index 0000000000..37217a5f4d
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/legacy_isotime.mdx
@@ -0,0 +1,41 @@
+---
+page_title: legacy_isotime - Functions - Configuration Language
+description: |-
+ The legacy_isotime function returns a string representation of the current date
+ and time.
+---
+
+# `legacy_isotime` Function
+
+The `legacy_isotime` function returns the current date and time using the given format string.
+The format string follows Go's datetime formatting. See
+[isotime-function-format-reference](/packer/docs/templates/legacy_json_templates/engine#isotime-function-format-reference)
+for more details.
+
+This function has been provided to create backwards compatibility with
+Packer's legacy JSON templates. However, we recommend that you upgrade your
+HCL Packer template to use [`timestamp`](/packer/docs/templates/hcl_templates/functions/datetime/timestamp)
+and [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) together as soon as is convenient.
+
+-> **Note:** If you are using a large number of builders, provisioners
+or post-processors, the isotime may be slightly different for each one
+because it is from when the plugin is launched not the initial Packer
+process. In order to avoid this and make the timestamp consistent across all
+plugins, set it as a user variable and then access the user variable within
+your plugins.
+
+## Examples
+
+```shell-session
+> legacy_isotime("2006-01-02")
+2021-04-19
+```
+
+## Related Functions
+
+- [`format`](/packer/docs/templates/hcl_templates/functions/string/format) is a more general formatting function for arbitrary
+data.
+- [`timestamp`](/packer/docs/templates/hcl_templates/functions/datetime/timestamp) returns the current date and time in a format
+suitable for input to `formatdate`.
+- [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) can convert the resulting timestamp to
+ other date and time formats.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/legacy_strftime.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/legacy_strftime.mdx
new file mode 100644
index 0000000000..c993315076
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/legacy_strftime.mdx
@@ -0,0 +1,40 @@
+---
+page_title: legacy_strftime - Functions - Configuration Language
+description: |-
+ The legacy_strftime function returns a string representation of the current date
+ and time.
+---
+
+# `legacy_strftime` — UTC time, formated using the ISO C standard format
+
+The `legacy_strftime` function returns the current date and time using the given
+format string. The format string follows strftime's datetime formatting.
+
+This function has been provided to create backwards compatibility with Packer's
+legacy JSON templates. However, we recommend that you upgrade your HCL Packer
+template to use
+[`timestamp`](/packer/docs/templates/hcl_templates/functions/datetime/timestamp) and
+[`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate)
+together as soon as is convenient.
+
+-> **Note:** If you are using a large number of builders, provisioners or
+post-processors, the strftime may be slightly different for each one because it
+is from when the plugin is launched not the initial Packer process. In order to
+avoid this and make the timestamp consistent across all plugins, set it as a
+user variable and then access the user variable within your plugins.
+
+## Examples
+
+```shell-session
+> legacy_strftime("%Y-%m")
+2021-08
+```
+
+## Related Functions
+
+- [`format`](/packer/docs/templates/hcl_templates/functions/string/format) is a more general formatting function for arbitrary
+data.
+- [`timestamp`](/packer/docs/templates/hcl_templates/functions/datetime/timestamp) returns the current date and time in a format
+suitable for input to `formatdate`.
+- [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) can convert the resulting timestamp to
+ other date and time formats.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/timeadd.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/timeadd.mdx
new file mode 100644
index 0000000000..0a19c566b6
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/timeadd.mdx
@@ -0,0 +1,40 @@
+---
+page_title: timeadd - Functions - Configuration Language
+description: |-
+ The timeadd function adds a duration to a timestamp, returning a new
+ timestamp.
+---
+
+# `timeadd` Function
+
+`timeadd` adds a duration to a timestamp, returning a new timestamp.
+
+```hcl
+timeadd(timestamp, duration)
+```
+
+In the Packer language, timestamps are conventionally represented as
+strings using [RFC 3339](https://tools.ietf.org/html/rfc3339)
+"Date and Time format" syntax. `timeadd` requires the `timestamp` argument
+to be a string conforming to this syntax.
+
+`duration` is a string representation of a time difference, consisting of
+sequences of number and unit pairs, like `"1.5h"` or `"1h30m"`. The accepted
+units are `"ns"`, `"us"` (or `"µs"`), `"ms"`, `"s"`, `"m"`, and `"h"`. The first
+number may be negative to indicate a negative duration, like `"-2h5m"`.
+
+The result is a string, also in RFC 3339 format, representing the result
+of adding the given direction to the given timestamp.
+
+-> **Breaking change note:** Packer previously let you decide your own "Date
+and Time format" syntax. With HCL2 and for parity with Terraform, Packer will
+be using the [RFC 3339](https://tools.ietf.org/html/rfc3339) "Date and Time
+format" syntax. As a string. [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) still allows you
+to format a date.
+
+## Examples
+
+```shell-session
+> timeadd("2017-11-22T00:00:00Z", "10m")
+2017-11-22T00:10:00Z
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/timestamp.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/timestamp.mdx
new file mode 100644
index 0000000000..b27eb1123a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/datetime/timestamp.mdx
@@ -0,0 +1,37 @@
+---
+page_title: timestamp - Functions - Configuration Language
+description: |-
+ The timestamp function returns a string representation of the current date
+ and time.
+---
+
+# `timestamp` Function
+
+`timestamp` returns the current date and time.
+
+In the Packer language, timestamps are conventionally represented as
+strings using [RFC 3339](https://tools.ietf.org/html/rfc3339)
+"Date and Time format" syntax, and so `timestamp` returns a string
+in this format.
+
+The result of this function will change every second, so using this function
+directly with resource attributes will cause a diff to be detected on every
+Packer run.
+
+-> **Breaking change note:** Packer previously let you decide your own "Date
+and Time format" syntax. With HCL2 and for parity with Terraform, Packer will
+be using the [RFC 3339](https://tools.ietf.org/html/rfc3339) "Date and Time
+format" syntax. As a string. [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) still allows you
+to format a date.
+
+## Examples
+
+```shell-session
+> timestamp()
+2018-05-13T07:44:12Z
+```
+
+## Related Functions
+
+- [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) can convert the resulting timestamp to
+ other date and time formats.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/base64decode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/base64decode.mdx
new file mode 100644
index 0000000000..8d91882304
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/base64decode.mdx
@@ -0,0 +1,36 @@
+---
+page_title: base64decode - Functions - Configuration Language
+description: The base64decode function decodes a string containing a base64 sequence.
+---
+
+# `base64decode` Function
+
+`base64decode` takes a string containing a Base64 character sequence and
+returns the original string.
+
+Packer uses the "standard" Base64 alphabet as defined in
+[RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4).
+
+Strings in the Packer language are sequences of unicode characters rather
+than bytes, so this function will also interpret the resulting bytes as
+UTF-8. If the bytes after Base64 decoding are _not_ valid UTF-8, this function
+produces an error.
+
+While we do not recommend manipulating large, raw binary data in the Packer
+language, Base64 encoding is the standard way to represent arbitrary byte
+sequences, and so resource types that accept or return binary data will use
+Base64 themselves, which avoids the need to encode or decode it directly in
+most cases. Various other functions with names containing "base64" can generate
+or manipulate Base64 data directly.
+
+## Examples
+
+```shell-session
+> base64decode("SGVsbG8gV29ybGQ=")
+Hello World
+```
+
+## Related Functions
+
+- [`base64encode`](/packer/docs/templates/hcl_templates/functions/encoding/base64encode) performs the opposite operation,
+ encoding the UTF-8 bytes for a string as Base64.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/base64encode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/base64encode.mdx
new file mode 100644
index 0000000000..2d3441d888
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/base64encode.mdx
@@ -0,0 +1,37 @@
+---
+page_title: base64encode - Functions - Configuration Language
+description: The base64encode function applies Base64 encoding to a string.
+---
+
+# `base64encode` Function
+
+`base64encode` applies Base64 encoding to a string.
+
+Packer uses the "standard" Base64 alphabet as defined in
+[RFC 4648 section 4](https://tools.ietf.org/html/rfc4648#section-4).
+
+Strings in the Packer language are sequences of unicode characters rather
+than bytes, so this function will first encode the characters from the string
+as UTF-8, and then apply Base64 encoding to the result.
+
+The Packer language applies Unicode normalization to all strings, and so
+passing a string through `base64decode` and then `base64encode` may not yield
+the original result exactly.
+
+While we do not recommend manipulating large, raw binary data in the Packer
+language, Base64 encoding is the standard way to represent arbitrary byte
+sequences, and so resource types that accept or return binary data will use
+Base64 themselves, and so this function exists primarily to allow string
+data to be easily provided to resource types that expect Base64 bytes.
+
+## Examples
+
+```shell-session
+> base64encode("Hello World")
+SGVsbG8gV29ybGQ=
+```
+
+## Related Functions
+
+- [`base64decode`](/packer/docs/templates/hcl_templates/functions/encoding/base64decode) performs the opposite operation,
+ decoding Base64 data and interpreting it as a UTF-8 string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/csvdecode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/csvdecode.mdx
new file mode 100644
index 0000000000..88cb42d49e
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/csvdecode.mdx
@@ -0,0 +1,95 @@
+---
+page_title: csvdecode - Functions - Configuration Language
+description: The csvdecode function decodes CSV data into a list of maps.
+---
+
+# `csvdecode` Function
+
+`csvdecode` decodes a string containing CSV-formatted data and produces a
+list of maps representing that data.
+
+CSV is _Comma-separated Values_, an encoding format for tabular data. There
+are many variants of CSV, but this function implements the format defined
+in [RFC 4180](https://tools.ietf.org/html/rfc4180).
+
+The first line of the CSV data is interpreted as a "header" row: the values
+given are used as the keys in the resulting maps. Each subsequent line becomes
+a single map in the resulting list, matching the keys from the header row
+with the given values by index. All lines in the file must contain the same
+number of fields, or this function will produce an error.
+
+## Examples
+
+```shell-session
+> csvdecode("a,b,c\n1,2,3\n4,5,6")
+[
+ {
+ "a" = "1"
+ "b" = "2"
+ "c" = "3"
+ },
+ {
+ "a" = "4"
+ "b" = "5"
+ "c" = "6"
+ }
+]
+```
+
+## Use with the `for_each` meta-argument
+
+You can use the result of `csvdecode` with
+[the `for_each` meta-argument](/terraform/docs/configuration/resources#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
+to describe a collection of similar objects whose differences are
+described by the rows in the given CSV file.
+
+There must be one column in the CSV file that can serve as a unique ID for each
+row, which we can then use as the tracking key for the individual instances in
+the `for_each` expression. For example:
+
+```hcl
+locals {
+ # We've included this inline to create a complete example, but in practice
+ # this is more likely to be loaded from a file using the "file" function.
+ csv_data = <<-CSV
+ local_id,instance_type,ami
+ foo1,t2.micro,ami-54d2a63b
+ foo2,t2.micro,ami-54d2a63b
+ foo3,t2.micro,ami-54d2a63b
+ bar1,m3.large,ami-54d2a63b
+ CSV
+
+ instances = csvdecode(local.csv_data)
+}
+
+resource "aws_instance" "example" {
+ for_each = { for inst in local.instances : inst.local_id => inst }
+
+ instance_type = each.value.instance_type
+ ami = each.value.ami
+}
+```
+
+The `for` expression in our `for_each` argument transforms the list produced
+by `csvdecode` into a map using the `local_id` as a key, which tells
+Packer to use the `local_id` value to track each instance it creates.
+Packer will create and manage the following instance addresses:
+
+- `aws_instance.example["foo1"]`
+- `aws_instance.example["foo2"]`
+- `aws_instance.example["foo3"]`
+- `aws_instance.example["bar1"]`
+
+If you modify a row in the CSV on a subsequent plan, Packer will interpret
+that as an update to the existing object as long as the `local_id` value is
+unchanged. If you add or remove rows from the CSV then Packer will plan to
+create or destroy associated instances as appropriate.
+
+If there is no reasonable value you can use as a unique identifier in your CSV
+then you could instead use
+[the `count` meta-argument](/terraform/docs/configuration/resources#count-multiple-resource-instances-by-count)
+to define an object for each CSV row, with each one identified by its index into
+the list returned by `csvdecode`. However, in that case any future updates to
+the CSV may be disruptive if they change the positions of particular objects in
+the list. We recommend using `for_each` with a unique ID column to make
+behavior more predictable on future changes.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/jsondecode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/jsondecode.mdx
new file mode 100644
index 0000000000..ade3fd2bd1
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/jsondecode.mdx
@@ -0,0 +1,46 @@
+---
+page_title: jsondecode - Functions - Configuration Language
+description: |-
+ The jsondecode function decodes a JSON string into a representation of its
+ value.
+---
+
+# `jsondecode` Function
+
+`jsondecode` interprets a given string as JSON, returning a representation
+of the result of decoding that string.
+
+The JSON encoding is defined in [RFC 7159](https://tools.ietf.org/html/rfc7159).
+
+This function maps JSON values to
+[Packer language values](/packer/docs/templates/hcl_templates/expressions#types-and-values)
+in the following way:
+
+| JSON type | Packer type |
+| --------- | ------------------------------------------------------------ |
+| String | `string` |
+| Number | `number` |
+| Boolean | `bool` |
+| Object | `object(...)` with attribute types determined per this table |
+| Array | `tuple(...)` with element types determined per this table |
+| Null | The Packer language `null` value |
+
+The Packer language automatic type conversion rules mean that you don't
+usually need to worry about exactly what type is produced for a given value,
+and can just use the result in an intuitive way.
+
+## Examples
+
+```shell-session
+> jsondecode("{\"hello\": \"world\"}")
+{
+ "hello" = "world"
+}
+> jsondecode("true")
+true
+```
+
+## Related Functions
+
+- [`jsonencode`](/packer/docs/templates/hcl_templates/functions/encoding/jsonencode) performs the opposite operation, _encoding_
+ a value as JSON.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/jsonencode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/jsonencode.mdx
new file mode 100644
index 0000000000..fb75ee7fa8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/jsonencode.mdx
@@ -0,0 +1,43 @@
+---
+page_title: jsonencode - Functions - Configuration Language
+description: The jsonencode function encodes a given value as a JSON string.
+---
+
+# `jsonencode` Function
+
+`jsonencode` encodes a given value to a string using JSON syntax.
+
+The JSON encoding is defined in [RFC 7159](https://tools.ietf.org/html/rfc7159).
+
+This function maps
+[Packer language values](/packer/docs/templates/hcl_templates/expressions#types-and-values)
+to JSON values in the following way:
+
+| Packer type | JSON type |
+| ------------- | --------- |
+| `string` | String |
+| `number` | Number |
+| `bool` | Bool |
+| `list(...)` | Array |
+| `set(...)` | Array |
+| `tuple(...)` | Array |
+| `map(...)` | Object |
+| `object(...)` | Object |
+| Null value | `null` |
+
+Since the JSON format cannot fully represent all of the Packer language
+types, passing the `jsonencode` result to `jsondecode` will not produce an
+identical value, but the automatic type conversion rules mean that this is
+rarely a problem in practice.
+
+## Examples
+
+```shell-session
+> jsonencode({"hello"="world"})
+{"hello":"world"}
+```
+
+## Related Functions
+
+- [`jsondecode`](/packer/docs/templates/hcl_templates/functions/encoding/jsondecode) performs the opposite operation, _decoding_
+ a JSON string to obtain its represented value.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/urlencode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/urlencode.mdx
new file mode 100644
index 0000000000..a2b8de5cc7
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/urlencode.mdx
@@ -0,0 +1,31 @@
+---
+page_title: urlencode - Functions - Configuration Language
+description: The urlencode function applies URL encoding to a given string.
+---
+
+# `urlencode` Function
+
+`urlencode` applies URL encoding to a given string.
+
+This function identifies characters in the given string that would have a
+special meaning when included as a query string argument in a URL and
+escapes them using
+[RFC 3986 "percent encoding"](https://tools.ietf.org/html/rfc3986#section-2.1).
+
+The exact set of characters escaped may change over time, but the result
+is guaranteed to be interpolatable into a query string argument without
+inadvertently introducing additional delimiters.
+
+If the given string contains non-ASCII characters, these are first encoded as
+UTF-8 and then percent encoding is applied separately to each UTF-8 byte.
+
+## Examples
+
+```shell-session
+> urlencode("Hello World")
+Hello%20World
+> urlencode("☃")
+%E2%98%83
+> "http://example.com/search?q=${urlencode("packer urlencode")}"
+http://example.com/search?q=packer%20urlencode
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/yamldecode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/yamldecode.mdx
new file mode 100644
index 0000000000..ea787ca2c0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/yamldecode.mdx
@@ -0,0 +1,99 @@
+---
+page_title: yamldecode - Functions - Configuration Language
+description: |-
+ The yamldecode function decodes a YAML string into a representation of its
+ value.
+---
+
+# `yamldecode` Function
+
+`yamldecode` parses a string as a subset of YAML, and produces a representation
+of its value.
+
+This function supports a subset of [YAML 1.2](https://yaml.org/spec/1.2/spec.html),
+as described below.
+
+This function maps YAML values to
+[Packer language values](/packer/docs/templates/hcl_templates/expressions#types-and-values)
+in the following way:
+
+| YAML type | Packer type |
+| ------------- | ------------------------------------------------------------------ |
+| `!!str` | `string` |
+| `!!float` | `number` |
+| `!!int` | `number` |
+| `!!bool` | `bool` |
+| `!!map` | `object(...)` with attribute types determined per this table |
+| `!!seq` | `tuple(...)` with element types determined per this table |
+| `!!null` | The Packer language `null` value |
+| `!!timestamp` | `string` in [RFC 3339](https://tools.ietf.org/html/rfc3339) format |
+| `!!binary` | `string` containing base64-encoded representation |
+
+The Packer language automatic type conversion rules mean that you don't
+usually need to worry about exactly what type is produced for a given value,
+and can just use the result in an intuitive way.
+
+Note though that the mapping above is ambiguous -- several different source
+types map to the same target type -- and so round-tripping through `yamldecode`
+and then `yamlencode` cannot produce an identical result.
+
+YAML is a complex language and it supports a number of possibilities that the
+Packer language's type system cannot represent. Therefore this YAML decoder
+supports only a subset of YAML 1.2, with restrictions including the following:
+
+- Although aliases to earlier anchors are supported, cyclic data structures
+ (where a reference to a collection appears inside that collection) are not.
+ If `yamldecode` detects such a structure then it will return an error.
+
+- Only the type tags shown in the above table (or equivalent alternative
+ representations of those same tags) are supported. Any other tags will
+ result in an error.
+
+- Only one YAML document is permitted. If multiple documents are present in
+ the given string then this function will return an error.
+
+## Examples
+
+```shell-session
+> yamldecode("{\"hello\": \"world\"}")
+{
+ "hello" = "world"
+}
+
+> yamldecode("true")
+true
+
+> yamldecode("{a: &foo [1, 2, 3], b: *foo}")
+{
+ "a" = [
+ 1,
+ 2,
+ 3,
+ ]
+ "b" = [
+ 1,
+ 2,
+ 3,
+ ]
+}
+
+> yamldecode("{a: &foo [1, *foo, 3]}")
+
+Error: Error in function call
+
+Call to function "yamldecode" failed: cannot refer to anchor "foo" from inside
+its own definition.
+
+> yamldecode("{a: !not-supported foo}")
+
+Error: Error in function call
+
+Call to function "yamldecode" failed: unsupported tag "!not-supported".
+```
+
+## Related Functions
+
+- [`jsondecode`](/packer/docs/templates/hcl_templates/functions/encoding/jsondecode) is a similar operation using JSON instead
+ of YAML.
+- [`yamlencode`](/packer/docs/templates/hcl_templates/functions/encoding/yamlencode) performs the opposite operation, _encoding_
+ a value as YAML.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/yamlencode.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/yamlencode.mdx
new file mode 100644
index 0000000000..2aa0174714
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/encoding/yamlencode.mdx
@@ -0,0 +1,85 @@
+---
+page_title: yamlencode - Functions - Configuration Language
+description: The yamlencode function encodes a given value as a YAML string.
+---
+
+# `yamlencode` Function
+
+`yamlencode` encodes a given value to a string using
+[YAML 1.2](https://yaml.org/spec/1.2/spec) block syntax.
+
+~> **Warning:** This function is currently **experimental** and its exact
+result format may change in future versions of Packer, based on feedback.
+Do not use `yamldecode` to construct a value for any resource argument where
+changes to the result would be disruptive. To get a consistent string
+representation of a value use [`jsonencode`](/packer/docs/templates/hcl_templates/functions/encoding/jsonencode) instead; its
+results are also valid YAML because YAML is a JSON superset.
+
+
+
+This function maps
+[Packer language values](/packer/docs/templates/hcl_templates/expressions#types-and-values)
+to YAML tags in the following way:
+
+| Packer type | YAML type |
+| ------------- | -------------------- |
+| `string` | `!!str` |
+| `number` | `!!float` or `!!int` |
+| `bool` | `!!bool` |
+| `list(...)` | `!!seq` |
+| `set(...)` | `!!seq` |
+| `tuple(...)` | `!!seq` |
+| `map(...)` | `!!map` |
+| `object(...)` | `!!map` |
+| Null value | `!!null` |
+
+`yamlencode` uses the implied syntax for all of the above types, so it does
+not generate explicit YAML tags.
+
+Because the YAML format cannot fully represent all of the Packer language
+types, passing the `yamlencode` result to `yamldecode` will not produce an
+identical value, but the Packer language automatic type conversion rules
+mean that this is rarely a problem in practice.
+
+## Examples
+
+```shell-session
+> yamlencode({"a":"b", "c":"d"})
+"a": "b"
+"c": "d"
+
+> yamlencode({"foo":[1, 2, 3], "bar": "baz"})
+"bar": "baz"
+"foo":
+- 1
+- 2
+- 3
+
+> yamlencode({"foo":[1, {"a":"b","c":"d"}, 3], "bar": "baz"})
+"bar": "baz"
+"foo":
+- 1
+- "a": "b"
+ "c": "d"
+- 3
+```
+
+`yamlencode` always uses YAML's "block style" for mappings and sequences, unless
+the mapping or sequence is empty. To generate flow-style YAML, use
+[`jsonencode`](/packer/docs/templates/hcl_templates/functions/encoding/jsonencode) instead: YAML flow-style is a superset
+of JSON syntax.
+
+## Related Functions
+
+- [`jsonencode`](/packer/docs/templates/hcl_templates/functions/encoding/jsonencode) is a similar operation using JSON instead
+ of YAML.
+- [`yamldecode`](/packer/docs/templates/hcl_templates/functions/encoding/yamldecode) performs the opposite operation, _decoding_
+ a YAML string to obtain its represented value.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/abspath.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/abspath.mdx
new file mode 100644
index 0000000000..b9c28ca976
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/abspath.mdx
@@ -0,0 +1,24 @@
+---
+page_title: abspath - Functions - Configuration Language
+description: The abspath function converts the argument to an absolute filesystem path.
+---
+
+# `abspath` Function
+
+`abspath` takes a string containing a filesystem path and converts it
+to an absolute path. That is, if the path is not absolute, it will be joined
+with the current working directory.
+
+Referring directly to filesystem paths in resource arguments may cause spurious
+diffs if the same configuration is applied from multiple systems or on
+different host operating systems. We recommend using filesystem paths only for
+transient values, such as the argument to
+[`file`](/packer/docs/templates/hcl_templates/functions/file) (where only the contents are then
+stored).
+
+## Examples
+
+```shell-session
+> abspath(path.root)
+/home/user/some/packer/root
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/basename.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/basename.mdx
new file mode 100644
index 0000000000..70a05e08a0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/basename.mdx
@@ -0,0 +1,41 @@
+---
+page_title: basename - Functions - Configuration Language
+description: |-
+ The basename function removes all except the last portion from a filesystem
+ path.
+---
+
+# `basename` Function
+
+`basename` takes a string containing a filesystem path and removes all except
+the last portion from it.
+
+This function works only with the path string and does not access the
+filesystem itself. It is therefore unable to take into account filesystem
+features such as symlinks.
+
+If the path is empty then the result is `"."`, representing the current
+working directory.
+
+The behavior of this function depends on the host platform. On Windows systems,
+it uses backslash `\` as the path segment separator. On Unix systems, the slash
+`/` is used.
+
+Referring directly to filesystem paths in resource arguments may cause
+spurious diffs if the same configuration is applied from multiple systems or on
+different host operating systems. We recommend using filesystem paths only
+for transient values, such as the argument to [`file`](/packer/docs/templates/hcl_templates/functions/file) (where
+only the contents are then stored) or in `connection` and `provisioner` blocks.
+
+## Examples
+
+```shell-session
+> basename("foo/bar/baz.txt")
+baz.txt
+```
+
+## Related Functions
+
+- [`dirname`](/packer/docs/templates/hcl_templates/functions/file/dirname) returns all of the segments of a filesystem path
+ _except_ the last, discarding the portion that would be returned by
+ `basename`.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/dirname.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/dirname.mdx
new file mode 100644
index 0000000000..348c0363ab
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/dirname.mdx
@@ -0,0 +1,39 @@
+---
+page_title: dirname - Functions - Configuration Language
+description: The dirname function removes the last portion from a filesystem path.
+---
+
+# `dirname` Function
+
+`dirname` takes a string containing a filesystem path and removes the last
+portion from it.
+
+This function works only with the path string and does not access the
+filesystem itself. It is therefore unable to take into account filesystem
+features such as symlinks.
+
+If the path is empty then the result is `"."`, representing the current
+working directory.
+
+The behavior of this function depends on the host platform. On Windows systems,
+it uses backslash `\` as the path segment separator. On Unix systems, the slash
+`/` is used. The result of this function is normalized, so on a Windows system
+any slashes in the given path will be replaced by backslashes before returning.
+
+Referring directly to filesystem paths in resource arguments may cause
+spurious diffs if the same configuration is applied from multiple systems or on
+different host operating systems. We recommend using filesystem paths only
+for transient values, such as the argument to [`file`](/packer/docs/templates/hcl_templates/functions/file) (where
+only the contents are then stored) or in `connection` and `provisioner` blocks.
+
+## Examples
+
+```shell-session
+> dirname("foo/bar/baz.txt")
+foo/bar
+```
+
+## Related Functions
+
+- [`basename`](/packer/docs/templates/hcl_templates/functions/file/basename) returns _only_ the last portion of a filesystem
+ path, discarding the portion that would be returned by `dirname`.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/file.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/file.mdx
new file mode 100644
index 0000000000..6dd36ee3a5
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/file.mdx
@@ -0,0 +1,37 @@
+---
+page_title: file - Functions - Configuration Language
+description: |-
+ The file function reads the contents of the file at the given path and
+ returns them as a string.
+---
+
+# `file` Function
+
+`file` reads the contents of a file at the given path and returns them as
+a string.
+
+```hcl
+file(path)
+```
+
+Strings in the Packer language are sequences of Unicode characters, so
+this function will interpret the file contents as UTF-8 encoded text and
+return the resulting Unicode characters. If the file contains invalid UTF-8
+sequences then this function will produce an error.
+
+This function can be used only with files that already exist on disk
+at the beginning of a Packer run. Functions do not participate in the
+dependency graph, so this function cannot be used with files that are generated
+dynamically during a Packer operation.
+
+## Examples
+
+```shell-session
+> file("${path.folder}/hello.txt")
+Hello World
+```
+
+## Related Functions
+
+- [`fileexists`](/packer/docs/templates/hcl_templates/functions/file/fileexists) determines whether a file exists
+ at a given path.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/fileexists.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/fileexists.mdx
new file mode 100644
index 0000000000..b8b0b3fe2b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/fileexists.mdx
@@ -0,0 +1,35 @@
+---
+page_title: fileexists - Functions - Configuration Language
+description: The fileexists function determines whether a file exists at a given path.
+---
+
+# `fileexists` Function
+
+`fileexists` determines whether a file exists at a given path.
+
+```hcl
+fileexists(path)
+```
+
+Functions are evaluated during configuration parsing rather than at apply time,
+so this function can only be used with files that are already present on disk
+before Packer takes any actions.
+
+This function works only with regular files. If used with a directory, FIFO,
+or other special mode, it will return an error.
+
+## Examples
+
+```shell-session
+> fileexists("${path.folder}/hello.txt")
+true
+```
+
+```hcl
+fileexists("custom-section.sh") ? file("custom-section.sh") : local.default_content
+```
+
+## Related Functions
+
+- [`file`](/packer/docs/templates/hcl_templates/functions/file/file) reads the contents
+ of a file at a given path.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/fileset.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/fileset.mdx
new file mode 100644
index 0000000000..e60dd126d3
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/fileset.mdx
@@ -0,0 +1,102 @@
+---
+page_title: fileset - Functions - Configuration Language
+description: The fileset function enumerates a set of regular file names given a pattern.
+---
+
+# `fileset` Function
+
+`fileset` enumerates a set of regular file names given a path and pattern.
+The path is automatically removed from the resulting set of file names and any
+result still containing path separators always returns forward slash (`/`) as
+the path separator for cross-system compatibility.
+
+```hcl
+fileset(path, pattern)
+```
+
+Supported pattern matches:
+
+- `*` - matches any sequence of non-separator characters
+- `**` - matches any sequence of characters, including separator characters
+- `?` - matches any single non-separator character
+- `{alternative1,...}` - matches a sequence of characters if one of the comma-separated alternatives matches
+- `[CLASS]` - matches any single non-separator character inside a class of characters (see below)
+- `[^CLASS]` - matches any single non-separator character outside a class of characters (see below)
+
+Character classes support the following:
+
+- `[abc]` - matches any single character within the set
+- `[a-z]` - matches any single character within the range
+
+Functions are evaluated during configuration parsing rather than at apply time,
+so this function can only be used with files that are already present on disk
+before Packer takes any actions.
+
+## Examples
+
+```shell-session
+> tree pkr-consul
+pkr-consul
+├── build-linux.pkr.hcl
+└── linux
+ ├── files
+ │ ├── hello.txt
+ │ └── world.txt
+ └── scripts
+ ├── script-1-install.sh
+ └── script-2-setup.sh
+
+3 directories, 5 files
+
+> fileset(".", "*") | packer console pkr-consul
+[
+ "build-linux.pkr.hcl",
+]
+
+> echo 'fileset(".", "linux/scripts/*")' | packer console pkr-consul
+[
+ "linux/scripts/script-1-install.sh",
+ "linux/scripts/script-2-setup.sh",
+]
+
+> echo 'fileset("linux", "files/{hello,world}.txt")' | packer console pkr-consul
+[
+ "files/hello.txt",
+ "files/world.txt",
+]
+
+> echo 'fileset("./linux/files", "*")' | packer console pkr-consul
+[
+ "hello.txt",
+ "world.txt",
+]
+
+> echo 'fileset("./linux", "**")' | packer console pkr-consul
+[
+ "files/hello.txt",
+ "files/world.txt",
+ "scripts/script-1-install.sh",
+ "scripts/script-2-setup.sh",
+]
+```
+
+A common use of `fileset` is to set the `scripts` field of a `shell`
+provisioner with a list of matching scripts to run.
+
+```hcl
+build {
+ sources = [
+ "source.amazon-ebs.linux",
+ ]
+
+ provisioner "shell" {
+ scripts = fileset(".", "linux/scripts/*")
+ }
+```
+
+List of provisioners with a `scripts` field:
+
+- [`shell`](/packer/docs/provisioners/shell)
+- [`powershell`](/packer/docs/provisioners/powershell)
+- [`shell-local`](/packer/docs/provisioners/shell-local)
+- [`windows-shell`](/packer/docs/provisioners/windows-shell)
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/pathexpand.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/pathexpand.mdx
new file mode 100644
index 0000000000..974716c8f6
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/pathexpand.mdx
@@ -0,0 +1,54 @@
+---
+page_title: pathexpand - Functions - Configuration Language
+description: |-
+ The pathexpand function expands a leading ~ character to the current user's
+ home directory.
+---
+
+# `pathexpand` Function
+
+`pathexpand` takes a filesystem path that might begin with a `~` segment,
+and if so it replaces that segment with the current user's home directory
+path.
+
+This function works only with the path string and does not access the
+filesystem itself. It is therefore unable to take into account filesystem
+features such as symlinks.
+
+If the leading segment in the path is not `~` then the given path is returned
+unmodified.
+
+Using this function in resource arguments will cause spurious diffs if the
+same configuration is run by multiple users with different home directory
+paths, or used on different host operating systems. We recommend using this
+function only for transient values, such as in `connection` and `provisioner`
+blocks to locate SSH keys, etc.
+
+The rules for determining the "home directory" for the current user vary
+depending on host operating system.
+
+**For Unix systems**, the following sources are consulted, in order of preference:
+
+- The `HOME` environment variable.
+- The result of running `getent passwd` followed by the Packer process uid.
+- The result of running `cd && pwd` in `sh`.
+
+**For Windows systems**, there is not really the concept of a home directory
+in the same sense as on Unix, but the following sources are consulted in
+order of preference:
+
+- The `HOME` environment variable.
+- The `HOMEDRIVE` and `HOMEPATH` environment variables, if both are set.
+- The `USERPROFILE` environment variable.
+
+The exact rules employed for each operating system may change in future
+releases of Packer.
+
+## Examples
+
+```shell-session
+> pathexpand("~/.ssh/id_rsa")
+/home/steve/.ssh/id_rsa
+> pathexpand("/etc/resolv.conf")
+/etc/resolv.conf
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/templatefile.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/templatefile.mdx
new file mode 100644
index 0000000000..68cc8cf470
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/file/templatefile.mdx
@@ -0,0 +1,138 @@
+---
+page_title: templatefile - Functions - Configuration Language
+description: |-
+ The templatefile function reads the file at the given path and renders its
+ content as a template using a supplied set of template variables.
+---
+
+# `templatefile` Function
+
+-> _Recommendation:_ we recommend using the `.pkrtpl.hcl` file extension when
+using the `templatefile` function. Template files _are_ hcl treated as files but
+also templates and therefore have slightly different set of features
+than the ones offered in a `.pkr.hcl` Packer template. While you are not
+required to use this extension, doing so will enable syntax highlighters to
+properly understand your file.
+
+`templatefile` reads the file at the given path and renders its content as a
+template using a supplied set of template variables.
+
+```hcl
+templatefile(path, vars)
+```
+
+The template syntax is the same as for string templates in the main HCL2
+language, including interpolation sequences delimited with `${ ... }`. This
+function just allows longer template sequences to be factored out into a
+separate file for readability.
+
+The "vars" argument must be a map. Within the template file, each of the keys in
+the map is available as a variable for interpolation. The template may also use
+any other function available in Packer, except that recursive calls to
+templatefile are not permitted. Variable names must each start with a letter,
+followed by zero or more letters, digits, or underscores.
+
+Strings in HCL2 are sequences of Unicode characters, so this function will
+interpret the file contents as UTF-8 encoded text and return the resulting
+Unicode characters. If the file contains invalid UTF-8 sequences then this
+function will produce an error.
+
+This function can be used only with files that already exist on disk at the
+beginning of a run.
+
+## Examples
+
+### Lists
+
+Given a template file backends.tpl with the following content:
+
+```hcl
+%{ for addr in ip_addrs ~}
+backend ${addr}:${port}
+%{ endfor ~}
+```
+
+The templatefile function renders the template:
+
+```shell-session
+> templatefile("${path.root}/backends.tmpl", { port = 8080, ip_addrs = ["10.0.0.1", "10.0.0.2"] })
+backend 10.0.0.1:8080
+backend 10.0.0.2:8080
+```
+
+### Maps
+
+Given a template file config.tmpl with the following content:
+
+```hcl
+%{ for config_key, config_value in config }
+set ${config_key} = ${config_value}
+%{ endfor ~}
+```
+
+The templatefile function renders the template:
+
+```shell-session
+> templatefile(
+ "${path.root}/config.tmpl",
+ {
+ config = {
+ "x" = "y"
+ "foo" = "bar"
+ "key" = "value"
+ }
+ }
+ )
+set foo = bar
+set key = value
+set x = y
+```
+
+### Generating JSON or YAML from a template
+
+If the string you want to generate will be in JSON or YAML syntax, it's often
+tricky and tedious to write a template that will generate valid JSON or YAML
+that will be interpreted correctly when using lots of individual interpolation
+sequences and directives.
+
+Instead, you can write a template that consists only of a single interpolated
+call to either jsonencode or yamlencode, specifying the value to encode using
+normal expression syntax as in the following examples:
+
+```hcl
+${jsonencode({
+ "backends": [for addr in ip_addrs : "${addr}:${port}"],
+})}
+${yamlencode({
+ "backends": [for addr in ip_addrs : "${addr}:${port}"],
+})}
+```
+
+Given the same input as the `backends.tmpl` example in the previous section,
+this will produce a valid JSON or YAML representation of the given data
+structure, without the need to manually handle escaping or delimiters. In the
+latest examples above, the repetition based on elements of ip_addrs is achieved
+by using a for expression rather than by using template directives.
+
+```
+{"backends":["10.0.0.1:8080","10.0.0.2:8080"]}
+```
+
+If the resulting template is small, you can choose instead to write jsonencode or yamlencode calls inline in your main configuration files, and avoid creating separate template files at all:
+
+```hcl
+locals {
+ backend_config_json = jsonencode({
+ "backends": [for addr in ip_addrs : "${addr}:${port}"],
+ })
+}
+```
+
+For more information, see the main documentation for jsonencode and yamlencode.
+
+## Related Functions
+
+- [`file`](/packer/docs/templates/hcl_templates/functions/file/file) reads the contents
+ of a file at a given path.
+- [`fileexists`](/packer/docs/templates/hcl_templates/functions/file/fileexists)
+ determines whether a file exists at a given path.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/index.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/index.mdx
new file mode 100644
index 0000000000..0a9ee2a9ee
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/index.mdx
@@ -0,0 +1,26 @@
+---
+page_title: Functions - Configuration Language
+description: |-
+ The HCL language has a number of built-in functions that can be called
+ from within expressions to transform and combine values.
+---
+
+# Built-in Functions
+
+`@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
+syntax for function calls is a function name followed by comma-separated
+arguments in parentheses:
+
+```hcl
+max(5, 12, 9)
+```
+
+For information on invoking functions in string literals, refer to the
+[String Literals](https://developer.hashicorp.com/packer/docs/templates/hcl_templates/expressions#string-literals) section
+in the HCL2 expressions documentation.
+
+The HCL language does not support user-defined functions, and so only
+the functions built in to the language are available for use. The documentation includes all of the available built-in functions.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrhost.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrhost.mdx
new file mode 100644
index 0000000000..77c5679990
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrhost.mdx
@@ -0,0 +1,49 @@
+---
+page_title: cidrhost - Functions - Configuration Language
+description: |-
+ The cidrhost function calculates a full host IP address within a given
+ IP network address prefix.
+---
+
+# `cidrhost` Function
+
+`cidrhost` calculates a full host IP address for a given host number within
+a given IP network address prefix.
+
+```hcl
+cidrhost(prefix, hostnum)
+```
+
+`prefix` must be given in CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+`hostnum` is a whole number that can be represented as a binary integer with
+no more than the number of digits remaining in the address after the given
+prefix. For more details on how this function interprets CIDR prefixes and
+populates host numbers, see the worked example for
+[`cidrsubnet`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrsubnet).
+
+Conventionally host number zero is used to represent the address of the
+network itself and the host number that would fill all the host bits with
+binary 1 represents the network's broadcast address. These numbers should
+generally not be used to identify individual hosts except in unusual
+situations, such as point-to-point links.
+
+This function accepts both IPv6 and IPv4 prefixes, and the result always uses
+the same addressing scheme as the given prefix.
+
+## Examples
+
+```shell-session
+> cidrhost("10.12.127.0/20", 16)
+10.12.112.16
+> cidrhost("10.12.127.0/20", 268)
+10.12.113.12
+> cidrhost("fd00:fd12:3456:7890:00a2::/72", 34)
+fd00:fd12:3456:7890::22
+```
+
+## Related Functions
+
+- [`cidrsubnet`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrsubnet) calculates a subnet address under a given
+ network address prefix.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrnetmask.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrnetmask.mdx
new file mode 100644
index 0000000000..fbb43eec47
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrnetmask.mdx
@@ -0,0 +1,31 @@
+---
+page_title: cidrnetmask - Functions - Configuration Language
+description: |-
+ The cidrnetmask function converts an IPv4 address prefix given in CIDR
+ notation into a subnet mask address.
+---
+
+# `cidrnetmask` Function
+
+`cidrnetmask` converts an IPv4 address prefix given in CIDR notation into
+a subnet mask address.
+
+```hcl
+cidrnetmask(prefix)
+```
+
+`prefix` must be given in IPv4 CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+The result is a subnet address formatted in the conventional dotted-decimal
+IPv4 address syntax, as expected by some software.
+
+CIDR notation is the only valid notation for IPv6 addresses, so `cidrnetmask`
+produces an error if given an IPv6 address.
+
+## Examples
+
+```shell-session
+> cidrnetmask("172.16.0.0/12")
+255.240.0.0
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrsubnet.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrsubnet.mdx
new file mode 100644
index 0000000000..fbe916df75
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrsubnet.mdx
@@ -0,0 +1,166 @@
+---
+page_title: cidrsubnet - Functions - Configuration Language
+description: |-
+ The cidrsubnet function calculates a subnet address within a given IP network
+ address prefix.
+---
+
+# `cidrsubnet` Function
+
+`cidrsubnet` calculates a subnet address within given IP network address prefix.
+
+```hcl
+cidrsubnet(prefix, newbits, netnum)
+```
+
+`prefix` must be given in CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+`newbits` is the number of additional bits with which to extend the prefix.
+For example, if given a prefix ending in `/16` and a `newbits` value of
+`4`, the resulting subnet address will have length `/20`.
+
+`netnum` is a whole number that can be represented as a binary integer with
+no more than `newbits` binary digits, which will be used to populate the
+additional bits added to the prefix.
+
+This function accepts both IPv6 and IPv4 prefixes, and the result always uses
+the same addressing scheme as the given prefix.
+
+Unlike the related function [`cidrsubnets`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrsubnets), `cidrsubnet`
+allows you to give a specific network number to use. `cidrsubnets` can allocate
+multiple network addresses at once, but numbers them automatically starting
+with zero.
+
+## Examples
+
+```shell-session
+> cidrsubnet("172.16.0.0/12", 4, 2)
+172.18.0.0/16
+> cidrsubnet("10.1.2.0/24", 4, 15)
+10.1.2.240/28
+> cidrsubnet("fd00:fd12:3456:7890::/56", 16, 162)
+fd00:fd12:3456:7800:a200::/72
+```
+
+## Netmasks and Subnets
+
+Using `cidrsubnet` requires familiarity with some network addressing concepts.
+
+The most important idea is that an IP address (whether IPv4 or IPv6) is
+fundamentally constructed from binary digits, even though we conventionally
+represent it as either four decimal octets (for IPv4) or a sequence of 16-bit
+hexadecimal numbers (for IPv6).
+
+Taking our example above of `cidrsubnet("10.1.2.0/24", 4, 15)`, the function
+will first convert the given IP address string into an equivalent binary
+representation:
+
+```text
+ 10 . 1 . 2 . 0
+00001010 00000001 00000010 | 00000000
+ network | host
+```
+
+The `/24` at the end of the prefix string specifies that the first 24
+bits -- or, the first three octets -- of the address identify the network
+while the remaining bits (32 - 24 = 8 bits in this case) identify hosts
+within the network.
+
+The CLI tool [`ipcalc`](https://gitlab.com/ipcalc/ipcalc) is useful for
+visualizing CIDR prefixes as binary numbers. We can confirm the conversion
+above by providing the same prefix string to `ipcalc`:
+
+```shell-session
+$ ipcalc 10.1.2.0/24
+Address: 10.1.2.0 00001010.00000001.00000010. 00000000
+Netmask: 255.255.255.0 = 24 11111111.11111111.11111111. 00000000
+Wildcard: 0.0.0.255 00000000.00000000.00000000. 11111111
+=>
+Network: 10.1.2.0/24 00001010.00000001.00000010. 00000000
+HostMin: 10.1.2.1 00001010.00000001.00000010. 00000001
+HostMax: 10.1.2.254 00001010.00000001.00000010. 11111110
+Broadcast: 10.1.2.255 00001010.00000001.00000010. 11111111
+Hosts/Net: 254 Class A, Private Internet
+```
+
+This gives us some additional information but also confirms (using a slightly
+different notation) the conversion from decimal to binary and shows the range
+of possible host addresses in this network.
+
+While [`cidrhost`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrhost) allows calculating single host IP addresses,
+`cidrsubnet` on the other hand creates a new network prefix _within_ the given
+network prefix. In other words, it creates a subnet.
+
+When we call `cidrsubnet` we also pass two additional arguments: `newbits` and
+`netnum`. `newbits` decides how much longer the resulting prefix will be in
+bits; in our example here we specified `4`, which means that the resulting
+subnet will have a prefix length of 24 + 4 = 28 bits. We can imagine these
+bits breaking down as follows:
+
+```text
+ 10 . 1 . 2 . ? 0
+00001010 00000001 00000010 | XXXX | 0000
+ parent network | netnum | host
+```
+
+Four of the eight bits that were originally the "host number" are now being
+repurposed as the subnet number. The network prefix no longer falls on an
+exact octet boundary, so in effect we are now splitting the last decimal number
+in the IP address into two parts, using half of it to represent the subnet
+number and the other half to represent the host number.
+
+The `netnum` argument then decides what number value to encode into those
+four new subnet bits. In our current example we passed `15`, which is
+represented in binary as `1111`, allowing us to fill in the `XXXX` segment
+in the above:
+
+```text
+ 10 . 1 . 2 . 15 0
+00001010 00000001 00000010 | 1111 | 0000
+ parent network | netnum | host
+```
+
+To convert this back into normal decimal notation we need to recombine the
+two portions of the final octet. Converting `11110000` from binary to decimal
+gives 240, which can then be combined with our new prefix length of 28 to
+produce the result `10.1.2.240/28`. Again we can pass this prefix string to
+`ipcalc` to visualize it:
+
+```shell-session
+$ ipcalc 10.1.2.240/28
+Address: 10.1.2.240 00001010.00000001.00000010.1111 0000
+Netmask: 255.255.255.240 = 28 11111111.11111111.11111111.1111 0000
+Wildcard: 0.0.0.15 00000000.00000000.00000000.0000 1111
+=>
+Network: 10.1.2.240/28 00001010.00000001.00000010.1111 0000
+HostMin: 10.1.2.241 00001010.00000001.00000010.1111 0001
+HostMax: 10.1.2.254 00001010.00000001.00000010.1111 1110
+Broadcast: 10.1.2.255 00001010.00000001.00000010.1111 1111
+Hosts/Net: 14 Class A, Private Internet
+```
+
+The new subnet has four bits available for host numbering, which means
+that there are 14 host addresses available for assignment once we subtract
+the network's own address and the broadcast address. You can thus use
+[`cidrhost`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrhost) function to calculate those host addresses by
+providing it a value between 1 and 14:
+
+```shell-session
+> cidrhost("10.1.2.240/28", 1)
+10.1.2.241
+> cidrhost("10.1.2.240/28", 14)
+10.1.2.254
+```
+
+For more information on CIDR notation and subnetting, see
+[Classless Inter-domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).
+
+## Related Functions
+
+- [`cidrhost`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrhost) calculates the IP address for a single host
+ within a given network address prefix.
+- [`cidrnetmask`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrnetmask) converts an IPv4 network prefix in CIDR
+ notation into netmask notation.
+- [`cidrsubnets`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrsubnets) can allocate multiple consecutive
+ addresses under a prefix at once, numbering them automatically.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrsubnets.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrsubnets.mdx
new file mode 100644
index 0000000000..faac15f8b8
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/ipnet/cidrsubnets.mdx
@@ -0,0 +1,93 @@
+---
+page_title: cidrsubnets - Functions - Configuration Language
+description: |-
+ The cidrsubnets function calculates a sequence of consecutive IP address
+ ranges within a particular CIDR prefix.
+---
+
+# `cidrsubnets` Function
+
+`cidrsubnets` calculates a sequence of consecutive IP address ranges within
+a particular CIDR prefix.
+
+```hcl
+cidrsubnets(prefix, newbits...)
+```
+
+`prefix` must be given in CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+The remaining arguments, indicated as `newbits` above, each specify the number
+of additional network prefix bits for one returned address range. The return
+value is therefore a list with one element per `newbits` argument, each
+a string containing an address range in CIDR notation.
+
+For more information on IP addressing concepts, see the documentation for the
+related function [`cidrsubnet`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrsubnet). `cidrsubnet` calculates
+a single subnet address within a prefix while allowing you to specify its
+subnet number, while `cidrsubnets` can calculate many at once, potentially of
+different sizes, and assigns subnet numbers automatically.
+
+When using this function to partition an address space as part of a network
+address plan, you must not change any of the existing arguments once network
+addresses have been assigned to real infrastructure, or else later address
+assignments will be invalidated. However, you _can_ append new arguments to
+existing calls safely, as long as there is sufficient address space available.
+
+This function accepts both IPv6 and IPv4 prefixes, and the result always uses
+the same addressing scheme as the given prefix.
+
+## Examples
+
+```shell-session
+> cidrsubnets("10.1.0.0/16", 4, 4, 8, 4)
+[
+ "10.1.0.0/20",
+ "10.1.16.0/20",
+ "10.1.32.0/24",
+ "10.1.48.0/20",
+]
+
+> cidrsubnets("fd00:fd12:3456:7890::/56", 16, 16, 16, 32)
+[
+ "fd00:fd12:3456:7800::/72",
+ "fd00:fd12:3456:7800:100::/72",
+ "fd00:fd12:3456:7800:200::/72",
+ "fd00:fd12:3456:7800:300::/88",
+]
+```
+
+You can use nested `cidrsubnets` calls with
+[`for` expressions](/packer/docs/templates/hcl_templates/expressions#for-expressions)
+to concisely allocate groups of network address blocks:
+
+```shell-session
+> [for cidr_block in cidrsubnets("10.0.0.0/8", 8, 8, 8, 8) : cidrsubnets(cidr_block, 4, 4)]
+[
+ [
+ "10.0.0.0/20",
+ "10.0.16.0/20",
+ ],
+ [
+ "10.1.0.0/20",
+ "10.1.16.0/20",
+ ],
+ [
+ "10.2.0.0/20",
+ "10.2.16.0/20",
+ ],
+ [
+ "10.3.0.0/20",
+ "10.3.16.0/20",
+ ],
+]
+```
+
+## Related Functions
+
+- [`cidrhost`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrhost) calculates the IP address for a single host
+ within a given network address prefix.
+- [`cidrnetmask`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrnetmask) converts an IPv4 network prefix in CIDR
+ notation into netmask notation.
+- [`cidrsubnet`](/packer/docs/templates/hcl_templates/functions/ipnet/cidrsubnet) calculates a single subnet address, allowing
+ you to specify its network number.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/abs.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/abs.mdx
new file mode 100644
index 0000000000..023b415572
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/abs.mdx
@@ -0,0 +1,21 @@
+---
+page_title: abs - Functions - Configuration Language
+description: The abs function returns the absolute value of the given number.
+---
+
+# `abs` Function
+
+`abs` returns the absolute value of the given number. In other words, if the
+number is zero or positive then it is returned as-is, but if it is negative
+then it is multiplied by -1 to make it positive before returning it.
+
+## Examples
+
+```shell-session
+> abs(23)
+23
+> abs(0)
+0
+> abs(-12.4)
+12.4
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/ceil.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/ceil.mdx
new file mode 100644
index 0000000000..2c3e9a70f1
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/ceil.mdx
@@ -0,0 +1,25 @@
+---
+page_title: ceil - Functions - Configuration Language
+description: |-
+ The ceil function returns the closest whole number greater than or equal to
+ the given value.
+---
+
+# `ceil` Function
+
+`ceil` returns the closest whole number that is greater than or equal to the
+given value, which may be a fraction.
+
+## Examples
+
+```shell-session
+> ceil(5)
+5
+> ceil(5.1)
+6
+```
+
+## Related Functions
+
+- [`floor`](/packer/docs/templates/hcl_templates/functions/numeric/floor), which rounds to the nearest whole number _less than_
+ or equal.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/floor.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/floor.mdx
new file mode 100644
index 0000000000..66faf73f20
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/floor.mdx
@@ -0,0 +1,25 @@
+---
+page_title: floor - Functions - Configuration Language
+description: |-
+ The floor function returns the closest whole number less than or equal to
+ the given value.
+---
+
+# `floor` Function
+
+`floor` returns the closest whole number that is less than or equal to the
+given value, which may be a fraction.
+
+## Examples
+
+```shell-session
+> floor(5)
+5
+> floor(4.9)
+4
+```
+
+## Related Functions
+
+- [`ceil`](/packer/docs/templates/hcl_templates/functions/numeric/ceil), which rounds to the nearest whole number _greater than_
+ or equal.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/log.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/log.mdx
new file mode 100644
index 0000000000..c63952e05a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/log.mdx
@@ -0,0 +1,33 @@
+---
+page_title: log - Functions - Configuration Language
+description: The log function returns the logarithm of a given number in a given base.
+---
+
+# `log` Function
+
+`log` returns the logarithm of a given number in a given base.
+
+```hcl
+log(number, base)
+```
+
+## Examples
+
+```shell-session
+> log(50, 10)
+1.6989700043360185
+> log(16, 2)
+4
+```
+
+`log` and `ceil` can be used together to find the minimum number of binary
+digits required to represent a given number of distinct values:
+
+```shell-session
+> ceil(log(15, 2))
+4
+> ceil(log(16, 2))
+4
+> ceil(log(17, 2))
+5
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/max.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/max.mdx
new file mode 100644
index 0000000000..36f8ac2554
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/max.mdx
@@ -0,0 +1,27 @@
+---
+page_title: max - Functions - Configuration Language
+description: The max function takes one or more numbers and returns the greatest number.
+---
+
+# `max` Function
+
+`max` takes one or more numbers and returns the greatest number from the set.
+
+## Examples
+
+```shell-session
+> max(12, 54, 3)
+54
+```
+
+If the numbers are in a list or set value, use `...` to expand the collection
+to individual arguments:
+
+```shell-session
+> max([12, 54, 3]...)
+54
+```
+
+## Related Functions
+
+- [`min`](/packer/docs/templates/hcl_templates/functions/numeric/min), which returns the _smallest_ number from a set.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/min.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/min.mdx
new file mode 100644
index 0000000000..64e697143a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/min.mdx
@@ -0,0 +1,27 @@
+---
+page_title: min - Functions - Configuration Language
+description: The min function takes one or more numbers and returns the smallest number.
+---
+
+# `min` Function
+
+`min` takes one or more numbers and returns the smallest number from the set.
+
+## Examples
+
+```shell-session
+> min(12, 54, 3)
+3
+```
+
+If the numbers are in a list or set value, use `...` to expand the collection
+to individual arguments:
+
+```shell-session
+> min([12, 54, 3]...)
+3
+```
+
+## Related Functions
+
+- [`max`](/packer/docs/templates/hcl_templates/functions/numeric/max), which returns the _greatest_ number from a set.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/parseint.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/parseint.mdx
new file mode 100644
index 0000000000..3b8ac24118
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/parseint.mdx
@@ -0,0 +1,50 @@
+---
+page_title: parseint - Functions - Configuration Language
+description: >-
+ The parseint function parses the given string as a representation of an
+ integer.
+---
+
+# `parseint` Function
+
+`parseint` parses the given string as a representation of an integer in
+the specified base and returns the resulting number. The base must be between 2
+and 62 inclusive.
+
+All bases use the arabic numerals 0 through 9 first. Bases between 11 and 36
+inclusive use case-insensitive latin letters to represent higher unit values.
+Bases 37 and higher use lowercase latin letters and then uppercase latin
+letters.
+
+If the given string contains any non-digit characters or digit characters that
+are too large for the given base then `parseint` will produce an error.
+
+## Examples
+
+```shell-session
+> parseint("100", 10)
+100
+
+> parseint("FF", 16)
+255
+
+> parseint("-10", 16)
+-16
+
+> parseint("1011111011101111", 2)
+48879
+
+> parseint("aA", 62)
+656
+
+> parseint("12", 2)
+
+Error: Invalid function argument
+
+Invalid value for "number" parameter: cannot parse "12" as a base 2 integer.
+```
+
+## Related Functions
+
+- [`format`](/packer/docs/templates/hcl_templates/functions/string/format) can format numbers and other values into strings,
+ with optional zero padding, alignment, etc.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/pow.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/pow.mdx
new file mode 100644
index 0000000000..e8702cba97
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/pow.mdx
@@ -0,0 +1,17 @@
+---
+page_title: pow - Functions - Configuration Language
+description: The pow function raises a number to a power.
+---
+
+# `pow` Function
+
+`pow` calculates an exponent, by raising its first argument to the power of the second argument.
+
+## Examples
+
+```shell-session
+> pow(3, 2)
+9
+> pow(4, 0)
+1
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/signum.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/signum.mdx
new file mode 100644
index 0000000000..1caf698838
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/numeric/signum.mdx
@@ -0,0 +1,20 @@
+---
+page_title: signum - Functions - Configuration Language
+description: The signum function determines the sign of a number.
+---
+
+# `signum` Function
+
+`signum` determines the sign of a number, returning a number between -1 and
+1 to represent the sign.
+
+## Examples
+
+```shell-session
+> signum(-13)
+-1
+> signum(0)
+0
+> signum(344)
+1
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/chomp.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/chomp.mdx
new file mode 100644
index 0000000000..9586ab280e
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/chomp.mdx
@@ -0,0 +1,27 @@
+---
+page_title: chomp - Functions - Configuration Language
+description: The chomp function removes newline characters at the end of a string.
+---
+
+# `chomp` Function
+
+`chomp` removes newline characters at the end of a string.
+
+This can be useful if, for example, the string was read from a file that has
+a newline character at the end.
+
+## Examples
+
+```shell-session
+> chomp("hello\n")
+hello
+> chomp("hello\r\n")
+hello
+> chomp("hello\n\n")
+hello
+```
+
+## Related Functions
+
+- [`trimspace`](/packer/docs/templates/hcl_templates/functions/string/trimspace), which removes all types of whitespace from
+ both the start and the end of a string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/format.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/format.mdx
new file mode 100644
index 0000000000..7ac645ffed
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/format.mdx
@@ -0,0 +1,119 @@
+---
+page_title: format - Functions - Configuration Language
+description: |-
+ The format function produces a string by formatting a number of other values
+ according to a specification string.
+---
+
+# `format` Function
+
+`format` produces a string by formatting a number of other values according
+to a specification string. It is similar to the `printf` function in C, and
+other similar functions in other programming languages.
+
+```hcl
+format(spec, values...)
+```
+
+## Examples
+
+```shell-session
+> format("Hello, %s!", "Ander")
+Hello, Ander!
+> format("There are %d lights", 4)
+There are 4 lights
+```
+
+Simple format verbs like `%s` and `%d` behave similarly to template
+interpolation syntax, which is often more readable:
+
+```shell-session
+> format("Hello, %s!", var.name)
+Hello, Valentina!
+> "Hello, ${var.name}!"
+Hello, Valentina!
+```
+
+The `format` function is therefore more useful when you use more complex format
+specifications, as described in the following section.
+
+## Specification Syntax
+
+The specification is a string that includes formatting verbs that are introduced
+with the `%` character. The function call must then have one additional argument
+for each verb sequence in the specification. The verbs are matched with
+consecutive arguments and formatted as directed, as long as each given argument
+is convertible to the type required by the format verb.
+
+The specification may contain the following verbs:
+
+| Verb | Result |
+| ----- | ----------------------------------------------------------------------------------------- |
+| `%%` | Literal percent sign, consuming no value. |
+| `%v` | Default formatting based on the value type, as described below. |
+| `%#v` | JSON serialization of the value, as with `jsonencode`. |
+| `%t` | Convert to boolean and produce `true` or `false`. |
+| `%b` | Convert to integer number and produce binary representation. |
+| `%d` | Convert to integer number and produce decimal representation. |
+| `%o` | Convert to integer number and produce octal representation. |
+| `%x` | Convert to integer number and produce hexadecimal representation with lowercase letters. |
+| `%X` | Like `%x`, but use uppercase letters. |
+| `%e` | Convert to number and produce scientific notation, like `-1.234456e+78`. |
+| `%E` | Like `%e`, but use an uppercase `E` to introduce the exponent. |
+| `%f` | Convert to number and produce decimal fraction notation with no exponent, like `123.456`. |
+| `%g` | Like `%e` for large exponents or like `%f` otherwise. |
+| `%G` | Like `%E` for large exponents or like `%f` otherwise. |
+| `%s` | Convert to string and insert the string's characters. |
+| `%q` | Convert to string and produce a JSON quoted string representation. |
+
+When `%v` is used, one of the following format verbs is chosen based on the value type:
+
+| Type | Verb |
+| --------- | ----- |
+| `string` | `%s` |
+| `number` | `%g` |
+| `bool` | `%t` |
+| any other | `%#v` |
+
+Null values produce the string `null` if formatted with `%v` or `%#v`, and
+cause an error for other verbs.
+
+A width modifier can be included with an optional decimal number immediately
+preceding the verb letter, to specify how many characters will be used to
+represent the value. Precision can be specified after the (optional) width
+with a period (`.`) followed by a decimal number. If width or precision are
+omitted then default values are selected based on the given value. For example:
+
+| Sequence | Result |
+| -------- | ---------------------------- |
+| `%f` | Default width and precision. |
+| `%9f` | Width 9, default precision. |
+| `%.2f` | Default width, precision 2. |
+| `%9.2f` | Width 9, precision 2. |
+
+The following additional symbols can be used immediately after the `%` symbol
+to set additional flags:
+
+| Symbol | Result |
+| ------ | -------------------------------------------------------------- |
+| space | Leave a space where the sign would be if a number is positive. |
+| `+` | Show the sign of a number even if it is positive. |
+| `-` | Pad the width with spaces on the left rather than the right. |
+| `0` | Pad the width with leading zeros rather than spaces. |
+
+By default, `%` sequences consume successive arguments starting with the first.
+Introducing a `[n]` sequence immediately before the verb letter, where `n` is a
+decimal integer, explicitly chooses a particular value argument by its
+one-based index. Subsequent calls without an explicit index will then proceed
+with `n`+1, `n`+2, etc.
+
+The function produces an error if the format string requests an impossible
+conversion or access more arguments than are given. An error is produced also
+for an unsupported format verb.
+
+## Related Functions
+
+- [`formatdate`](/packer/docs/templates/hcl_templates/functions/datetime/formatdate) is a specialized formatting function for
+ human-readable timestamps.
+- [`formatlist`](/packer/docs/templates/hcl_templates/functions/string/formatlist) uses the same specification syntax to
+ produce a list of strings.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/formatlist.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/formatlist.mdx
new file mode 100644
index 0000000000..6d110ae206
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/formatlist.mdx
@@ -0,0 +1,49 @@
+---
+page_title: formatlist - Functions - Configuration Language
+description: |-
+ The formatlist function produces a list of strings by formatting a number of
+ other values according to a specification string.
+---
+
+# `formatlist` Function
+
+`formatlist` produces a list of strings by formatting a number of other
+values according to a specification string.
+
+```hcl
+formatlist(spec, values...)
+```
+
+The specification string uses
+[the same syntax as `format`](/packer/docs/templates/hcl_templates/functions/string/format#specification-syntax).
+
+The given values can be a mixture of list and non-list arguments. Any given
+lists must be the same length, which decides the length of the resulting list.
+
+The list arguments are iterated together in order by index, while the non-list
+arguments are used repeatedly for each iteration. The format string is evaluated
+once per element of the list arguments.
+
+## Examples
+
+```shell-session
+> formatlist("Hello, %s!", ["Valentina", "Ander", "Olivia", "Sam"])
+[
+ "Hello, Valentina!",
+ "Hello, Ander!",
+ "Hello, Olivia!",
+ "Hello, Sam!",
+]
+> formatlist("%s, %s!", "Salutations", ["Valentina", "Ander", "Olivia", "Sam"])
+[
+ "Salutations, Valentina!",
+ "Salutations, Ander!",
+ "Salutations, Olivia!",
+ "Salutations, Sam!",
+]
+```
+
+## Related Functions
+
+- [`format`](/packer/docs/templates/hcl_templates/functions/string/format) defines the specification syntax used by this
+ function and produces a single string as its result.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/indent.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/indent.mdx
new file mode 100644
index 0000000000..158a22a497
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/indent.mdx
@@ -0,0 +1,31 @@
+---
+page_title: indent - Functions - Configuration Language
+description: |-
+ The indent function adds a number of spaces to the beginnings of all but the
+ first line of a given multi-line string.
+---
+
+# `indent` Function
+
+`indent` adds a given number of spaces to the beginnings of all but the first
+line in a given multi-line string.
+
+```hcl
+indent(num_spaces, string)
+```
+
+## Examples
+
+This function is useful for inserting a multi-line string into an
+already-indented context in another string:
+
+```shell-session
+> " items: %{indent(2, "[\n foo,\n bar,\n]\n")}"
+ items: [
+ foo,
+ bar,
+ ]
+```
+
+The first line of the string is not indented so that, as above, it can be
+placed after an introduction sequence that has already begun the line.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/join.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/join.mdx
new file mode 100644
index 0000000000..acdbaa8ae0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/join.mdx
@@ -0,0 +1,29 @@
+---
+page_title: join - Functions - Configuration Language
+description: |-
+ The join function produces a string by concatenating the elements of a list
+ with a given delimiter.
+---
+
+# `join` Function
+
+`join` produces a string by concatenating together all elements of a given
+list of strings with the given delimiter.
+
+```hcl
+join(separator, list)
+```
+
+## Examples
+
+```shell-session
+> join(", ", ["foo", "bar", "baz"])
+foo, bar, baz
+> join(", ", ["foo"])
+foo
+```
+
+## Related Functions
+
+- [`split`](/packer/docs/templates/hcl_templates/functions/string/split) performs the opposite operation: producing a list
+ by separating a single string using a given delimiter.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/lower.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/lower.mdx
new file mode 100644
index 0000000000..6548248220
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/lower.mdx
@@ -0,0 +1,26 @@
+---
+page_title: lower - Functions - Configuration Language
+description: >-
+ The lower function converts all cased letters in the given string to
+ lowercase.
+---
+
+# `lower` Function
+
+`lower` converts all cased letters in the given string to lowercase.
+
+## Examples
+
+```shell-session
+> lower("HELLO")
+hello
+> lower("АЛЛО!")
+алло!
+```
+
+This function uses Unicode's definition of letters and of upper- and lowercase.
+
+## Related Functions
+
+- [`upper`](/packer/docs/templates/hcl_templates/functions/string/upper) converts letters in a string to _uppercase_.
+- [`title`](/packer/docs/templates/hcl_templates/functions/string/title) converts the first letter of each word in a string to uppercase.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regex.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regex.mdx
new file mode 100644
index 0000000000..74d55a647a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regex.mdx
@@ -0,0 +1,161 @@
+---
+page_title: regex - Functions - Configuration Language
+description: |-
+ The regex function applies a regular expression to a string and returns the
+ matching substrings.
+---
+
+# `regex` Function
+
+`regex` applies a
+[regular expression](https://en.wikipedia.org/wiki/Regular_expression)
+to a string and returns the matching substrings.
+
+```hcl
+regex(pattern, string)
+```
+
+The return type of `regex` depends on the capture groups, if any, in the
+pattern:
+
+- If the pattern has no capture groups at all, the result is a single string
+ covering the substring matched by the pattern as a whole.
+- If the pattern has one or more _unnamed_ capture groups, the result is a
+ list of the captured substrings in the same order as the definition of
+ the capture groups.
+- If the pattern has one or more _named_ capture groups, the result is a
+ map of the captured substrings, using the capture group names as map keys.
+
+It's not valid to mix both named and unnamed capture groups in the same pattern.
+
+If the given pattern does not match at all, the `regex` raises an error. To
+_test_ whether a given pattern matches a string, use
+[`regexall`](/packer/docs/templates/hcl_templates/functions/string/regexall) and test that the result has length greater than
+zero.
+
+The pattern is a string containing a mixture of literal characters and special
+matching operators as described in the following table. Note that when giving a
+regular expression pattern as a literal quoted string in the Packer
+language, the quoted string itself already uses backslash `\` as an escape
+character for the string, so any backslashes intended to be recognized as part
+of the pattern must be escaped as `\\`.
+
+| Sequence | Matches |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `.` | Any character except newline |
+| `[xyz]` | Any character listed between the brackets (`x`, `y`, and `z` in this example) |
+| `[a-z]` | Any character between `a` and `z`, inclusive |
+| `[^xyz]` | The opposite of `[xyz]` |
+| `\d` | ASCII digits (0 through 9, inclusive) |
+| `\D` | Anything except ASCII digits |
+| `\s` | ASCII spaces (space, tab, newline, carriage return, form feed) |
+| `\S` | Anything except ASCII spaces |
+| `\w` | The same as `[0-9A-Za-z_]` |
+| `\W` | Anything except the characters matched by `\w` |
+| `[[:alnum:]]` | The same as `[0-9A-Za-z]` |
+| `[[:alpha:]]` | The same as `[A-Za-z]` |
+| `[[:ascii:]]` | Any ASCII character |
+| `[[:blank:]]` | ASCII tab or space |
+| `[[:cntrl:]]` | ASCII/Unicode control characters |
+| `[[:digit:]]` | The same as `[0-9]` |
+| `[[:graph:]]` | All "graphical" (printable) ASCII characters |
+| `[[:lower:]]` | The same as `[a-z]` |
+| `[[:print:]]` | The same as `[[:graph:]]` |
+| `[[:punct:]]` | The same as `` [!-/:-@[-`{-~] `` |
+| `[[:space:]]` | The same as `[\t\n\v\f\r ]` |
+| `[[:upper:]]` | The same as `[A-Z]` |
+| `[[:word:]]` | The same as `\w` |
+| `[[:xdigit:]]` | The same as `[0-9A-Fa-f]` |
+| `\pN` | Unicode character class by using single-letter class names ("N" in this example) |
+| `\p{Greek}` | Unicode character class by unicode name ("Greek" in this example) |
+| `\PN` | The opposite of `\pN` |
+| `\P{Greek}` | The opposite of `\p{Greek}` |
+| `xy` | `x` followed immediately by `y` |
+| x|y | either `x` or `y`, preferring `x` |
+| `x*` | zero or more `x`, preferring more |
+| `x*?` | zero or more `x`, preferring fewer |
+| `x+` | one or more `x`, preferring more |
+| `x+?` | one or more `x`, preferring fewer |
+| `x?` | zero or one `x`, preferring one |
+| `x??` | zero or one `x`, preferring zero |
+| `x{n,m}` | between `n` and `m` repetitions of `x`, preferring more |
+| `x{n,m}?` | between `n` and `m` repetitions of `x`, preferring fewer |
+| `x{n,}` | at least `n` repetitions of `x`, preferring more |
+| `x{n,}?` | at least `n` repetitions of `x`, preferring fewer |
+| `x{n}` | exactly `n` repetitions of `x` |
+| `(x)` | unnamed capture group for sub-pattern `x` |
+| `(?Px)` | named capture group, named `name`, for sub-pattern `x` |
+| `(?:x)` | non-capturing sub-pattern `x` |
+| `\*` | Literal `*` for any punctuation character `*` |
+| `\Q...\E` | Literal `...` for any text `...` as long as it does not include literally `\E` |
+
+In addition to the above matching operators that consume the characters they
+match, there are some additional operators that _only_ match, but consume
+no characters. These are "zero-width" matching operators:
+
+| Sequence | Matches |
+| -------- | ------------------------------------------------------------------------------------------------ |
+| `^` | At the beginning of the given string |
+| `$` | At the end of the given string |
+| `\A` | At the beginning of the given string |
+| `\z` | At the end of the given string |
+| `\b` | At an ASCII word boundary (transition between `\w` and either `\W`, `\A` or `\z`, or vice-versa) |
+| `\B` | Not at an ASCII word boundary |
+
+Packer uses the
+[RE2](https://github.com/google/re2/wiki/Syntax) regular expression language.
+This engine does not support all of the features found in some other regular
+expression engines; in particular, it does not support backreferences.
+
+## Matching Flags
+
+Some of the matching behaviors described above can be modified by setting
+matching flags, activated using either the `(?flags)` operator (to activate
+within the current sub-pattern) or the `(?flags:x)` operator (to match `x` with
+the modified flags). Each flag is a single letter, and multiple flags can be
+set at once by listing multiple letters in the `flags` position.
+The available flags are listed in the table below:
+
+| Flag | Meaning |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `i` | Case insensitive: a literal letter in the pattern matches both lowercase and uppercase versions of that letter |
+| `m` | The `^` and `$` operators also match the beginning and end of lines within the string, marked by newline characters; behavior of `\A` and `\z` is unchanged |
+| `s` | The `.` operator also matches newline |
+| `U` | The meaning of presence or absense `?` after a repetition operator is inverted. For example, `x*` is interpreted like `x*?` and vice-versa. |
+
+## Examples
+
+```
+> regex("[a-z]+", "53453453.345345aaabbbccc23454")
+aaabbbccc
+
+> regex("(\\d\\d\\d\\d)-(\\d\\d)-(\\d\\d)", "2019-02-01")
+[
+ "2019",
+ "02",
+ "01",
+]
+
+> regex("^(?:(?P[^:/?#]+):)?(?://(?P[^/?#]*))?", "https://packer.io/docs/")
+{
+ "packer" = "packer.io"
+ "scheme" = "https"
+}
+
+> regex("[a-z]+", "53453453.34534523454")
+
+Error: Error in function call
+
+Call to function "regex" failed: pattern did not match any part of the given
+string.
+```
+
+## Related Functions
+
+- [`regexall`](/packer/docs/templates/hcl_templates/functions/string/regexall) searches for potentially multiple matches of a given pattern in a string.
+- [`replace`](/packer/docs/templates/hcl_templates/functions/string/replace) replaces a substring of a string with another string, optionally matching using the same regular expression syntax as `regex`.
+
+If Packer already has a more specialized function to parse the syntax you
+are trying to match, prefer to use that function instead. Regular expressions
+can be hard to read and can obscure your intent, making a configuration harder
+to read and understand.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regex_replace.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regex_replace.mdx
new file mode 100644
index 0000000000..29d10b8e09
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regex_replace.mdx
@@ -0,0 +1,47 @@
+---
+page_title: regex_replace - Functions - Configuration Language
+description: >-
+ The regex_replace function searches a given string for another given
+ substring,
+
+ and replaces all occurrences with a given replacement string. The substring
+
+ argument can be a valid regular expression or a string.
+---
+
+# `regex_replace` Function
+
+`regex_replace` searches a given string for another given substring, and
+replaces each occurrence with a given replacement string. The substring
+argument can be a valid regular expression or a string.
+
+```hcl
+regex_replace(string, substring, replacement)
+```
+
+`substring` should not be wrapped in forward slashes, it is always treated as a
+regular expression. The `replacement` string can incorporate captured strings
+from the input by using an `$n` or `${n}` sequence, where `n` is the index or
+name of a capture group.
+
+## Examples
+
+```shell-session
+> regex_replace("hello world", "world", "everybody")
+hello everybody
+
+
+> regex_replace("hello world", "w.*d", "everybody")
+hello everybody
+
+> regex_replace("-ab-axxb-", "a(x*)b", "$1W")
+---
+
+> regex_replace("-ab-axxb-", "a(x*)b", "${1}W")
+-W-xxW-
+```
+
+## Related Functions
+
+- [`replace`](/packer/docs/templates/hcl_templates/functions/string/replace) searches a given string for another given
+ substring, and replaces all occurrences with a given replacement string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regexall.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regexall.mdx
new file mode 100644
index 0000000000..9690069814
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/regexall.mdx
@@ -0,0 +1,56 @@
+---
+page_title: regexall - Functions - Configuration Language
+description: |-
+ The regexall function applies a regular expression to a string and returns a list of all matches.
+---
+
+# `regexall` Function
+
+`regexall` applies a
+[regular expression](https://en.wikipedia.org/wiki/Regular_expression)
+to a string and returns a list of all matches.
+
+```hcl
+regexall(pattern, string)
+```
+
+`regexall` is a variant of [`regex`](/packer/docs/templates/hcl_templates/functions/string/regex) and uses the same pattern
+syntax. For any given input to `regex`, `regexall` returns a list of whatever
+type `regex` would've returned, with one element per match. That is:
+
+- If the pattern has no capture groups at all, the result is a list of
+ strings.
+- If the pattern has one or more _unnamed_ capture groups, the result is a
+ list of lists.
+- If the pattern has one or more _named_ capture groups, the result is a
+ list of maps.
+
+`regexall` can also be used to test whether a particular string matches a
+given pattern, by testing whether the length of the resulting list of matches
+is greater than zero.
+
+## Examples
+
+```
+> regexall("[a-z]+", "1234abcd5678efgh9")
+[
+ "abcd",
+ "efgh",
+]
+
+> length(regexall("[a-z]+", "1234abcd5678efgh9"))
+2
+
+> length(regexall("[a-z]+", "123456789")) > 0
+false
+```
+
+## Related Functions
+
+- [`regex`](/packer/docs/templates/hcl_templates/functions/string/regex) searches for a single match of a given pattern, and
+ returns an error if no match is found.
+
+If Packer already has a more specialized function to parse the syntax you
+are trying to match, prefer to use that function instead. Regular expressions
+can be hard to read and can obscure your intent, making a configuration harder
+to read and understand.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/replace.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/replace.mdx
new file mode 100644
index 0000000000..4097756f9b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/replace.mdx
@@ -0,0 +1,30 @@
+---
+page_title: replace - Functions - Configuration Language
+description: |-
+ The replace function searches a given string for another given substring,
+ and replaces all occurrences with a given replacement string.
+---
+
+# `replace` Function
+
+`replace` searches a given string for another given substring, and replaces
+each occurrence with a given replacement string.
+
+```hcl
+replace(string, substring, replacement)
+```
+
+## Examples
+
+```shell-session
+> replace("1 + 2 + 3", "+", "-")
+1 - 2 - 3
+
+> replace("hello world", "world", "everybody")
+hello everybody
+```
+
+## Related Functions
+
+- [`regex_replace`](/packer/docs/templates/hcl_templates/functions/string/regex_replace) searches a given string for another given substring,
+ and replaces each occurrence with a given replacement string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/split.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/split.mdx
new file mode 100644
index 0000000000..677b10a924
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/split.mdx
@@ -0,0 +1,39 @@
+---
+page_title: split - Functions - Configuration Language
+description: |-
+ The split function produces a list by dividing a given string at all
+ occurrences of a given separator.
+---
+
+# `split` Function
+
+`split` produces a list by dividing a given string at all occurrences of a
+given separator.
+
+```hcl
+split(separator, string)
+```
+
+## Examples
+
+```shell-session
+> split(",", "foo,bar,baz")
+[
+ "foo",
+ "bar",
+ "baz",
+]
+> split(",", "foo")
+[
+ "foo",
+]
+> split(",", "")
+[
+ "",
+]
+```
+
+## Related Functions
+
+- [`join`](/packer/docs/templates/hcl_templates/functions/string/join) performs the opposite operation: producing a string
+ joining together a list of strings with a given separator.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/strrev.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/strrev.mdx
new file mode 100644
index 0000000000..c543bfeb93
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/strrev.mdx
@@ -0,0 +1,26 @@
+---
+page_title: strrev - Functions - Configuration Language
+description: The strrev function reverses a string.
+---
+
+# `strrev` Function
+
+`strrev` reverses the characters in a string.
+Note that the characters are treated as _Unicode characters_ (in technical terms, Unicode [grapheme cluster boundaries](https://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries) are respected).
+
+```hcl
+strrev(string)
+```
+
+## Examples
+
+```shell-session
+> strrev("hello")
+olleh
+> strrev("a ☃")
+☃ a
+```
+
+## Related Functions
+
+- [`reverse`](/packer/docs/templates/hcl_templates/functions/collection/reverse) reverses a sequence.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/substr.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/substr.mdx
new file mode 100644
index 0000000000..594feb28e7
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/substr.mdx
@@ -0,0 +1,29 @@
+---
+page_title: substr - Functions - Configuration Language
+description: |-
+ The substr function extracts a substring from a given string by offset and
+ length.
+---
+
+# `substr` Function
+
+`substr` extracts a substring from a given string by offset and length.
+
+```hcl
+substr(string, offset, length)
+```
+
+## Examples
+
+```shell-session
+> substr("hello world", 1, 4)
+ello
+```
+
+The offset and length are both counted in _unicode characters_ rather than
+bytes:
+
+```shell-session
+> substr("🤔🤷", 0, 1)
+🤔
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/title.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/title.mdx
new file mode 100644
index 0000000000..15d40f3d0b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/title.mdx
@@ -0,0 +1,24 @@
+---
+page_title: title - Functions - Configuration Language
+description: |-
+ The title function converts the first letter of each word in a given string
+ to uppercase.
+---
+
+# `title` Function
+
+`title` converts the first letter of each word in the given string to uppercase.
+
+## Examples
+
+```shell-session
+> title("hello world")
+Hello World
+```
+
+This function uses Unicode's definition of letters and of upper- and lowercase.
+
+## Related Functions
+
+- [`upper`](/packer/docs/templates/hcl_templates/functions/string/upper) converts _all_ letters in a string to uppercase.
+- [`lower`](/packer/docs/templates/hcl_templates/functions/string/lower) converts all letters in a string to lowercase.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trim.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trim.mdx
new file mode 100644
index 0000000000..321a46eac0
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trim.mdx
@@ -0,0 +1,25 @@
+---
+page_title: trim - Functions - Configuration Language
+description: |-
+ The trim function removes the specified characters from the start and end of
+ a given string.
+---
+
+# `trim` Function
+
+`trim` removes the specified characters from the start and end of the given
+string.
+
+## Examples
+
+```shell-session
+> trim("?!hello?!", "!?")
+hello
+```
+
+## Related Functions
+
+- [`trimprefix`](/packer/docs/templates/hcl_templates/functions/string/trimprefix) removes a word from the start of a string.
+- [`trimsuffix`](/packer/docs/templates/hcl_templates/functions/string/trimsuffix) removes a word from the end of a string.
+- [`trimspace`](/packer/docs/templates/hcl_templates/functions/string/trimspace) removes all types of whitespace from
+ both the start and the end of a string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimprefix.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimprefix.mdx
new file mode 100644
index 0000000000..f9396edc0f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimprefix.mdx
@@ -0,0 +1,24 @@
+---
+page_title: trimprefix - Functions - Configuration Language
+description: |-
+ The trimprefix function removes the specified prefix from the start of a
+ given string.
+---
+
+# `trimprefix` Function
+
+`trimprefix` removes the specified prefix from the start of the given string.
+
+## Examples
+
+```shell-session
+> trimprefix("helloworld", "hello")
+world
+```
+
+## Related Functions
+
+- [`trim`](/packer/docs/templates/hcl_templates/functions/string/trim) removes characters at the start and end of a string.
+- [`trimsuffix`](/packer/docs/templates/hcl_templates/functions/string/trimsuffix) removes a word from the end of a string.
+- [`trimspace`](/packer/docs/templates/hcl_templates/functions/string/trimspace) removes all types of whitespace from
+ both the start and the end of a string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimspace.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimspace.mdx
new file mode 100644
index 0000000000..a1f619083a
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimspace.mdx
@@ -0,0 +1,27 @@
+---
+page_title: trimspace - Functions - Configuration Language
+description: |-
+ The trimspace function removes space characters from the start and end of
+ a given string.
+---
+
+# `trimspace` Function
+
+`trimspace` removes any space characters from the start and end of the given
+string.
+
+This function follows the Unicode definition of "space", which includes
+regular spaces, tabs, newline characters, and various other space-like
+characters.
+
+## Examples
+
+```shell-session
+> trimspace(" hello\n\n")
+hello
+```
+
+## Related Functions
+
+- [`chomp`](/packer/docs/templates/hcl_templates/functions/string/chomp) removes just line ending characters from the _end_ of
+ a string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimsuffix.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimsuffix.mdx
new file mode 100644
index 0000000000..e69644ca37
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/trimsuffix.mdx
@@ -0,0 +1,24 @@
+---
+page_title: trimsuffix - Functions - Configuration Language
+description: |-
+ The trimsuffix function removes the specified suffix from the end of a
+ given string.
+---
+
+# `trimsuffix` Function
+
+`trimsuffix` removes the specified suffix from the end of the given string.
+
+## Examples
+
+```shell-session
+> trimsuffix("helloworld", "world")
+hello
+```
+
+## Related Functions
+
+- [`trim`](/packer/docs/templates/hcl_templates/functions/string/trim) removes characters at the start and end of a string.
+- [`trimprefix`](/packer/docs/templates/hcl_templates/functions/string/trimprefix) removes a word from the start of a string.
+- [`trimspace`](/packer/docs/templates/hcl_templates/functions/string/trimspace) removes all types of whitespace from
+ both the start and the end of a string.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/upper.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/upper.mdx
new file mode 100644
index 0000000000..7a6bb0a5b6
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/string/upper.mdx
@@ -0,0 +1,26 @@
+---
+page_title: upper - Functions - Configuration Language
+description: >-
+ The upper function converts all cased letters in the given string to
+ uppercase.
+---
+
+# `upper` Function
+
+`upper` converts all cased letters in the given string to uppercase.
+
+## Examples
+
+```shell-session
+> upper("hello")
+HELLO
+> upper("алло!")
+АЛЛО!
+```
+
+This function uses Unicode's definition of letters and of upper- and lowercase.
+
+## Related Functions
+
+- [`lower`](/packer/docs/templates/hcl_templates/functions/string/lower) converts letters in a string to _lowercase_.
+- [`title`](/packer/docs/templates/hcl_templates/functions/string/title) converts the first letter of each word in a string to uppercase.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/uuid/uuidv4.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/uuid/uuidv4.mdx
new file mode 100644
index 0000000000..d3135ae227
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/uuid/uuidv4.mdx
@@ -0,0 +1,27 @@
+---
+page_title: v4 - uuid - Functions - Configuration Language
+description: The uuidv4 function generates a unique ID.
+---
+
+# `uuidv4` Function
+
+`uuidv4` generates a unique identifier string.
+
+The ID is a generated and formatted as required by [RFC 4122 section
+4.4](https://tools.ietf.org/html/rfc4122#section-4.4), producing a Version 4
+UUID. The result is a UUID generated only from pseudo-random numbers.
+
+This function produces a new value each time it is called, and so using it
+directly in resource arguments will result in spurious diffs. We do not
+recommend using the `uuidv4` function in resource configurations.
+
+## Examples
+
+```shell-session
+> uuidv4()
+b5ee72a3-54dd-c4b8-551c-4bdc0204cedb
+```
+
+## Related Functions
+
+- [`uuidv5`](/packer/docs/templates/hcl_templates/functions/uuid/uuidv5), which generates name-based UUIDs.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/uuid/uuidv5.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/uuid/uuidv5.mdx
new file mode 100644
index 0000000000..310b4b1305
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/functions/uuid/uuidv5.mdx
@@ -0,0 +1,78 @@
+---
+page_title: uuidv5 - Functions - Configuration Language
+description: |-
+ The uuidv5 function generates a uuid v5 string representation of the value in
+ the specified namespace.
+---
+
+# `uuidv5` Function
+
+`uuidv5` generates a _name-based_ UUID, as described in [RFC 4122 section
+4.3](https://tools.ietf.org/html/rfc4122#section-4.3), also known as a "version
+5" UUID.
+
+```hcl
+uuidv5(namespace, name)
+```
+
+Unlike the pseudo-random UUIDs generated by [`uuidv4`](/packer/docs/templates/hcl_templates/functions/uuid/uuidv4),
+name-based UUIDs derive from namespace and an name, producing the same UUID
+value every time if the namespace and name are unchanged.
+
+Name-based UUID namespaces are themselves UUIDs, but for readability this
+function accepts some keywords as aliases for the namespaces that were assigned
+by RFC 4122:
+
+| Keyword | Namespace ID | Name format |
+| -------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `"dns"` | `6ba7b810-9dad-11d1-80b4-00c04fd430c8` | A fully-qualified DNS domain name. |
+| `"url"` | `6ba7b811-9dad-11d1-80b4-00c04fd430c8` | Any valid URL as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). |
+| `"oid"` | `6ba7b812-9dad-11d1-80b4-00c04fd430c8` | An [ISO/IEC object identifier](https://oidref.com/) |
+| `"x500"` | `6ba7b814-9dad-11d1-80b4-00c04fd430c8` | [X.500 Distinguished Name](https://tools.ietf.org/html/rfc1779) |
+
+To use any other namespace not included in the above table, pass its assigned
+namespace ID directly in the first argument in the usual UUID string format.
+
+## Examples
+
+Use the namespace keywords where possible, to make the intent more obvious to
+a future reader:
+
+```shell-session
+> uuidv5("dns", "www.packer.io")
+a5008fae-b28c-5ba5-96cd-82b4c53552d6
+
+> uuidv5("url", "https://www.packer.io/")
+9db6f67c-dd95-5ea0-aa5b-e70e5c5f7cf5
+
+> uuidv5("oid", "1.3.6.1.4")
+af9d40a5-7a36-5c07-b23a-851cd99fbfa5
+
+> uuidv5("x500", "CN=Example,C=GB")
+84e09961-4aa4-57f8-95b7-03edb1073253
+```
+
+The namespace keywords treated as equivalent to their corresponding namespace
+UUIDs, and in some special cases it may be more appropriate to use the
+UUID form:
+
+```shell-session
+> uuidv5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "www.packer.io")
+a5008fae-b28c-5ba5-96cd-82b4c53552d6
+```
+
+If you wish to use a namespace defined outside of RFC 4122, using the namespace
+UUID is required because no corresponding keyword is available:
+
+```shell-session
+> uuidv5("743ac3c0-3bf7-4a5b-9e6c-59360447c757", "LIBS:diskfont.library")
+ede1a974-df7e-5f17-84b9-76208818b2c8
+```
+
+When using raw UUID namespaces, consider including a comment alongside the
+expression that indicates which namespace this represents in a
+human-significant manner, such as by reference to the standard that defined it.
+
+## Related Functions
+
+- [`uuidv4`](/packer/docs/templates/hcl_templates/functions/uuid/uuidv4), which generates pseudorandom UUIDs.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/index.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/index.mdx
new file mode 100644
index 0000000000..72d845f8f2
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/index.mdx
@@ -0,0 +1,76 @@
+---
+page_title: HCL Templates
+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 Configuration Language
+
+`@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
+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).
+
+## Builds
+
+The main purpose of the HCL language is defining builds and sources. All other
+language features exist only to make the definition of builds more flexible and
+convenient.
+
+`packer build` takes one argument. When a directory is passed, all files in the
+folder with a name ending with `.pkr.hcl` or `.pkr.json` will be parsed using
+the HCL2 format. When a file ending with `.pkr.hcl` or `.pkr.json` is passed it
+will be parsed using the HCL2 schema. For every other case; the _JSON only_ old
+packer schema will be used.
+
+## Arguments, Blocks, and Expressions
+
+The syntax of the HCL language consists of only a few basic elements:
+
+```hcl
+source "amazon-ebs" "main" {
+ ami_name = "main-ami"
+}
+
+ "" "" {
+ # Block body
+ = # Argument
+}
+```
+
+- _Blocks_ are containers for other content and usually represent the
+ configuration of some kind of object, like a source. Blocks have a
+ _block type,_ can have zero or more _labels,_ and have a _body_ that contains
+ any number of arguments and nested blocks. Most of Packer's features are
+ controlled by top-level blocks in a configuration file.
+- _Arguments_ assign a value to a name. They appear within blocks.
+- _Expressions_ represent a value, either literally or by referencing and
+ combining other values. They appear as values for arguments, or within other
+ expressions.
+
+For full details about Packer's syntax, see:
+
+- [Configuration Syntax](/packer/docs/templates/hcl_templates/syntax)
+- [Expressions](/packer/docs/templates/hcl_templates/expressions)
+
+## Code Organization
+
+The HCL language uses configuration files that are named with the `.pkr.hcl`
+file extension. There is also [a JSON-based variant of the
+language](/packer/docs/templates/hcl_templates/syntax-json) that is named with the `.pkr.json` file
+extension.
+
+Configuration files must always use UTF-8 encoding, and by convention are
+usually maintained with Unix-style line endings (LF) rather than Windows-style
+line endings (CRLF), though both are accepted.
+
+## Configuration Ordering
+
+The ordering of root blocks is not significant. The order of `provisioner` or
+`post-processor` blocks within a `build` is the only major feature where block
+order matters.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/locals.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/locals.mdx
new file mode 100644
index 0000000000..456f6af90e
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/locals.mdx
@@ -0,0 +1,132 @@
+---
+page_title: Local Variables - HCL Configuration Language
+description: >-
+ Local variables assign a name to an expression that you can use multiple
+ times within a folder.
+---
+
+# Local Variables
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+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.
+
+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.
+
+Input variable and local variable usage are introduced in the [_Variables
+Guide_](/packer/guides/hcl/variables).
+
+## Examples
+
+Local variables are defined in a `local` or `locals` block:
+
+```hcl
+# Using the local block allows you to mark locals as sensitive, which will
+# filter their values from logs.
+local "mylocal" {
+ expression = "${var.secret_api_key}"
+ sensitive = true
+}
+
+# Using the locals block is more compact and efficient for declaring many locals
+# Ids for multiple sets of EC2 instances, merged together
+locals {
+ instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
+}
+
+# A computed default name prefix
+locals {
+ default_name_prefix = "${var.project_name}-web"
+ name_prefix = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
+}
+
+# Local variables can be referenced using the "local." prefix.
+source "virtualbox-iso" "example" {
+ output = "${local.name_prefix}-files"
+ # ...
+}
+```
+
+Named local maps can be merged with local maps to implement common or default
+values:
+
+```hcl
+# Define the common tags for all resources
+locals {
+ common_tags = {
+ Component = "awesome-app"
+ Environment = "production"
+ }
+}
+
+# Create a resource that blends the common tags with instance-specific tags.
+source "amazon-ebs" "server" {
+ source_ami = "ami-123456"
+ instance_type = "t2.micro"
+
+ tags = "${merge(
+ local.common_tags,
+ {
+ "Name" = "awesome-app-server",
+ "Role" = "server"
+ }
+ )}"
+ # ...
+}
+```
+
+## Single `local` block
+
+The `local` block defines exactly one local variable within a folder. The block
+label is the name of the local, and the "expression" is the expression that
+should be evaluated to create the local. Using this block, you can optionally
+supply a "sensitive" boolean to mark the variable as sensitive and filter it
+from logs.
+
+```hcl
+local "mylocal" {
+ expression = "${var.secret_api_key}"
+ sensitive = true
+}
+```
+
+This block is also very useful for defining complex locals. Packer might take some time to expand and evaluate `locals`
+with complex expressions dependent on other locals. The `locals` block is read as a map. Maps are not sorted, and therefore
+the evaluation time is not deterministic.
+
+To avoid that, singular `local` blocks should be used instead. These will be
+evaluated in the order they are defined, and the evaluation order and time will always be the same.
+
+## `locals` block
+
+The `locals` block defines one or more local variables within a folder.
+
+The names given for the items in the `locals` block must be unique throughout a
+folder. The given value can be any expression that is valid within the current
+folder.
+
+The expression of a local value can refer to other locals, but reference cycles
+are not allowed. That is, a local cannot refer to itself or to a variable that
+refers (directly or indirectly) back to it.
+
+It's recommended to group together logically-related local variables into a single
+block, particularly if they depend on each other. This will help the reader
+understand the relationships between variables. Conversely, prefer to define
+_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
+`@include 'datasources/local-dependency-limitation.mdx'`
+
+
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/onlyexcept.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/onlyexcept.mdx
new file mode 100644
index 0000000000..3aab1084c5
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/onlyexcept.mdx
@@ -0,0 +1,80 @@
+---
+page_title: Only Except - HCL Configuration Language
+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.
+---
+
+# Only and Except
+
+`only` and `except` are keywords used to filter what runs in your Packer build,
+they can be seen as a command line argument:
+
+`@include 'commands/except.mdx'`
+
+`@include 'commands/only.mdx'`
+
+They can also be seen in a template to run or skip provisioners and/or
+post-processors for a specific source:
+
+```hcl
+source "amazon-ebs" "first-example" {
+}
+
+source "amazon-ebs" "second-example" {
+}
+
+source "amazon-ebs" "third-example" {
+}
+
+build {
+ name = "my_build"
+ sources = [
+ "source.amazon-ebs.first-example",
+ ]
+ source "source.amazon-ebs.second-example" {
+ // setting the name field allows you to rename the source only for this
+ // build section. To match this builder, you need to use
+ // second-example-local-name, not second-example
+ name = "second-example-local-name"
+ }
+
+ provisioner "shell-local" {
+ only = ["amazon-ebs.first-example"]
+ inline = ["echo I will only run for the first example source"]
+ }
+
+ provisioner "shell-local" {
+ except = ["amazon-ebs.second-example-local-name"]
+ inline = ["echo I will never run for the second example source"]
+ }
+}
+
+build {
+ sources = [
+ "source.amazon-ebs.third-example",
+ ]
+}
+
+# this file will result in Packer creating three builds named:
+# my_build.amazon-ebs.first-example
+# my_build.amazon-ebs.second-example
+# amazon-ebs.third-example
+```
+
+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
+ named `my_build`.
+
+- `packer build -only '*.amazon-ebs.*' dir`: will only run the builds with a
+ source of type `amazon-ebs`.
+
+- `packer build -only '*.second-example-local-name' dir`: will only run that
+ specifically named build.
+
+-> Note: In the cli `only` and `except` will match against **build names** (for
+example:`my_build.amazon-ebs.first-example`) but in a provisioner they will
+match on the **source name** (for example:`amazon-ebs.third-example`).
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/path-variables.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/path-variables.mdx
new file mode 100644
index 0000000000..fb9b74defc
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/path-variables.mdx
@@ -0,0 +1,40 @@
+---
+page_title: Path Variables - HCL Configuration Language
+description: |-
+ Special variables provide directory information. This page covers all path
+ variables.
+---
+
+`@include 'path/separator-note.mdx'`
+
+# Path variables
+
+- `path.cwd`: the directory from where Packer was started.
+
+- `path.root`: the directory of the input HCL file or the input folder.
+
+## Examples
+
+```HCL
+locals {
+ settings_file = "${path.cwd}/settings.txt"
+ scripts_folder = "${path.root}/scripts"
+ root = path.root
+}
+```
+
+## 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.
+
+- [`basename`](/packer/docs/templates/hcl_templates/functions/file/basename) returns _only_ the last
+ portion of a filesystem path, discarding the portion that would be returned
+ by `dirname`.
+
+- [`fileset`](/packer/docs/templates/hcl_templates/functions/file/fileset) enumerates a set of
+ regular file names given a path and pattern.
+
+- [`dirname`](/packer/docs/templates/hcl_templates/functions/file/dirname) returns all of the
+ segments of a filesystem path _except_ the last, discarding the portion that
+ would be returned by `basename`.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/syntax-json.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/syntax-json.mdx
new file mode 100644
index 0000000000..414f864a0e
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/syntax-json.mdx
@@ -0,0 +1,308 @@
+---
+page_title: JSON Configuration Syntax - Configuration Language
+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.
+---
+
+# JSON Configuration Syntax
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+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.
+
+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
+configuration files.
+
+This syntax is not to be confused with the pre-version-1.5 "legacy" Packer
+templates, which were exclusively JSON and follow a different format.
+
+The JSON syntax is defined in terms of the native syntax. Everything that can
+be expressed in native syntax can also be expressed in JSON syntax, but some
+constructs are more complex to represent in JSON due to limitations of the
+JSON grammar.
+
+Packer expects native syntax for files named with a `.pkr.hcl` suffix, and JSON
+syntax for files named with a `.pkr.json` suffix. If you leave out the `.pkr`
+portion of suffix, Packer will try to read your json file as a legacy Packer
+template.
+
+The low-level JSON syntax, just as with the native syntax, is defined in terms
+of a specification called _HCL_. It is not necessary to know all of the details
+of HCL syntax or its JSON mapping in order to use Packer, and so this page
+summarizes the most important differences between native and JSON syntax. If
+you are interested, you can find a full definition of HCL's JSON syntax in [its
+specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).
+
+## JSON File Structure
+
+At the root of any JSON-based Packer configuration is a JSON object. The
+properties of this object correspond to the top-level block types of the
+Packer language. For example:
+
+```json
+{
+ "variables": {
+ "example": "value"
+ }
+}
+```
+
+Each top-level object property must match the name of one of the expected
+top-level block types. Block types that expect labels, such as `variable` shown
+above, are represented by one nested object value for each level of label.
+`source` blocks expect two labels, so two levels of nesting are required:
+
+```json
+{
+ "source": {
+ "amazon-ebs": {
+ "example": {
+ "instance_type": "t2.micro",
+ "ami_name": "ami-abc123"
+ }
+ }
+ }
+}
+```
+
+After any nested objects representing the labels, finally one more nested
+object represents the body of the block itself. In the above example the
+`instance_type` and `ami_name` arguments for `source "amazon-ebs" "example"`
+are specified.
+
+Taken together, the above two configuration files are equivalent to the
+following blocks in the native syntax:
+
+```hcl
+variables {
+ example = "value"
+}
+
+source "amazon-ebs" "example" {
+ instance_type = "t2.micro"
+ ami_name = "ami-abc123"
+}
+```
+
+Within each top-level block type the rules for mapping to JSON are slightly
+different (see [block-type-specific exceptions](#block-type-specific-exceptions) below), but the following general rules apply in most cases:
+
+- The JSON object representing the block body contains properties that
+ correspond either to argument names or to nested block type names.
+
+- Where a property corresponds to an argument that accepts
+ [arbitrary expressions](/packer/docs/templates/hcl_templates/expressions) in the native syntax, the
+ property value is mapped to an expression as described under
+ [_Expression Mapping_](#expression-mapping) below. For arguments that
+ do _not_ accept arbitrary expressions, the interpretation of the property
+ value depends on the argument, as described in the
+ [block-type-specific exceptions](#block-type-specific-exceptions)
+ given later in this page.
+
+- Where a property name corresponds to an expected nested block type name,
+ the value is interpreted as described under
+ [_Nested Block Mapping_](#nested-block-mapping) below, unless otherwise
+ stated in [the block-type-specific exceptions](#block-type-specific-exceptions)
+ given later in this page.
+
+## Expression Mapping
+
+Since JSON grammar is not able to represent all of the Packer language
+[expression syntax](/packer/docs/templates/hcl_templates/expressions), JSON values interpreted as expressions
+are mapped as follows:
+
+| JSON | Packer Language Interpretation |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Boolean | A literal `bool` value. |
+| Number | A literal `number` value. |
+| String | Parsed as a [string template](/packer/docs/templates/hcl_templates/expressions#string-templates) and then evaluated as described below. |
+| Object | Each property value is mapped per this table, producing an `object(...)` value with suitable attribute types. |
+| Array | Each element is mapped per this table, producing a `tuple(...)` value with suitable element types. |
+| Null | A literal `null`. |
+
+When a JSON string is encountered in a location where arbitrary expressions are
+expected, its value is first parsed as a [string template](/packer/docs/templates/hcl_templates/expressions#string-templates)
+and then it is evaluated to produce the final result.
+
+If the given template consists _only_ of a single interpolation sequence,
+the result of its expression is taken directly, without first converting it
+to a string. This allows non-string expressions to be used within the
+JSON syntax.
+
+## Nested Block Mapping
+
+When a JSON object property is named after a nested block type, the value
+of this property represents one or more blocks of that type. The value of
+the property must be either a JSON object or a JSON array.
+
+The simplest situation is representing only a single block of the given type
+when that type expects no labels, as with the `tags` nested block used
+within `source` blocks:
+
+```json
+{
+ "source": {
+ "amazon-ebs": {
+ "example": {
+ "tags": {
+ "key": "value"
+ }
+ }
+ }
+ }
+}
+```
+
+The above is equivalent to the following native syntax configuration:
+
+```hcl
+source "amazon-ebs" "example" {
+ tags = {
+ key = "value"
+ }
+}
+```
+
+When the nested block type requires one or more labels, or when multiple
+blocks of the same type can be given, the mapping gets a little more
+complicated. For example, the `provisioner` nested block type used
+within `build` blocks expects a label giving the provisioner to use,
+and the ordering of provisioner blocks is significant to decide the order
+of operations.
+
+The following native syntax example shows a `build` block with a number
+of provisioners of different types:
+
+```hcl
+build {
+ # (source configuration omitted for brevity)
+
+ provisioner "shell-local" {
+ inline = ["echo 'Hello World' >example.txt"]
+ }
+ provisioner "file" {
+ source = "example.txt"
+ destination = "/tmp/example.txt"
+ }
+ provisioner "shell" {
+ inline = [
+ "sudo install-something -f /tmp/example.txt",
+ ]
+ }
+}
+```
+
+In order to preserve the order of these blocks, you must use a JSON array
+as the direct value of the property representing this block type, as in
+this JSON equivalent of the above:
+
+```json
+{
+ "build": {
+ "//": "(source configuration omitted for brevity)",
+
+ "provisioner": [
+ {
+ "shell-local": {
+ "inline": ["echo 'Hello World' >example.txt"]
+ }
+ },
+ {
+ "file": {
+ "source": "example.txt",
+ "destination": "/tmp/example.txt"
+ }
+ },
+ {
+ "shell": {
+ "inline": ["sudo install-something -f /tmp/example.txt"]
+ }
+ }
+ ]
+ }
+}
+```
+
+Each element of the `provisioner` array is an object with a single property
+whose name represents the label for each `provisioner` block. For block types
+that expect multiple labels, this pattern of alternating array and object
+nesting can be used for each additional level.
+
+If a nested block type requires labels but the order does _not_ matter, you
+may omit the array and provide just a single object whose property names
+correspond to unique block labels. This is allowed as a shorthand for the above
+for simple cases, but the alternating array and object approach is the most
+general. We recommend using the most general form if systematically converting
+from native syntax to JSON, to ensure that the meaning of the configuration is
+preserved exactly.
+
+### Comment Properties
+
+Although we do not recommend hand-editing of JSON syntax configuration files
+-- this format is primarily intended for programmatic generation and consumption --
+a limited form of _comments_ are allowed inside JSON objects that represent
+block bodies using a special property name:
+
+```json
+{
+ "source": {
+ "amazon-ebs": {
+ "example": {
+ "//": "This instance runs the scheduled tasks for backup",
+
+ "instance_type": "t2.micro",
+ "ami_name": "ami-abc123"
+ }
+ }
+ }
+}
+```
+
+In any object that represents a block body, properties named `"//"` are
+ignored by Packer entirely. This exception does _not_ apply to objects
+that are being [interpreted as expressions](#expression-mapping), where this
+would be interpreted as an object type attribute named `"//"`.
+
+This special property name can also be used at the root of a JSON-based
+configuration file. This can be useful to note which program created the file.
+
+```json
+{
+ "//": "This file is generated by generate-outputs.py. DO NOT HAND-EDIT!"
+}
+```
+
+## Block-type-specific Exceptions
+
+[inpage-block]: #block-type-specific-exceptions
+
+Certain arguments within specific block types are processed in a special way,
+and so their mapping to the JSON syntax does not follow the general rules
+described above. The following sub-sections describe the special mapping rules
+that apply to each top-level block type.
+
+### `variable` blocks
+
+All arguments inside `variable` blocks have non-standard mappings to JSON:
+
+- `type`: a string containing a type expression, like `"string"` or `"list(string)"`.
+- `default`: a literal JSON value that can be converted to the given type.
+ Strings within this value are taken literally and _not_ interpreted as
+ string templates.
+- `description`: a literal JSON string, _not_ interpreted as a template.
+
+```json
+{
+ "variable": {
+ "example": {
+ "type": "string",
+ "default": "hello"
+ }
+ }
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/syntax.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/syntax.mdx
new file mode 100644
index 0000000000..7ed024eca5
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/syntax.mdx
@@ -0,0 +1,119 @@
+---
+page_title: Syntax - Configuration Language
+description: |-
+ HCL has its own syntax, intended to combine declarative
+ structure with expressions in a way that is easy for humans to read and
+ understand.
+---
+
+# HCL Configuration Syntax
+
+`@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
+language in more detail, revealing the building blocks that those constructs
+are built from.
+
+This page describes the _native syntax_ of HCL, which is a rich language
+designed to be easy for humans to read and write. The constructs in HCL can
+also be expressed in [JSON syntax](/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
+particular other HashiCorp products. It is not necessary to know all of the
+details of HCL in order to use Packer, and so this page summarizes the most
+important details. If you are interested, you can find a full definition of HCL
+syntax in [the HCL native syntax
+specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).
+
+## Arguments and Blocks
+
+HCL syntax is built around two key syntax constructs:
+arguments and blocks.
+
+### Arguments
+
+An _argument_ assigns a value to a particular name:
+
+```hcl
+image_id = "abc123"
+```
+
+The identifier before the equals sign is the _argument name_, and the expression
+after the equals sign is the argument's value.
+
+The context where the argument appears determines what value types are valid
+(for example, each source type has a schema that defines the types of its
+arguments), but many arguments accept arbitrary
+[expressions](/packer/docs/templates/hcl_templates/expressions), which allow the value to
+either be specified literally or generated from other values programmatically.
+
+### Blocks
+
+A _block_ is a container for other content:
+
+```hcl
+source "amazon-ebs" "example" {
+ ami_name = "abc123"
+
+ tags = {
+ # ...
+ }
+}
+```
+
+A block has a _type_ (`source` in this example). Each block type defines
+how many _labels_ must follow the type keyword. The `source` block type
+expects two labels, which are `amazon-ebs` and `example` in the example above.
+A particular block type may have any number of required labels, or it may
+require none as with the nested `tags` block type.
+
+After the block type keyword and any labels, the block _body_ is delimited
+by the `{` and `}` characters. Within the block body, further arguments
+and blocks may be nested, creating a hierarchy of blocks and their associated
+arguments.
+
+HCL uses a limited number of _top-level block types,_ which
+are blocks that can appear outside of any other block in a configuration file.
+Most of Packer's features (including resources, input variables, output
+values, data sources, etc.) are implemented as top-level blocks.
+
+## Identifiers
+
+Argument names, block type names, and the names of most Packer-specific
+constructs like resources, input variables, etc. are all _identifiers_.
+
+Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
+The first character of an identifier must not be a digit, to avoid ambiguity
+with literal numbers.
+
+For complete identifier rules, Packer implements
+[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
+include the ASCII hyphen character `-`.
+
+## Comments
+
+HCL supports three different syntaxes for comments:
+
+- `#` begins a single-line comment, ending at the end of the line.
+- `//` also begins a single-line comment, as an alternative to `#`.
+- `/*` and `*/` are start and end delimiters for a comment that might span
+ over multiple lines.
+
+The `#` single-line comment style is the default comment style and should be
+used in most cases. Automatic configuration formatting tools may automatically
+transform `//` comments into `#` comments, since the double-slash style is
+not idiomatic.
+
+## Character Encoding and Line Endings
+
+Packer configuration files must always be UTF-8 encoded. While the
+delimiters of the language are all ASCII characters, Packer accepts
+non-ASCII characters in identifiers, comments, and string values.
+
+Packer accepts configuration files with either Unix-style line endings
+(LF only) or Windows-style line endings (CR then LF), but the idiomatic style
+is to use the Unix convention, and so automatic configuration formatting tools
+may automatically transform CRLF endings to LF.
diff --git a/content/packer/v1.10.x/content/docs/templates/hcl_templates/variables.mdx b/content/packer/v1.10.x/content/docs/templates/hcl_templates/variables.mdx
new file mode 100644
index 0000000000..4c8f856faf
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/hcl_templates/variables.mdx
@@ -0,0 +1,339 @@
+---
+page_title: Input Variables - HCL Configuration Language
+description: |-
+ Input variables are parameters for Packer modules.
+ This page covers configuration syntax for variables.
+---
+
+# Input Variables
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+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.
+
+This page is about input variables. To learn about local variables, see the
+[locals](/packer/docs/templates/hcl_templates/locals) page.
+
+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)).
+
+## Declaring an Input Variable
+
+Each input variable accepted by a build must be declared using a `variable`
+block :
+
+```hcl
+variable "image_id" {
+ type = string
+}
+
+variable "availability_zone_names" {
+ type = list(string)
+ default = ["us-west-1a"]
+}
+
+variable "docker_ports" {
+ type = list(object({
+ internal = number
+ external = number
+ protocol = string
+ }))
+ default = [
+ {
+ internal = 8300
+ external = 8300
+ protocol = "tcp"
+ }
+ ]
+}
+```
+
+Or a less precise variables block:
+
+```hcl
+variables {
+ foo = "value"
+ my_secret = "foo"
+}
+```
+
+The label after the `variable` keyword or a label of a `variables` block is a
+name for the variable, which must be unique among all variables in the same
+build. This name is used to assign a value to the variable from outside and to
+reference the variable's value from within the build.
+
+
+## Arguments
+
+Packer defines the following arguments for variable declarations:
+
+* [`default`][inpage-default] - A default value which then makes the variable optional.
+* [`type`][inpage-type] - This argument specifies what value types are accepted for the variable.
+* [`description`][inpage-description] - This specifies the input variable's documentation.
+* [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints.
+* [`sensitive`][inpage-sensitive] - This causes string-values from that variable to be obfuscated from Packer's output.
+
+
+
+### Default values
+
+[inpage-default]: #default-values
+
+The variable declaration can also include a `default` argument. If present,
+the variable is considered to be _optional_ and the default value will be used
+if no value is set when running Packer. The `default`
+argument requires a literal value and cannot reference other objects in the
+configuration.
+
+
+### Type Constraints
+[inpage-type]: #type-constraints
+
+The `type` argument in a `variable` block allows you to restrict the [type of
+value](/packer/docs/templates/hcl_templates/expressions#types-and-values) that will be accepted as the value
+for a variable. If no type constraint is set then a value of any type is
+accepted.
+
+While type constraints are optional, we recommend specifying them; they serve
+as easy reminders for users of the build, and allow Packer to return a helpful
+error message if the wrong type is used.
+
+Type constraints are created from a mixture of type keywords and type
+constructors. The supported type keywords are:
+
+- `string`
+- `number`
+- `bool`
+
+The type constructors allow you to specify complex types such as collections:
+
+- `list()`
+- `set()`
+- `map()`
+- `object({ = , ... })`
+- `tuple([, ...])`
+
+The keyword `any` may be used to indicate that any type is acceptable. For more
+information on the meaning and behavior of these different types, as well as
+detailed information about automatic conversion of complex types, see [Type
+Constraints](/terraform/docs/configuration/types).
+
+If both the `type` and `default` arguments are specified, the given default
+value must be convertible to the specified type.
+
+If only `default` is specified, the type of the default value will be used.
+
+When the `type` and `default` are both _not_ specified and you try to set a
+variable [from env vars](#environment-variables) or [from the command
+line](#variables-on-the-command-line), the variable will always be interpreted
+as a string.
+
+### Input Variable Documentation
+
+[inpage-description]: #input-variable-documentation
+
+Because the input variables of a build are part of its user interface, you can
+briefly describe the purpose of each variable using the optional `description`
+argument:
+
+```hcl
+variable "image_id" {
+ type = string
+ description = "The ID of the machine image (AMI) to use for the server."
+}
+```
+
+The description should concisely explain the purpose of the variable and what
+kind of value is expected. This description string might be included in
+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.
+
+`@include 'from-1.5/variables/custom-validation.mdx'`
+
+`@include 'from-1.5/variables/sensitive.mdx'`
+
+
+## Using Input Variable Values
+
+Within the build that declared a variable, its value can be accessed from
+within [expressions](/packer/docs/templates/hcl_templates/expressions) as `var.`, where ``
+matches the label given in the declaration block:
+
+```hcl
+source "googlecompute" "debian" {
+ zone = var.gcp_zone
+ tags = var.gcp_debian_tags
+}
+```
+
+The value assigned to a variable can be accessed only from expressions within
+the folder where it was declared.
+
+
+`@include 'from-1.5/variables/assignment.mdx'`
+
+The following sections describe these options in more detail.
+
+### Variables on the Command Line
+
+To specify individual variables on the command line, use the `-var` option when
+running the `packer build` command:
+
+```shell-session
+$ packer build -var="image_id=ami-abc123"
+$ packer build -var='image_id_list=["ami-abc123","ami-def456"]'
+$ packer build -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'
+```
+
+The `-var` option can be used any number of times in a single command.
+
+If you plan to assign variables via the command line, we strongly recommend that
+you at least set a default type instead of using empty blocks; this helps the
+HCL parser understand what is being set. Otherwise, the interpreter will assume
+that any variable set on the command line is a string.
+
+### Standard Variable Definitions Files
+
+To set lots of variables, it is more convenient to specify their values in a
+_variable definitions file_ with a filename ending in either `.pkrvars.hcl` or
+`.pkrvars.json` and then specify that file on the command line with
+`-var-file`:
+
+```shell-session
+$ packer build -var-file="testing.pkrvars.hcl"
+```
+
+A variable definitions file uses the same basic syntax as Packer language
+files, but consists only of variable name and its assigned values:
+
+```hcl
+image_id = "ami-abc123"
+availability_zone_names = [
+ "us-east-1a",
+ "us-west-1c",
+]
+```
+
+~> **Important**: Unlike legacy JSON templates the input variables within a variable definitions file must be declared
+via a variables block within a standard HCL2 template file `*.pkr.hcl` before it can be assigned a value.
+Failure to do so will result in an unknown variable error during Packer's runtime.
+
+### Auto-loaded Variable Definitions Files
+
+Packer also has the ability automatically load one or more variable definitions files if they
+are present:
+
+- Any files with names ending in `.auto.pkrvars.hcl` or `.auto.pkrvars.json`.
+
+Files whose names end with `.json` are parsed as JSON objects instead of HCL,
+with the root object properties corresponding to variable names:
+
+```json
+{
+ "image_id": "ami-abc123",
+ "availability_zone_names": ["us-west-1a", "us-west-1c"]
+}
+```
+
+~> **Important**: Unlike legacy JSON templates the input variables within a variable definitions file must be declared
+via a variables block within a standard HCL2 template file `*.pkr.hcl` before it can be assigned a value.
+Failure to do so will result in an unknown variable error during Packer's runtime.
+
+
+### Environment Variables
+
+As a fallback for the other ways of defining variables, Packer searches the
+environment of its own process for environment variables named `PKR_VAR_`
+followed by the name of a declared variable.
+
+This can be useful when running Packer in automation, or when running a
+sequence of Packer commands in succession with the same variables. For example,
+at a `bash` prompt on a Unix system:
+
+```shell-session
+$ export PKR_VAR_image_id=ami-abc123
+$ packer build gcp/debian/
+...
+```
+
+On operating systems where environment variable names are case-sensitive,
+Packer matches the variable name exactly as given in configuration, and so the
+required environment variable name will usually have a mix of upper and lower
+case letters as in the above example.
+
+### Complex-typed Values
+
+When variable values are provided in a variable definitions file, Packer's
+[usual syntax](/packer/docs/templates/hcl_templates/expressions) can be used to assign
+complex-typed values, like lists and maps.
+
+Some special rules apply to the `-var` command line option and to environment
+variables. For convenience, Packer defaults to interpreting `-var` and
+environment variable values as literal strings, which do not need to be quoted:
+
+```shell-session
+$ export PKR_VAR_image_id=ami-abc123
+```
+
+However, if a build variable uses a [type constraint](#type-constraints) to
+require a complex value (list, set, map, object, or tuple), Packer will instead
+attempt to parse its value using the same syntax used within variable
+definitions files, which requires careful attention to the string escaping
+rules in your shell:
+
+```shell-session
+$ export PKR_VAR_availability_zone_names='["us-west-1b","us-west-1d"]'
+```
+
+For readability, and to avoid the need to worry about shell escaping, we
+recommend always setting complex variable values via variable definitions
+files.
+
+### Variable Definition Precedence
+
+The above mechanisms for setting variables can be used together in any
+combination.
+
+Packer loads variables in the following order, with later sources taking
+precedence over earlier ones:
+
+- Environment variables (lowest priority)
+- Any `*.auto.pkrvars.hcl` or `*.auto.pkrvars.json` files, processed in lexical
+ order of their filenames.
+- Any `-var` and `-var-file` options on the command line, in the order they are
+ provided. (highest priority)
+
+If the same variable is assigned multiple values using different mechanisms,
+Packer uses the _last_ value it finds, overriding any previous values. Note
+that the same variable cannot be assigned multiple values within a single source.
+
+~> **Important:** Variables with map and object values behave the same way as
+other variables: the last value found overrides the previous values.
+
+`@include 'from-1.5/variables/must-be-set.mdx'`
+
+### Setting an unknown variable will not always fail:
+
+| Usage | packer validate | any other packer command |
+| :----------------------------: | :---------------------: | :-----------------------: |
+| `bar=yz` in .pkrvars.hcl file. | error, "bar undeclared" | warning, "bar undeclared" |
+| `var.bar` in .pkr.hcl file | error, "bar undeclared" | error, "bar undeclared" |
+| `-var bar=yz` argument | error, "bar undeclared" | error, "bar undeclared" |
+| `export PKR_VAR_bar=yz` | - | - |
+
diff --git a/content/packer/v1.10.x/content/docs/templates/index.mdx b/content/packer/v1.10.x/content/docs/templates/index.mdx
new file mode 100644
index 0000000000..b3c0ccd661
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/index.mdx
@@ -0,0 +1,31 @@
+---
+description: |
+ This section describes the configuration language used to create Packer
+ templates.
+page_title: Templates
+---
+
+# Packer Templates
+
+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.
+
+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.
+
+From version **1.7.0**, HCL2 becomes officially the preferred way to write Packer
+configuration(s).
+
+If you need help upgrading a JSON template to an HCL template, check
+our upgrade guide [here](/packer/tutorials/configuration-language/hcl2-upgrade).
diff --git a/content/packer/v1.10.x/content/docs/templates/json_to_hcl.mdx b/content/packer/v1.10.x/content/docs/templates/json_to_hcl.mdx
new file mode 100644
index 0000000000..2be56685dc
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/json_to_hcl.mdx
@@ -0,0 +1,158 @@
+---
+description: |
+ This section highlights the differences between JSON and HCL2 templates and explains the parallels between the specifications.
+page_title: JSON to HCL
+---
+
+# Packer 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 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.
+
+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
+
+Builders are components that are specialized for a platform.
+Their role is to set the stage for the steps that will let you build the final image from your configuration template.
+
+### JSON
+
+In JSON, the `builders` attribute declares how a builder will be invoked to build an image.
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "name": "test",
+ "communicator": "none"
+ }
+ ]
+}
+```
+
+### HCL2
+
+In HCL2, builders are declared through a `source` block. Sources on their own are not enough, and must be invoked in a `build` block.
+The `build` block serves as a container for all the steps (i.e. `source`, `provisioners` and `post-processors`) to go from a blank image to a finished one.
+
+```hcl
+source "null" "test" {
+ communicator = "none"
+}
+
+build {
+ sources = ["null.test"]
+}
+```
+
+## Provisioners
+
+Provisioners are components that modify the state of the machine image you are building.
+They can be used for installing packages, writing data to the remote file system, or executing remote commands.
+They can be defined in both JSON or HCL templates.
+
+### JSON
+
+In a JSON template, provisioners are declared at the top-level of the template as an array of sequentially
+invoked components to provision the image you are building. They apply to all the builders defined in the template.
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "name": "test",
+ "communicator": "none"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "inline": ["echo test"]
+ }
+ ]
+}
+```
+
+### HCL2
+
+In HCL2, provisioners are declared in the `build` block, and apply only to the sources invoked as
+part of this build block.
+This lets you declare multiple build blocks, each with its own set of provisioners, which will
+result in multiple different builds executed in parallel.
+
+```hcl
+source "null" "test" {
+ communicator = "none"
+}
+
+build {
+ sources = ["null.test"]
+
+ provisioner "shell-local" {
+ inline = ["echo test"]
+ }
+}
+```
+
+## Post-processors
+
+Post-processors are components that are invoked after the image was produced. Their
+role is to consume an artifact produced by a builder, or another post-processor, and
+build a new artifact from that.
+
+### JSON
+
+As with provisioners, in JSON templates, post-processors are sequentially invoked after a
+build finished provisioning, and are declared in the template under "post-processors".
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "name": "test",
+ "communicator": "none"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "inline": ["echo test"]
+ }
+ ],
+ "post-processors": [
+ {
+ "type": "manifest"
+ }
+ ]
+}
+```
+
+### HCL2
+
+In HCL2, much like provisioners, they are also part of the `build` block, and similar rules
+apply as with provisioners.
+
+```hcl
+source "null" "test" {
+ communicator = "none"
+}
+
+build {
+ sources = ["null.test"]
+
+ provisioner "shell-local" {
+ inline = ["echo test"]
+ }
+
+ post-processor "manifest" {}
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/builders.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/builders.mdx
new file mode 100644
index 0000000000..42d3afa15b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/builders.mdx
@@ -0,0 +1,78 @@
+---
+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
+---
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+# Template Builders
+
+Within the template, the builders section 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
+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.
+
+This documentation page will cover how to configure a builder in a template.
+The specific configuration options available for each builder, however, must be
+referenced from the documentation for that specific builder.
+
+Within a template, a section of builder definitions looks like this:
+
+```json
+{
+ "builders": [
+ // ... one or more builder definitions here
+ ]
+}
+```
+
+## Builder Definition
+
+A single builder definition maps to exactly one
+[build](/packer/docs/terminology#builds). A builder definition is a
+JSON object that requires at least a `type` key. The `type` is the name of the
+builder that will be used to create a machine image for the build.
+
+In addition to the `type`, other keys configure the builder itself. For
+example, the AWS builder requires an `access_key`, `secret_key`, and some other
+settings. These are placed directly within the builder definition.
+
+An example builder definition is shown below, in this case configuring the AWS
+builder:
+
+```json
+{
+ "type": "amazon-ebs",
+ "access_key": "...",
+ "secret_key": "..."
+}
+```
+
+## Named Builds
+
+Each build in Packer has a name. By default, the name is just the name of the
+builder being used. In general, this is good enough. Names only serve as an
+indicator in the output of what is happening. If you want, however, you can
+specify a custom name using the `name` key within the builder definition.
+
+This is particularly useful if you have multiple builds defined that use the
+same underlying builder. In this case, you must specify a name for at least one
+of them since the names must be unique.
+
+## Communicators
+
+Every build is associated with a single
+[communicator](/packer/docs/templates/legacy_json_templates/communicator). Communicators are used to
+establish a connection for provisioning a remote machine (such as an AWS
+instance or local virtual machine).
+
+All the examples for the various builders show some communicator (usually SSH),
+but the communicators are highly customizable so we recommend reading the
+[communicator documentation](/packer/docs/templates/legacy_json_templates/communicator).
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/communicator.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/communicator.mdx
new file mode 100644
index 0000000000..a1c32a9c69
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/communicator.mdx
@@ -0,0 +1,52 @@
+---
+description: |
+ Communicators are the mechanism Packer uses to upload files, execute scripts,
+ etc. with the machine being created.
+page_title: Communicators - Templates
+---
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+# Template Communicators
+
+Communicators are the mechanism Packer uses to upload files, execute scripts,
+etc. with the machine being created.
+
+Communicators are configured within the
+[builder](/packer/docs/templates/legacy_json_templates/builders) section.
+
+All communicators have the following options:
+
+@include 'packer-plugin-sdk/communicator/Config-not-required.mdx'
+
+## Getting Ready to Use the Communicator
+
+Depending on your builder, your communicator may not have all it needs in order
+to work "out of the box".
+
+If you are building from a cloud image (for example, building on Amazon), there
+is a good chance that your cloud provider has already preconfigured SSH on the
+image for you, meaning that all you have to do is configure the communicator in
+the Packer template.
+
+However, if you are building from a brand-new and unconfigured operating system
+image, you will almost always have to perform some extra work to configure SSH
+on the guest machine. For most operating system distributions, this work will
+be performed by a [boot_command](/packer/plugins/builders/vmware/iso#boot-configuration) that references a file which
+provides answers to the normally-interactive questions you get asked when
+installing an operating system. The name of this file varies by operating
+system; some common examples are the "preseed" file required by Debian, the
+"kickstart" file required by CentOS or the "answer file", also known as the
+Autounattend.xml file, required by Windows. For simplicity's sake, we'll refer
+to this file as the "preseed" file in the rest of the documentation.
+
+If you are unfamiliar with how to use a preseed file for automatic
+bootstrapping of an image, please either take a look at our quick guides to
+image bootstrapping, or research automatic configuration for your specific
+guest operating system. Knowing how to automatically initalize your operating
+system is critical for being able to successfully use Packer.
+
+## Communicator-Specific Options
+
+For more details on how to use each communicator, visit the
+[communicators](/packer/docs/communicators) page.
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/engine.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/engine.mdx
new file mode 100644
index 0000000000..e603320c5e
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/engine.mdx
@@ -0,0 +1,382 @@
+---
+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
+---
+
+# Template Engine
+
+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.
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+The syntax of templates uses the following conventions:
+
+- Anything template related happens within double-braces: `{{ }}`.
+- Functions are specified directly within the braces, such as
+ `{{timestamp}}`.
+- Template variables are prefixed with a period and capitalized, such as
+ `{{.Variable}}`.
+
+## Functions
+
+Functions perform operations on and within strings, for example the
+`{{timestamp}}` function can be used in any string to generate the current
+timestamp. This is useful for configurations that require unique keys, such as
+AMI names. By setting the AMI name to something like `My Packer AMI {{timestamp}}`, the AMI name will be unique down to the second. If you need
+greater than one second granularity, you should use `{{uuid}}`, for example
+when you have multiple builders in the same template.
+
+Here is a full list of the available functions for reference.
+
+- `build_name` - The name of the build being run.
+- `build_type` - The type of the builder being used currently.
+- `clean_resource_name` - Image names can only contain certain characters and
+ have a maximum length, eg 63 on GCE & 80 on Azure. `clean_resource_name`
+ will convert upper cases to lower cases and replace illegal characters with
+ a "-" character. Example:
+
+ `"mybuild-{{isotime | clean_resource_name}}"` will become `mybuild-2017-10-18t02-06-30z`.
+
+ Note: Valid Azure image names must match the regex
+ `^[^_\\W][\\w-._)]{0,79}$`
+
+ Note: Valid GCE image names must match the regex
+ `(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)`
+
+ This engine does not guarantee that the final image name will match the
+ regex; it will not truncate your name if it exceeds the maximum number of
+ allowed characters, and it will not validate that the beginning and end of
+ the engine's output are valid. For example, `"image_name": {{isotime | clean_resource_name}}"` will cause your build to fail because the image
+ name will start with a number, which is why in the above example we prepend
+ the isotime with "mybuild".
+ Exact behavior of `clean_resource_name` will depend on which builder it is
+ being applied to; refer to build-specific docs below for more detail on how
+ each function will behave.
+
+- `env` - Returns environment variables. See example in [using home
+ variable](/packer/docs/templates/legacy_json_templates/user-variables#using-home-variable)
+- `build` - This engine will allow you to access, from provisioners and post-processors, special variables that
+ provide connection information and basic instance state information.
+ Usage example:
+
+ ```json
+ {
+ "type": "shell-local",
+ "environment_vars": ["TESTVAR={{ build `PackerRunUUID`}}"],
+ "inline": ["echo $TESTVAR"]
+ }
+ ```
+
+ Valid variables to request are:
+
+ - **ID**: Represents the VM being provisioned. For example, in Amazon it is the instance ID; in DigitalOcean,
+ it is the Droplet ID; in VMware, it is the VM name.
+
+ - **Host**, **Port**, **User** and **Password**: The host, port, user, and password that Packer uses to access the machine.
+ Useful for using the shell local provisioner to run Ansible or Inspec against the provisioned instance.
+
+ - **ConnType**: Type of communicator being used. For example, for SSH communicator this will be "ssh".
+
+ - **PackerRunUUID**: Current build's unique ID. Can be used to specify build artifacts.
+ An example of that, is when multiple builds runs at the same time producing the same artifact.
+ It's possible to differentiate these artifacts by naming them with the builds' unique IDs.
+
+ - **PackerHTTPIP**, **PackerHTTPPort**, and **PackerHTTPAddr**: HTTP IP, port, and address of the file server Packer creates to serve items in the "http" dir to the VM. The HTTP address is displayed in the format `IP:PORT`.
+
+ - **SSHPublicKey** and **SSHPrivateKey**: The public and private key that Packer uses to connect to the instance.
+ These are unique to the SSH communicator and are unset when using other communicators.
+ **SSHPublicKey** and **SSHPrivateKey** can have escape sequences and special characters so their output should be single quoted to avoid surprises. For example:
+
+ ```json
+ { ... "provisioners": [{
+ "type": "shell",
+ "inline": [ "echo '{{ build `SSHPrivateKey`}}' > /tmp/packer-session.pem" ]
+ }]
+ }
+ ```
+
+ For backwards compatibility, `WinRMPassword` is also available through this
+ engine, though it is no different than using the more general `Password`.
+
+ This function is only for use within specific options inside of
+ _provisioners_ -- these options will be listed as being template engines
+ in the provisioner documentation.
+
+ For builder-specific builder variables, please also refer to the builder docs:
+
+ - Amazon EC2: [chroot](/packer/plugins/builders/amazon/chroot#build-shared-information-variables),
+ [EBS Volume](/packer/plugins/builders/amazon/ebsvolume#build-shared-information-variables),
+ [EBS](/packer/plugins/builders/amazon/ebs#build-shared-information-variables),
+ [EBS Surrogate](/packer/plugins/builders/amazon/ebssurrogate#build-shared-information-variables),
+ [Instance](/packer/plugins/builders/amazon/instance#build-shared-information-variables).
+
+ This engine is in beta; please report any issues or requests on the Packer
+ issue tracker on GitHub.
+
+- `isotime [FORMAT]` - UTC time, which can be
+ [formatted](https://pkg.go.dev/time#example_Time_Format). See more
+ examples below in [the `isotime` format
+ reference](/packer/docs/templates/legacy_json_templates/engine#isotime-function-format-reference).
+ `strftime FORMAT` - UTC time, formated using the ISO C standard format
+ `FORMAT`. See
+ [jehiah/go-strftime](https://github.com/jehiah/go-strftime) for a list
+ of available format specifiers.
+
+ Please note that if you are using a large number of builders,
+ provisioners or post-processors, using the isotime engine directly in the
+ plugin configuration may cause the timestamp to be slightly diffferent for
+ each plugin. This is because the timestamp is generated when each plugin is
+ launched rather than in the initial Packer process. In order to avoid this
+ and make sure the timestamp is consistent across all plugins, set it as a user
+ variable and then access the user variable within your plugins.
+
+- `lower` - Lowercases the string.
+- `packer_version` - Returns Packer version.
+- `pwd` - The working directory while executing Packer.
+- `replace` - ( old, new string, n int, s ) Replace returns a copy of the
+ string s with the first n non-overlapping instances of old replaced by new.
+- `replace_all` - ( old, new string, s ) ReplaceAll returns a copy of the
+ string s with all non-overlapping instances of old replaced by new.
+- `split` - Split an input string using separator and return the requested
+ substring.
+- `template_dir` - The directory to the template for the build.
+- `timestamp` - The Unix timestamp in UTC when the Packer process was
+ launched. Please note that if you are using a large number of builders,
+ provisioners or post-processors, the timestamp may be slightly
+ different for each one because it is from when the plugin is
+ launched not the initial Packer process. In order to avoid this and make
+ the timestamp consistent across all plugins, set it as a user variable
+ and then access the user variable within your plugins.
+- `uuid` - Returns a random UUID.
+- `upper` - Uppercases the string.
+- `user` - Specifies a user variable.
+
+#### Specific to Amazon builders:
+
+- `clean_resource_name` - AMI names
+ can only contain certain characters. This function will replace illegal
+ characters with a '-" character. Example usage since ":" is not a legal AMI
+ name is: `{{isotime | clean_resource_name}}`.
+
+#### Specific to Google Compute builders:
+
+- `clean_resource_name` - GCE
+ image names can only contain certain characters and the maximum length is
+
+ 63. This function will convert upper cases to lower cases and replace
+ illegal characters with a "-" character. Example:
+
+ `"mybuild-{{isotime | clean_resource_name}}"` will become
+ `mybuild-2017-10-18t02-06-30z`.
+
+ Note: Valid GCE image names must match the regex
+ `(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)`
+
+ This engine does not guarantee that the final image name will match the
+ regex; it will not truncate your name if it exceeds 63 characters, and it
+ will not validate that the beginning and end of the engine's output are
+ valid. For example, `"image_name": {{isotime | clean_resource_name}}"` will
+ cause your build to fail because the image name will start with a number,
+ which is why in the above example we prepend the isotime with "mybuild".
+
+#### Specific to Azure builders:
+
+- `clean_resource_name` - Azure
+ managed image names can only contain certain characters and the maximum
+ length is 80. This function will replace illegal characters with a "-"
+ character. Example:
+
+ `"mybuild-{{isotime | clean_resource_name}}"` will become
+ `mybuild-2017-10-18t02-06-30z`.
+
+ Note: Valid Azure image names must match the regex
+ `^[^_\\W][\\w-._)]{0,79}$`
+
+ This engine does not guarantee that the final image name will match the
+ regex; it will not truncate your name if it exceeds 80 characters, and it
+ will not validate that the beginning and end of the engine's output are
+ valid. It will truncate invalid characters from the end of the name when
+ converting illegal characters. For example, `"managed_image_name: "My-Name::"` will be converted to `"managed_image_name: "My-Name"`
+
+## Template variables
+
+Template variables are special variables automatically set by Packer at build
+time. Some builders, provisioners and other components have template variables
+that are available only for that component. Template variables are recognizable
+because they're prefixed by a period, such as `{{ .Name }}`. For example, when
+using the [`shell`](/packer/plugins/builders/vmware/iso) builder template variables
+are available to customize the
+[`execute_command`](/packer/docs/provisioners/shell#execute_command) parameter
+used to determine how Packer will run the shell command.
+
+```json
+{
+ "provisioners": [
+ {
+ "type": "shell",
+ "execute_command": "{{.Vars}} sudo -E -S bash '{{.Path}}'",
+ "scripts": ["scripts/bootstrap.sh"]
+ }
+ ]
+}
+```
+
+The `{{ .Vars }}` and `{{ .Path }}` template variables will be replaced with
+the list of the environment variables and the path to the script to be executed
+respectively.
+
+-> **Note:** In addition to template variables, you can specify your own
+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
+
+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.
+
+Full docs and examples for the Go time formatting function can be found
+[here](https://pkg.go.dev/time#example_Time_Format)
+
+However, the formatting basics are worth describing here. From the [Go docs](https://pkg.go.dev/time#pkg-constants):
+
+> These are predefined layouts for use in Time.Format and time.Parse. The
+> reference time used in the layouts is the specific time:
+>
+> Mon Jan 2 15:04:05 MST 2006
+>
+> which is Unix time 1136239445. Since MST is GMT-0700, the reference time
+> can be thought of as
+>
+> 01/02 03:04:05PM '06 -0700
+>
+> To define your own format, write down what the reference time would look like
+> formatted your way; see the values of constants like ANSIC, StampMicro or
+> Kitchen for examples. The model is to demonstrate what the reference time
+> looks like so that the Format and Parse methods can apply the same
+> transformation to a general time value.
+
+So what does that look like in a Packer template function? Here's an example
+of how you'd declare a variable using the isotime function.
+
+```json
+"variables": {
+ "myvar": "packer-{{isotime `2006-01-02 03:04:05`}}"
+}
+```
+
+You can try and modify the following examples in a packer template or in
+`packer console` to get an idea of how to set different timestamps:
+
+| Input | Output |
+| ------------------------------------------------ | ---------------------------- |
+| `` "packer-{{isotime `2006-01-02`}}" `` | "packer-2021-05-17" |
+| `` "packer-{{isotime `Jan-_2-15:04:05.000`}}" `` | "packer-May-17-23:40:16.786" |
+| `` "packer-{{isotime `3:04PM`}}" `` | "packer-11:40PM" |
+| `"{{ isotime }}"` | "June 7, 7:22:43pm 2014" |
+| `` "{{isotime `2006-01-02`}}" `` | "2014-06-07" |
+| `` "{{isotime `Mon 1504`}}" `` | "Sat 1922" |
+| `` "{{isotime `02-Jan-06 03\_04\_05`}}" `` | "07-Jun-2014 07_22_43" |
+| `` "{{isotime `Hour15Year200603`}}" `` | "Hour19Year201407" |
+
+Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
+15:04:05 -0700 MST 2006**, which breaks down to the following:
+
+
+
+
+
+
Day of Week
+
Month
+
Date
+
Hour
+
Minute
+
Second
+
Year
+
Timezone
+
+
+
+
Numeric
+
-
+
01
+
02
+
03 (15)
+
04
+
05
+
06
+
-0700
+
+
+
Textual
+
Monday (Mon)
+
January (Jan)
+
-
+
-
+
-
+
-
+
-
+
MST
+
+
+
+_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
+
+The function `split` takes an input string, a seperator string, and a numeric
+component value and returns the requested substring.
+
+Please note that you cannot use the `split` function on user variables, because
+we can't nest the functions currently. This function is intended to be used on
+builder variables like build_name. If you need a split user variable, the best
+way to do it is to create a separate variable.
+
+Here are some examples using the above options:
+
+```liquid
+build_name = foo-bar-provider
+
+{{split build_name "-" 0}} = foo
+{{split "fixed-string" "-" 1}} = string
+```
+
+Please note that double quote characters need escaping inside of templates (in
+this case, on the `fixed-string` value):
+
+```json
+{
+ "post-processors": [
+ [
+ {
+ "type": "vagrant",
+ "compression_level": 9,
+ "keep_input_artifact": false,
+ "vagrantfile_template": "tpl/{{split build_name \"-\" 1}}.rb",
+ "output": "output/{{build_name}}.box",
+ "only": ["org-name-provider"]
+ }
+ ]
+ ]
+}
+```
+
+# replace Function Format Reference
+
+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
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/index.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/index.mdx
new file mode 100644
index 0000000000..3a01ca7a5b
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/index.mdx
@@ -0,0 +1,183 @@
+---
+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
+---
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+# JSON Templates
+
+These Packer 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.
+
+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.
+
+## JSON Template Structure
+
+The template is a JSON object that has a set of keys configuring various
+components of Packer. The available keys within a template are listed below.
+Along with each key, it is noted whether it is required or not.
+
+- `builders` (_required_) is an array of one or more objects that defines the
+ builders that will be used to create machine images for this template, and
+ configures each of those builders. For more information on how to define
+ and configure a builder, read the sub-section on [configuring builders in
+ templates](/packer/docs/templates/legacy_json_templates/builders).
+
+- `description` (optional) is a string providing a description of what the
+ template does. This output is used only in the [inspect
+ command](/packer/docs/commands/inspect).
+
+- `min_packer_version` (optional) is a string that has a minimum Packer
+ version that is required to parse the template. This can be used to ensure
+ that proper versions of Packer are used with the template. A max version
+ can't be specified because Packer retains backwards compatibility with
+ `packer fix`.
+
+- `post-processors` (optional) is an array of one or more objects that
+ defines the various post-processing steps to take with the built images. If
+ not specified, then no post-processing will be done. For more information
+ on what post-processors do and how they're defined, read the sub-section on
+ [configuring post-processors in
+ templates](/packer/docs/templates/legacy_json_templates/post-processors).
+
+- `provisioners` (optional) is an array of one or more objects that defines
+ the provisioners that will be used to install and configure software for
+ the machines created by each of the builders. If it is not specified, then
+ no provisioners will be run. For more information on how to define and
+ configure a provisioner, read the sub-section on [configuring provisioners
+ in templates](/packer/docs/templates/legacy_json_templates/provisioners).
+
+- `variables` (optional) is an object of one or more key/value strings that
+ defines user variables contained in the template. If it is not specified,
+ then no variables are defined. For more information on how to define and
+ use user variables, read the sub-section on [user variables in
+ templates](/packer/docs/templates/legacy_json_templates/user-variables).
+
+## Comments
+
+JSON doesn't support comments and Packer reports unknown keys as validation
+errors. If you'd like to comment your template, you can prefix a _root level_
+key with an underscore. Example:
+
+```json
+{
+ "_comment": "This is a comment",
+ "builders": [{}]
+}
+```
+
+**Important:** Only _root level_ keys can be underscore prefixed. Keys within
+builders, provisioners, etc. will still result in validation errors.
+
+-> **Note:** Packer supports HCL2 from version 1.6.0. The HashiCorp
+Configuration Language does support comments anywhere in template files.
+If comments are important to you, consider upgrading your
+JSON template to HCL2 using the `packer hcl2_upgrade` command.
+
+One workaround if you are not ready to upgrade to HCL is to use jq to strip
+unsupported comments from a Packer template before you run `packer build`.
+
+For example, here is a file named `commented_template.json`:
+
+```json
+{
+ "_comment": ["this is", "a multi-line", "comment"],
+ "builders": [
+ {
+ "_comment": "this is a comment inside a builder",
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "_comment": "this is a root level comment",
+ "provisioners": [
+ {
+ "_comment": "this is a different comment",
+ "type": "shell",
+ "_comment": "this is yet another comment",
+ "inline": ["echo hellooooo"]
+ }
+ ]
+}
+```
+
+If you use the following jq command:
+
+```shell-session
+$ jq 'walk(if type == "object" then del(._comment) else . end)' commented_template.json > uncommented_template.json
+```
+
+The tool will produce a new file containing:
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell",
+ "inline": ["echo hellooooo"]
+ }
+ ]
+}
+```
+
+Once you've got your uncommented file, you can call `packer build` on it like
+you normally would.
+
+If your install of jq does not have the walk function and you get an error like
+
+```text
+jq: error: walk/1 is not defined at ,
+```
+
+You can create a file `~/.jq` and add the [walk function](https://github.com/stedolan/jq/blob/ad9fc9f559e78a764aac20f669f23cdd020cd943/src/builtin.jq#L255-L262) to it by hand.
+
+## Example Template
+
+Below is an example of a basic template that could be invoked with
+`packer build`. It would create an instance in AWS, and once running copy a
+script to it and run that script using SSH.
+
+-> **Note:** This example requires an account with Amazon Web Services.
+There are a number of parameters which need to be provided for a functional
+build to take place. See the [Amazon builder](/packer/plugins/builders/amazon)
+documentation for more information.
+
+```json
+{
+ "builders": [
+ {
+ "type": "amazon-ebs",
+ "access_key": "...",
+ "secret_key": "...",
+ "region": "us-east-1",
+ "source_ami": "ami-fce3c696",
+ "instance_type": "t2.micro",
+ "ssh_username": "ubuntu",
+ "ami_name": "packer {{timestamp}}"
+ }
+ ],
+
+ "provisioners": [
+ {
+ "type": "shell",
+ "script": "setup_things.sh"
+ }
+ ]
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/post-processors.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/post-processors.mdx
new file mode 100644
index 0000000000..b694d8eb43
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/post-processors.mdx
@@ -0,0 +1,175 @@
+---
+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
+---
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+# Template Post-Processors
+
+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.
+
+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:
+
+```json
+{
+ "post-processors": [
+ // ... one or more post-processor definitions here
+ ]
+}
+```
+
+For each post-processor definition, Packer will take the result of each of the
+defined builders and send it through the post-processors. This means that if
+you have one post-processor defined and two builders defined in a template, the
+post-processor will run twice (once for each builder), by default. There are
+ways, which will be covered later, to control what builders post-processors
+apply to, if you wish. It is also possible to prevent a post-processor from
+running.
+
+## Post-Processor Definition
+
+Within the `post-processors` array in a template, there are three ways to
+define a post-processor. There are _simple_ definitions, _detailed_
+definitions, and _sequence_ definitions. Another way to think about this is
+that the "simple" and "detailed" definitions are shortcuts for the "sequence"
+definition.
+
+A **simple definition** is just a string; the name of the post-processor. An
+example is shown below. Simple definitions are used when no additional
+configuration is needed for the post-processor.
+
+```json
+{
+ "post-processors": ["compress"]
+}
+```
+
+A **detailed definition** is a JSON object. It is very similar to a builder or
+provisioner definition. It contains a `type` field to denote the type of the
+post-processor, but may also contain additional configuration for the
+post-processor. A detailed definition is used when additional configuration is
+needed beyond simply the type for the post-processor. An example is shown
+below.
+
+```json
+{
+ "post-processors": [
+ {
+ "type": "compress",
+ "format": "tar.gz"
+ }
+ ]
+}
+```
+
+A **sequence definition** is a JSON array comprised of other **simple** or
+**detailed** definitions. The post-processors defined in the array are run in
+order, with the artifact of each feeding into the next, and any intermediary
+artifacts being discarded. A sequence definition may not contain another
+sequence definition. Sequence definitions are used to chain together multiple
+post-processors. An example is shown below, where the artifact of a build is
+compressed then uploaded, but the compressed result is not kept.
+
+It is very important that any post processors that need to be run in order, be
+sequenced!
+
+```json
+{
+ "post-processors": [
+ ["compress", { "type": "upload", "endpoint": "http://example.com" }]
+ ]
+}
+```
+
+As you may be able to imagine, the **simple** and **detailed** definitions are
+simply shortcuts for a **sequence** definition of only one element.
+
+## Input Artifacts
+
+When using post-processors, the input artifact (coming from a builder or
+another post-processor) is discarded by default after the post-processor runs.
+This is because generally, you don't want the intermediary artifacts on the way
+to the final artifact created.
+
+In some cases, however, you may want to keep the intermediary artifacts. You
+can tell Packer to keep these artifacts by setting the `keep_input_artifact`
+configuration to `true`. An example is shown below:
+
+```json
+{
+ "post-processors": [
+ {
+ "type": "compress",
+ "keep_input_artifact": true
+ }
+ ]
+}
+```
+
+This setting will only keep the input artifact to _that specific_
+post-processor. If you're specifying a sequence of post-processors, then all
+intermediaries are discarded by default except for the input artifacts to
+post-processors that explicitly state to keep the input artifact.
+
+-> **Note:** The intuitive reader may be wondering what happens if multiple
+post-processors are specified (not in a sequence). Does Packer require the
+configuration to keep the input artifact on all the post-processors? The answer
+is no, of course not. Packer is smart enough to figure out that at least one
+post-processor requested that the input be kept, so it will keep it around.
+
+## Run on Specific Builds
+
+You can use the `only` or `except` fields to run a post-processor only with
+specific builds. These two fields do what you expect: `only` will only run the
+post-processor on the specified builds and `except` will run the post-processor
+on anything other than the specified builds. A sequence of post-processors will
+execute until a skipped post-processor.
+
+An example of `only` being used is shown below, but the usage of `except` is
+effectively the same. `only` and `except` can only be specified on "detailed"
+fields. If you have a sequence of post-processors to run, `only` and `except`
+will affect that post-processor and stop the sequence.
+
+The `-except` option can specifically skip a named post processor. The `-only`
+option _ignores_ post-processors.
+
+```json
+([
+ {
+ "name": "vbox",
+ "type": "vagrant",
+ "only": ["virtualbox-iso"]
+ },
+ {
+ "type": "compress"
+ }
+],
+[
+ "compress",
+ {
+ "type": "upload",
+ "endpoint": "http://example.com"
+ }
+])
+```
+
+The values within `only` or `except` are _build names_, not builder types.
+Name is a required block label in HCL, but in legacy JSON, build names default
+to the types of their builders (e.g. `docker` or `amazon-ebs` or
+`virtualbox-iso`), unless a specific `name` attribute is specified within the
+configuration.
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/provisioners.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/provisioners.mdx
new file mode 100644
index 0000000000..5ecf660239
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/provisioners.mdx
@@ -0,0 +1,220 @@
+---
+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
+---
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+# Template Provisioners
+
+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.
+
+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.
+
+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.
+
+Within a template, a section of provisioner definitions looks like this:
+
+```json
+{
+ "provisioners": [
+ // ... one or more provisioner definitions here
+ ]
+}
+```
+
+For each of the definitions, Packer will run the provisioner for each of the
+configured builds. The provisioners will be run in the order they are defined
+within the template.
+
+## Provisioner Definition
+
+A provisioner definition is a JSON object that must contain at least the `type`
+key. This key specifies the name of the provisioner to use. Additional keys
+within the object are used to configure the provisioner, with the exception of
+a handful of special keys, covered later.
+
+As an example, the "shell" provisioner requires a key such as `script` which
+specifies a path to a shell script to execute within the machines being
+created.
+
+An example provisioner definition is shown below, configuring the shell
+provisioner to run a local script within the machines:
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh"
+}
+```
+
+## Run on Specific Builds
+
+You can use the `only` or `except` configurations to run a provisioner only
+with specific builds. These two configurations do what you expect: `only` will
+only run the provisioner on the specified builds and `except` will run the
+provisioner on anything other than the specified builds.
+
+An example of `only` being used is shown below, but the usage of `except` is
+effectively the same:
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh",
+ "only": ["virtualbox-iso"]
+}
+```
+
+The values within `only` or `except` are _build names_, not builder types. If
+you recall, build names by default are just their builder type, but if you
+specify a custom `name` parameter, then you should use that as the value
+instead of the type.
+Values within `except` could also be a _post-processor_ name.
+
+## On Error Provisioner
+
+You can optionally create a single specialized provisioner field called an
+`error-cleanup-provisioner`. This provisioner will not run unless the normal
+provisioning run fails. If the normal provisioning run does fail, this special
+error provisioner will run _before the instance is shut down_. This allows you
+to make last minute changes and clean up behaviors that Packer may not be able
+to clean up on its own.
+
+For examples, users may use this provisioner to make sure that the instance is
+properly unsubscribed from any services that it connected to during the build
+run.
+
+Toy usage example for the error cleanup script:
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell-local",
+ "inline": ["exit 2"]
+ }
+ ],
+ "error-cleanup-provisioner": {
+ "type": "shell-local",
+ "inline": ["echo 'rubber ducky'> ducky.txt"]
+ }
+}
+```
+
+## Build-Specific Overrides
+
+While the goal of Packer is to produce identical machine images, it sometimes
+requires periods of time where the machines are different before they
+eventually converge to be identical. In these cases, different configurations
+for provisioners may be necessary depending on the build. This can be done
+using build-specific overrides.
+
+An example of where this might be necessary is when building both an EC2 AMI
+and a VMware machine. The source EC2 AMI may setup a user with administrative
+privileges by default, whereas the VMware machine doesn't have these
+privileges. In this case, the shell script may need to be executed differently.
+Of course, the goal is that hopefully the shell script converges these two
+images to be identical. However, they may initially need to be run differently.
+
+This example is shown below:
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh",
+ "override": {
+ "vmware-iso": {
+ "execute_command": "echo 'password' | sudo -S bash {{.Path}}"
+ }
+ }
+}
+```
+
+As you can see, the `override` key is used. The value of this key is another
+JSON object where the key is the name of a [builder
+definition](/packer/docs/templates/legacy_json_templates/builders). The value of this is in turn
+another JSON object. This JSON object simply contains the provisioner
+configuration as normal. This configuration is merged into the default
+provisioner configuration.
+
+## Pausing Before Running
+
+With certain provisioners it is sometimes desirable to pause for some period of
+time before running it. Specifically, in cases where a provisioner reboots the
+machine, you may want to wait for some period of time before starting the next
+provisioner.
+
+Every provisioner definition in a Packer template can take a special
+configuration `pause_before` that is the amount of time to pause before running
+that provisioner. By default, there is no pause. An example is shown below:
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh",
+ "pause_before": "10s"
+}
+```
+
+For the above provisioner, Packer will wait 10 seconds before uploading and
+executing the shell script.
+
+## Retry on error
+
+With certain provisioners it is sometimes desirable to retry when it fails.
+Specifically, in cases where the provisioner depends on external processes that are not done yet.
+
+Every provisioner definition in a Packer template can take a special
+configuration `max_retries` that is the maximum number of times a provisioner will retry on error.
+By default, there `max_retries` is zero and there is no retry on error. An example is shown below:
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh",
+ "max_retries": 5
+}
+```
+
+For the above provisioner, Packer will retry maximum five times until stops failing.
+If after five retries the provisioner still fails, then the complete build will fail.
+
+## Timeout
+
+Sometimes a command can take much more time than expected
+
+Every provisioner definition in a Packer template can take a special
+configuration `timeout` that is the amount of time to wait before
+considering that the provisioner failed. By default, there is no timeout. An
+example is shown below:
+
+```json
+{
+ "type": "shell",
+ "script": "script.sh",
+ "timeout": "5m"
+}
+```
+
+For the above provisioner, Packer will cancel the script if it takes more than
+5 minutes.
+
+Timeout has no effect in debug mode.
diff --git a/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/user-variables.mdx b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/user-variables.mdx
new file mode 100644
index 0000000000..b3c00d620f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/templates/legacy_json_templates/user-variables.mdx
@@ -0,0 +1,423 @@
+---
+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
+---
+
+`@include 'from-1.5/legacy-json-warning.mdx'`
+
+# Template User Variables
+
+User variables allow your templates to be further configured 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
+templates. This maximizes the portability of the template.
+
+Using user variables expects you to know how [configuration
+templates](/packer/docs/templates/legacy_json_templates/engine) work. If you don't know how
+configuration templates work yet, please read that page first.
+
+## Usage
+
+In order to set a user variable, you must define it either within the
+`variables` section within your template, or using the command-line `-var` or
+`-var-file` flags.
+
+Even if you want a user variable to default to an empty string, it is best to
+explicitly define it. This explicitness helps reduce the time it takes for
+newcomers to understand what can be modified using variables in your template.
+
+The `variables` section is a key/value mapping of the user variable name to a
+default value. A default value can be the empty string. An example is shown
+below:
+
+```json
+{
+ "variables": {
+ "aws_access_key": "",
+ "aws_secret_key": ""
+ },
+
+ "builders": [
+ {
+ "type": "amazon-ebs",
+ "access_key": "{{user `aws_access_key`}}",
+ "secret_key": "{{user `aws_secret_key`}}"
+ // ...
+ }
+ ]
+}
+```
+
+In the above example, the template defines two user variables: `aws_access_key`
+and `aws_secret_key`. They default to empty values. Later, the variables are
+used within the builder we defined in order to configure the actual keys for
+the Amazon builder.
+
+If the default value is `null`, then the user variable will be _required_. This
+means that the user must specify a value for this variable or template
+validation will fail.
+
+User variables are used by calling the `{{user}}` function in the form of
+`{{user 'variable'}}`. This function can be used in _any value_ but `type`
+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 can be used within your template using user variables.
+The `env` function is available _only_ within the default value of a user
+variable, allowing you to default a user variable to an environment variable.
+An example is shown below:
+
+```json
+{
+ "variables": {
+ "my_secret": "{{env `MY_SECRET`}}"
+ }
+}
+```
+
+This will default "my_secret" to be the value of the "MY_SECRET" environment
+variable (or an empty string if it does not exist).
+
+-> **Why can't I use environment variables elsewhere?** User variables are
+the single source of configurable input to a template. We felt that having
+environment variables used _anywhere_ in a template would confuse the user
+about the possible inputs to a template. By allowing environment variables only
+within default values for user variables, user variables remain as the single
+source of input to a template that a user can easily discover using
+`packer inspect`.
+
+-> **Why can't I use `~` for home variable?** `~` is an special variable
+that is evaluated by shell during a variable expansion. As Packer doesn't run
+inside a shell, it won't expand `~`.
+
+## Consul keys
+
+Consul keys can be used within your template using the `consul_key` function.
+This function is available _only_ within the default value of a user variable,
+for reasons similar to environment variables above.
+
+```json
+{
+ "variables": {
+ "soft_versions": "{{ consul_key `my_image/softs_versions/next` }}"
+ }
+}
+```
+
+This will default `soft_versions` to the value of the key
+`my_image/softs_versions/next` in consul.
+
+The configuration for consul (address, tokens, ...) must be specified as
+environment variables, as specified in the
+[Documentation](/consul/docs/commands#environment-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_
+within the default value of a user variable, allowing you to default a user
+variable to a vault secret.
+
+An example of using a v2 kv engine:
+
+If you store a value in vault using `vault kv put secret/hello foo=world`, you
+can access it using the following template engine:
+
+```json
+{
+ "variables": {
+ "my_secret": "{{ vault `/secret/data/hello` `foo`}}"
+ }
+}
+```
+
+which will assign "my_secret": "world"
+
+An example of using a v1 kv engine:
+
+If you store a value in vault using:
+
+ vault secrets enable -version=1 -path=secrets kv
+ vault kv put secrets/hello foo=world
+
+You can access it using the following template engine:
+
+ {
+ "variables": {
+ "VAULT_SECRETY_SECRET": "{{ vault `secrets/hello` `foo`}}"
+ }
+ }
+
+This example accesses the Vault path `secret/data/foo` and returns the value
+stored at the key `bar`, storing it as "my_secret".
+
+In order for this to work, you must set the environment variables `VAULT_TOKEN`
+and `VAULT_ADDR` to valid values.
+
+The api tool we use allows for more custom configuration of the Vault client via
+environment variables.
+
+The full list of available environment variables is:
+
+```text
+"VAULT_ADDR"
+"VAULT_AGENT_ADDR"
+"VAULT_CACERT"
+"VAULT_CAPATH"
+"VAULT_CLIENT_CERT"
+"VAULT_CLIENT_KEY"
+"VAULT_CLIENT_TIMEOUT"
+"VAULT_SKIP_VERIFY"
+"VAULT_NAMESPACE"
+"VAULT_TLS_SERVER_NAME"
+"VAULT_WRAP_TTL"
+"VAULT_MAX_RETRIES"
+"VAULT_TOKEN"
+"VAULT_MFA"
+"VAULT_RATE_LIMIT"
+```
+
+and detailed documentation for usage of each of those variables can be found
+[here](/vault/docs/commands#environment-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
+
+```json
+{
+ "variables": {
+ "password": "{{ aws_secretsmanager `globalpassword` }}"
+ }
+}
+```
+
+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
+
+```json
+{
+ "variables": {
+ "password": "{{ aws_secretsmanager `sample/app/password` }}"
+ }
+}
+```
+
+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
+
+```json
+{
+ "variables": {
+ "db_password": "{{ aws_secretsmanager `sample/app/passwords` `db` }}",
+ "api_key": "{{ aws_secretsmanager `sample/app/passwords` `api_key` }}"
+ }
+}
+```
+
+In order to use this function you have to configure valid AWS credentials using
+one of the following methods:
+
+- [Environment Variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
+- [CLI Configuration Files](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+- [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
+
+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
+`ami_regions`, which takes an array of regions that it will copy the AMI to.
+You can parameterize this by using a variable that is a list of regions, joined
+by a `,`. For example:
+
+```json
+{
+ "variables": {
+ "destination_regions": "us-west-1,us-west-2"
+ },
+ "builders": [
+ {
+ "ami_name": "packer-qs-{{timestamp}}",
+ "instance_type": "t2.micro",
+ "region": "us-east-1",
+ "source_ami_filter": {
+ "filters": {
+ "name": "*ubuntu-xenial-16.04-amd64-server-*",
+ "root-device-type": "ebs",
+ "virtualization-type": "hvm"
+ },
+ "most_recent": true,
+ "owners": ["099720109477"]
+ },
+ "ami_regions": "{{user `destination_regions`}}",
+ "ssh_username": "ubuntu",
+ "type": "amazon-ebs"
+ }
+ ]
+}
+```
+
+## Setting 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
+
+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
+above, we could build our template using the command below. The command is
+split across multiple lines for readability, but can of course be a single
+line.
+
+```shell-session
+$ packer build \
+ -var 'aws_access_key=foo' \
+ -var 'aws_secret_key=bar' \
+ template.json
+```
+
+As you can see, the `-var` flag can be specified multiple times in order to set
+multiple variables. Also, variables set later on the command-line override any
+earlier set variable of the same name.
+
+**warning** If you are calling Packer from cmd.exe, you should double-quote
+your variables rather than single-quoting them. For example:
+
+`packer build -var "aws_secret_key=foo" template.json`
+
+### From a 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
+those variables. An example JSON file may look like this:
+
+```json
+{
+ "aws_access_key": "foo",
+ "aws_secret_key": "bar"
+}
+```
+
+It is a single JSON object where the keys are variables and the values are the
+variable values. Assuming this file is in `variables.json`, we can build our
+template using the following command:
+
+```text
+On Linux :
+$ packer build -var-file=variables.json template.json
+On Windows :
+packer build -var-file variables.json template.json
+```
+
+The `-var-file` flag can be specified multiple times and variables from
+multiple files will be read and applied. As you'd expect, variables read from
+files specified later override a variable set earlier.
+
+Combining the `-var` and `-var-file` flags together also works how you'd
+expect. Variables set later in the command override variables set earlier. So,
+for example, in the following command with the above `variables.json` file:
+
+```shell-session
+$ packer build \
+ -var 'aws_access_key=bar' \
+ -var-file=variables.json \
+ -var 'aws_secret_key=baz' \
+ template.json
+```
+
+Results in the following variables:
+
+| Variable | Value |
+| -------------- | ----- |
+| aws_access_key | foo |
+| aws_secret_key | baz |
+
+# 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
+sensitive variables won't get printed to the logs by adding them to the
+"sensitive-variables" list within the Packer template:
+
+```json
+{
+ "variables": {
+ "my_secret": "{{env `MY_SECRET`}}",
+ "not_a_secret": "plaintext",
+ "foo": "bar"
+ },
+
+ "sensitive-variables": ["my_secret", "foo"],
+ ...
+}
+```
+
+The above snippet of code will function exactly the same as if you did not set
+"sensitive-variables", except that the Packer UI and logs will replace all
+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
+
+## Making 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
+do this by referencing the variable within a command that you execute. For
+example, here is how to make a `shell-local` provisioner only run if the
+`do_nexpose_scan` variable is non-empty.
+
+```json
+{
+ "type": "shell-local",
+ "command": "if [ ! -z \"{{user `do_nexpose_scan`}}\" ]; then python -u trigger_nexpose_scan.py; fi"
+}
+```
+
+## Using HOME Variable
+
+In order to use `$HOME` variable, you can create a `home` variable in Packer:
+
+```json
+{
+ "variables": {
+ "home": "{{env `HOME`}}"
+ }
+}
+```
+
+And this will be available to be used in the rest of the template, i.e.:
+
+```json
+{
+ "builders": [
+ {
+ "type": "google",
+ "account_file": "{{ user `home` }}/.secrets/gcp-{{ user `env` }}.json"
+ }
+ ]
+}
+```
diff --git a/content/packer/v1.10.x/content/docs/terminology.mdx b/content/packer/v1.10.x/content/docs/terminology.mdx
new file mode 100644
index 0000000000..31bee6ed6f
--- /dev/null
+++ b/content/packer/v1.10.x/content/docs/terminology.mdx
@@ -0,0 +1,64 @@
+---
+description: >
+ There are a handful of terms used throughout the Packer documentation where
+ the
+
+ meaning may not be immediately obvious if you haven't used Packer before.
+
+ Luckily, there are relatively few. This page documents all the terminology
+
+ required to understand and use Packer. The terminology is in alphabetical
+ order
+
+ for quick referencing.
+page_title: Terminology
+---
+
+# Packer Terminology
+
+There are a handful of terms used throughout the Packer documentation where the
+meaning may not be immediately obvious if you haven't used Packer before.
+Luckily, there are relatively few. This page documents all the terminology
+required to understand and use Packer. The terminology is in alphabetical order
+for quick referencing.
+
+- `Artifacts` are the results of a single build, and are usually a set of IDs
+ or files to represent a machine image. Every builder produces a single
+ artifact. As an example, in the case of the Amazon EC2 builder, the
+ artifact is a set of AMI IDs (one per region). For the VMware builder, the
+ artifact is a directory of files comprising the created virtual machine.
+
+- `Builds` are a single task that eventually produces an artifact for a single
+ platform. Multiple builds run in parallel. Example usage in a sentence:
+ "The Packer build produced an AMI to run our web application." Or: "Packer
+ is running the builds now for VMware, AWS, and VirtualBox."
+
+- `Builders` are components of Packer that are able to create a machine image
+ for a single platform. Builders read in some configuration and use that to
+ run and generate a machine image. A builder is invoked as part of a build
+ in order to create the actual resulting artifacts. Example builders include
+ VirtualBox, VMware, and Amazon EC2.
+
+- `Commands` are sub-commands for the `packer` program that perform some job.
+ An example command is "build", which is invoked as `packer build`. Packer
+ ships with a set of commands out of the box in order to define its
+ command-line interface.
+
+- `Data Sources` are components of Packer that fetch data from outside Packer
+ and make it available to use within the template.
+ Example of data sources include Amazon AMI, and Amazon Secrets Manager.
+
+- `Post-processors` are components of Packer that take the result of a
+ builder or another post-processor and process that to create a new
+ artifact. Examples of post-processors are compress to compress artifacts,
+ upload to upload artifacts, etc.
+
+- `Provisioners` are components of Packer that install and configure software
+ within a running machine prior to that machine being turned into a static
+ artifact. They perform the major work of making the artifact contain useful
+ software. Example provisioners include shell scripts, Chef, Puppet, etc.
+
+- `Templates` are either [HCL](https://packer.io/templates/hcl_templates) or JSON files which
+ define one or more builds by configuring the various components of Packer.
+ Packer is able to read a template and use that information to create
+ multiple machine images in parallel.
diff --git a/content/packer/v1.10.x/content/guides/1.7-plugin-upgrade.mdx b/content/packer/v1.10.x/content/guides/1.7-plugin-upgrade.mdx
new file mode 100644
index 0000000000..9739d05400
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/1.7-plugin-upgrade.mdx
@@ -0,0 +1,118 @@
+---
+page_title: Upgrading your plugin to use the Packer plugin sdk
+description: >-
+ Learn how to upgrade your plugin to support v1.7.0 and later.
+---
+
+# Upgrading your plugin to be compatible with Packer v1.7.0 and later
+
+In version v1.7.0 the Packer plugin development model was split into two separate packages: the Packer core
+and the Packer plugin SDK. Prior to version 1.7.0, the Packer core repository (https://github.com/hashicorp/packer) contained the libraries and interfaces used by Packer plugins. In version 1.7.0, these libraries were moved into their own repository (https://github.com/hashicorp/packer-plugin-sdk). If you authored a plugin prior to the v1.7.0 release using the API version 4, you should switch to the Packer Plugin SDK.
+
+## Update plugins to use the new SDK
+
+### Why update to the new SDK?
+
+The goal of the SDK is to clearly separate the Packer core from the Packer plugins; as a plugin maintainer, you should only have to import the SDK and not the core. The SDK will allow us to use semantic versioning to express the changes to the API that our maintainers are expected to use, and will help us keep a clearer promise to you about the location and functionality of our helper tools.
+
+### How to update plugins to use the Packer plugin SDK
+
+We have created a [packer-sdk-migrator](https://github.com/hashicorp/packer-sdk-migrator) cli tool to help you migrate your plugin to use the new import paths. To use it, follow the installation instructions for the migration tool, then call `packer-sdk-migrator migrate` from the root of your plugin directory. More details can be found in the migrator's [README](https://github.com/hashicorp/packer-sdk-migrator/blob/main/README.md).
+
+Once you have migrated your plugin to the new SDK, your users can continue using your plugin as they always have, manually installing it in their `plugins` directories. However, Packer v1.7 also introduced the `packer init` command, and since you're here anyway it's a great time to upgrade your plugin so it can be found by `packer init`. Keep reading for more details!
+
+## Upgrade Plugins to use the new multi-component RPC server
+
+### Why is there a new RPC server?
+
+There are two main reasons we wrote the new server type.
+
+First, it enables multiple related components, for example a builder and a post-processor that share a hypervisor or cloud, to live together in the same plugin. This helps maintainers who are experts in a specific technology to focus on that technology without having to maintain several repositories that submodule the same common code. You can think of a multi-component plugin as being in some ways analogous to Terraform providers, in the sense that both frequently bundle common resources or components by hypervisor or cloud.
+
+Second, the new server provides the Packer core with structured metadata that allows the new `packer init` feature to work. This data includes semantic versioning that we need to implement the new [`required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) block, which allows us to ensure that users are using the correct _version_ of their plugin for a given Packer template. If you don't upgrade, your users cannot take advantage of the `packer init` tooling.
+
+### How to upgrade the plugin
+
+We've created a [scaffolding repository](https://github.com/hashicorp/packer-plugin-scaffolding/) that you can either clone or use as a reference example. If you already have a working plugin, it should look pretty familiar. You'll notice, however, that there are some changes to main.go.
+
+Previously, you may have had a main.go that looks something like:
+
+```go
+package main
+
+import (
+ "github.com/hashicorp/packer-plugin-sdk/plugin"
+)
+
+func main() {
+ server, err := plugin.Server()
+ if err != nil {
+ panic(err)
+ }
+
+ // MyProvisioner fulfils the Provisioner interface and is defined elsewhere
+ server.RegisterProvisioner(new(MyProvisioner))
+ server.Serve()
+}
+
+```
+
+With this single-component plugin binary you'd install it by putting it into the plugin directory with the name `packer-provisioner-foo`, and to access your provisioner in your Packer template, you would use the type `foo`.
+
+To use the new multi-component server, you'll want to use the NewSet() function to create a server:
+
+```go
+package main
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/hashicorp/packer-plugin-sdk/plugin"
+)
+
+func main() {
+ pps := plugin.NewSet()
+ pps.RegisterProvisioner(plugin.DEFAULT_NAME, new(MyProvisioner))
+ err := pps.Run()
+ if err != nil {
+ fmt.Fprintln(os.Stderr, err.Error())
+ os.Exit(1)
+ }
+}
+
+```
+
+The implementation is similar, but now we use the "NewSet" function to create the component Server, and call Run() instead of Serve().
+
+You build it as you would any Go binary:
+
+```go
+go build -o packer-plugin-bar
+```
+
+Then you install it by putting it into the plugin directory with the name `packer-plugin-foo`, and reference it in your template using the type "foo".
+
+Notice that the new naming convention uses the generic name "plugin" as opposed to saying the specific component type like the old style did; `packer-pluign-name` instead of `packer-provisioner-name`. You need to respect this new convention when installing the plugin, or Packer will not register it as a multi-component plugin.
+
+What does that `plugin.DEFAULT_NAME` do? It tells the Packer core that in your template you'll be using the root plugin name instead of a compound name composed of the plugin name and the component name. If you are only serving a single component, you may want to use `plugin.DEFAULT_NAME` to prevent your templates from stuttering.
+
+Here's an example using a custom string instead of `plugin.DEFAULT_NAME`:
+
+```go
+pps.RegisterProvisioner("bar", new(MyProvisioner))
+```
+
+When you do this, if you install your plugin as `packer-plugin-foo`, the Packer core expects you to access the provisioner in your template using the type `foo-bar`, where "foo" is the last portion of the plugin name as installed and "bar" is the name of the provisioner that you registered.
+
+## Registering multiple components
+
+The goal of this guide is to help you upgrade a single-component plugin to use the new SDK and plugin server; check out our [Plugin Development Basics](/packer/docs/plugins/creation#plugin-development-basics) guide for details on how to add new components to your plugin.
+
+## Distributing migrated plugins
+
+Once a plugin has been migrated to use the `packer-plugin-sdk` it can be released as it normally would and used by Packer by [installing the plugin](/packer/docs/plugins#installing-plugins) manually into the Packer plugin directory. But this method will not allow your users to take advantage of the `packer init` command.
+
+If you want Packer to be able to automatically install your plugin for your users via`packer init` -- the preferred method of installation -- you need to make the plugin available on GitHub in a repository named after the multi-component plugin. `https://github.com//packer-plugin-name`. We recognize that this may require you to rename or fork your plugin repository, but we think that it is worth the inconvenience to reduce ambiguity in the `init` call.
+
+See our documentation on [Creating a GitHub Release](/packer/docs/plugins/creation#creating-a-github-release) for details on the recommended practice for releasing Packer plugins on GitHub.
diff --git a/content/packer/v1.10.x/content/guides/1.7-template-upgrade.mdx b/content/packer/v1.10.x/content/guides/1.7-template-upgrade.mdx
new file mode 100644
index 0000000000..19d862c258
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/1.7-template-upgrade.mdx
@@ -0,0 +1,185 @@
+---
+page_title: Upgrading your template to use Packer init
+description: >-
+ Use packer init and the required_plugins block to better control plugin usage within Packer templates. Learn how to update your template to work with these new features.
+---
+
+# Upgrading your template to be compatible with `packer init`
+
+The `packer init` command introduced in version v1.7.0 benefits Packer users by providing better control of plugin
+usage within a Packer template configuration.
+
+In short, `packer init` will look at the `required_plugins` block definition within a template, and download the correct
+binaries for that template. For details about how the command works and where the plugins will be installed, please
+refer to the [`packer init`](/packer/docs/commands/init) documentation.
+
+-> **Note:** `packer init` is only supported for HCL templates. You can
+upgrade legacy JSON templates to HCL using the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) command.
+
+## Updating your template with the `required_plugins` block
+
+## FAQs
+
+### Why do you need to upgrade your template?
+
+To use the `packer init` command, you must upgrade your template to use the `required_plugins` block. The `init` command
+won't work if no `required_plugins` is provided.
+
+We strongly encourage you to upgrade and start using `required_plugins` block within your templates to manage plugin
+installation, but if you prefer not to use the `required_plugins` block you can continue to
+[install plugins manually](/packer/docs/plugins#installing-plugins).
+
+### What if you only use components that are built into the Packer core?
+
+You don't need `packer init` for this, as of v1.7.0. But it's a good idea to get familiar with the required_plugins
+block anyway, because we are going to start splitting popular HashiCorp-maintained components like the amazon-ebs
+builder out of the core into their own multi-component plugins. When we do split these plugins out of the core, we will
+provide a tool to help you create the correct required_plugins block.
+
+### When should you upgrade your template?
+
+The `packer init` command can only install plugins that have been upgraded to use the latest version of the
+[Packer Plugin SDK](https://github.com/hashicorp/packer-plugin-sdk), and therefore are compatible with Packer's API
+version v5.0. The plugin repository on GitHub also needs to use a specific release format. If you are not sure whether
+the plugin you use fits those requirements, you can reach out to your maintainer to ask. You can also look for clues
+that the plugin is ready for use with `packer init`:
+
+- Check the plugin's CHANGELOG for notes about migrating to the packer-plugin-sdk.
+- Check the name of the repository the plugin resides in. Chances are that if the repository follows the naming
+ convention `packer-plugin-*` (e.g. `packer-plugin-comment`), then the plugin has been upgraded to be compatible with
+ `packer init`. If the repository has a name that references a specific Packer component (for example,
+ `packer-provisioner-*`, `packer-builder-*`, or `packer-post-processor-*`) then the plugin likely still needs to be
+ upgraded to be compatible with `packer init`. Reach out to your plugin maintainer to request that they upgrade; the
+ Packer team has written a maintainer-focused guide [here](/packer/guides/1.7-plugin-upgrade).
+
+If the plugin(s) have been upgraded, then they can be used with the `required_plugins` block in your upgraded template.
+
+#### What if the plugin you need is not upgraded to API v5.0?
+
+Since the SDK is being released at the same time as the `init` command, plugin users may face a gap between when the
+Packer core v1.7.0 is released, and the plugins you use are upgraded by their maintainers. The Packer team is getting
+in touch with all currently known plugin maintainers to provide support during their upgrade process.
+
+If you are willing to upgrade your template but found out that the plugin you are using hasn't been upgraded yet,
+we suggest you reach out to the plugin maintainers and ask for an upgrade; the Packer team has written a
+maintainer-focused guide [here](/packer/guides/1.7-plugin-upgrade).
+
+Check the table below to better understand whether your plugin is compatible with `packer init`, with manual
+installation, or with both for the Packer version you are using.
+
+| Packer Core Version | Single Component Plugin - API v4 | Single Component Plugin - API v5.0 | Multi Component Plugin - API v5.0 |
+| ------------------- | ------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------- |
+| v1.5.0 to v1.6.6 | ✋ Plugin must be manually installed | ⛔ Plugin cannot be used with this Packer version | ⛔ Plugin cannot be used with this Packer version |
+| v1.7.0 | ⛔ Plugin cannot be used with this Packer version | ✋ Plugin must be manually installed | 📦 Plugin can be installed manually or with `packer init` |
+
+### How to upgrade your template
+
+Let's use the following template as an example:
+
+```hcl
+# file: example.pkr.hcl
+
+source "null" "basic-example" {
+ communicator = "none"
+}
+
+build {
+ sources = ["sources.null.basic-example"]
+
+ provisioner "comment" {
+ comment = "Hello from comment plugin"
+ ui = true
+ bubble_text = true
+ }
+}
+```
+
+This template uses the example [packer-provisioner-comment](https://github.com/sylviamoss/packer-plugin-comment) plugin.
+Until Packer v1.7.0, the binaries were installed manually.
+
+Since the Packer v1.7.0 release, the plugin has been upgraded by its maintainers and is now called
+`packer-plugin-comment`. with its latest version being v0.2.23. Knowing that, our example template can be upgraded to
+use the `required_plugins` block.
+
+```hcl
+# file: example.pkr.hcl
+
+packer {
+ required_plugins {
+ comment = {
+ version = ">=v0.2.23"
+ source = "github.com/sylviamoss/comment"
+ }
+ }
+}
+
+source "null" "basic-example" {
+ communicator = "none"
+}
+
+build {
+ sources = ["sources.null.basic-example"]
+
+ provisioner "comment" {
+ comment = "Hello from comment plugin"
+ ui = true
+ bubble_text = true
+ }
+}
+```
+
+The upgraded template is now telling Packer that it requires a plugin named `comment` stored in a github repository
+owned by the user `sylviamoss`. It also says that the template needs to use a version of the plugin equal to or greater
+than `v0.2.23`. Finally, the local_name of the plugin will be `comment`, which means it will be referred to as `comment`
+in the rest of the template.
+
+Here it is a brief explanation of each field:
+
+- `version` - Should follow the [version constraints](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints).
+- `source` - Should have the GitHub hostname, the plugin's organizational namespace, and its short name.
+ Packer will be responsible for determining the full GitHub
+ address. For example, if the source is `github.com/sylviamoss/comment`, Packer
+ will download the binaries from `github.com/sylviamoss/packer-plugin-comment`.
+ To learn more about the source field, check out the [Source
+ Address](/packer/docs/plugins#source-addresses) documentation.
+- `local_name`- Can be replaced with whatever you want, and the new value will become the name of the plugin.
+ For example:
+
+ ```hcl
+ packer {
+ required_plugins {
+ bubbled_up = {
+ # ...
+ }
+ }
+ }
+
+ # ...
+
+ build {
+ # ...
+
+ provisioner "bubbled_up" {
+ # ...
+ }
+ }
+ ```
+
+Once the template is upgraded, you can run `packer init example.pkr.hcl` and the output should tell you the installed
+plugin, and the place where it was installed.
+
+```shell
+➜ packerdev init example.pkr.hcl
+Installed plugin sylviamoss/comment v0.2.23 in "/Users//.packer.d/plugins/github.com/sylviamoss/comment/packer-plugin-comment_v0.2.23_x5.0_darwin_amd64"
+```
+
+`packer init` will only download plugin binaries and never delete existing ones. If all the required plugins are installed,
+the command won't do anything unless you set the `-upgrade` flag to force download newer versions of the existing plugins.
+
+You can uninstall a plugin by deleting it from the `.packer.d/plugins/` directory on your computer.
+
+Now that the required comment plugin is installed via `packer init`, you can run `packer build example.pkr.hcl` as usual
+and won't need to run `init` again unless you want to upgrade the plugin version.
+
+A template with a `required_plugins` block should **always** be initialised at least once with `packer init` before
+`packer build`. If the template is built before init, Packer will fail and ask for initialisation.
diff --git a/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/autounattend_windows.mdx b/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/autounattend_windows.mdx
new file mode 100644
index 0000000000..e36354dd4a
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/autounattend_windows.mdx
@@ -0,0 +1,89 @@
+---
+page_title: Unattended Windows Installation
+description: |-
+ Learn how to use an autounattend file to automatically answer installation
+ questions and enable Packer to connect to your Windows instance.
+---
+
+# Unattended Installation for Windows
+
+Unattended Windows installation is done via "Answer Files", or "Unattend files".
+
+These files are generally named "autounattend.xml". They are not
+Packer-specific tools, though we do make use of them.
+
+If, after following this guide, you're still having issues getting an answer
+file working, We recommend you read the official documentation on
+[answer files](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/update-windows-settings-and-scripts-create-your-own-answer-file-sxs).
+
+The guide here is hopefully enough to get you started, but isn't a replacement
+for the official documentation.
+
+## When To Use an Answer File
+
+If you are installing the Windows Operating System from a mounted iso as part of
+your Packer build, you will need to use an Answer file. For example, you're
+building an image from scratch using the [vmware-iso](/packer/plugins/builders/vmware/iso),
+[virtualbox-iso](/packer/plugins/builders/virtualbox/iso), or
+[hyperv-iso](/packer/plugins/builders/hyperv/iso) builders.
+
+If you are not installing the operating system, you won't need to provide an
+answer file. If you are using a pre-built image
+in a cloud, you don't need to worry about Answer files.
+
+## How to make an Answer File
+
+You can either start from an example answer file from a known repo (take a look
+at the examples links below), or you can generate one using an answer file
+wizard by selecting New File > New Answer file on a Windows machine.
+A comprehensive list of all the options you can set in an answer file can be
+found [here](https://docs.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/components-b-unattend)
+
+## Where to put the Answer File
+
+Windows will automatically look for an autounattend.xml file on mounted drives.
+Many users use the `floppy_files` option or a secondary mounted iso for
+providing the answer file to their iso builders.
+
+You can also specify an unattend file to use by using the /unattend: option when
+running Windows Setup (setup.exe) in your `boot_command`.
+
+## What does Packer _need_ the Answer File to do?
+
+Packer needs the Answer File to handle any questions that would normally be
+answered interactively during a Windows installation.
+
+If you want to be able to use provisioners, the Answer file must also contain
+a script that sets up SSH or WinRM so that Packer can connect to the instance.
+
+Finally, your Packer build will be much smoother if the Answer File handles or
+disables Windows updates rather than you trying to run them using a Packer
+provisioner. This is because the winrm communicator does not handle the
+disconnects caused by automatic reboots in Windows updates well, and the
+disconnections can fail a build.
+
+## Examples
+
+The chef-maintained bento boxes are a great example of a Windows build that
+sets up openssh as part of the unattended installation so that Packer can
+connect using the SSH communicator. The functioning answer files for every
+modern Windows version can be found [here](https://github.com/chef/bento/tree/master/packer_templates/win_answer_files).
+
+Stefan Scherer's [packer-windows repo](https://github.com/StefanScherer/packer-windows)
+is a great example of Windows builds that set up WinRM as part of the unattended
+installation so that Packer can connect using the `winrm` communicator:
+
+```json
+{
+ "type": "virtualbox-iso",
+ "guest_os_type": "Windows2008_64",
+ "iso_url": "https://download.microsoft.com/download/7/5/E/75EC4E54-5B02-42D6-8879-D8D3A25FBEF7/7601.17514.101119-1850_x64fre_server_eval_en-us-GRMSXEVAL_EN_DVD.iso",
+ "iso_checksum": "sha256:30832AD76CCFA4CE48CCB936EDEFE02079D42FB1DA32201BF9E3A880C8ED6312",
+ "shutdown_command": "shutdown /s /t 10 /f /d p:4:1 /c Packer_Provisioning_Shutdown",
+ "guest_additions_mode": "attach",
+ "floppy_files": ["./scripts/Autounattend.xml", "./scripts/openssh.ps1"],
+ "communicator": "winrm",
+ "winrm_username": "vagrant",
+ "winrm_password": "vagrant"
+}
+```
diff --git a/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/index.mdx b/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/index.mdx
new file mode 100644
index 0000000000..872df2d9ea
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/index.mdx
@@ -0,0 +1,23 @@
+---
+page_title: Automatic OS Installs
+description: |-
+ Learn how to use preseed, kickstart, and autounattend files to automatically
+ answer installation questions and enable Packer to connect to your instance.
+---
+
+# Automatic OS Installs
+
+If you are building from a brand-new and unconfigured operating system
+image, Packer will need you to perform the operating system install before it
+can connect to and configure your image using its provisioners. Most operating
+system distributions have a mechanism for performing the normally-interactive
+installation in an automated way. For Debian operating systems, this is done
+using a preseed file; for Windows, it's done using an Autounattend.xml. We have
+compiled some simple guides here for common operating system distributions.
+
+These guides are meant to give you a quick introduction to how to use automated
+installation answer files in order to perfom those installs; we don't mean to
+be a comprehensive guide on each operating system, but we hope to give you
+enough context to be able to more easily find any further information you need.
+
+Refer to the instructions for your operating system.
diff --git a/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/preseed_ubuntu.mdx b/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/preseed_ubuntu.mdx
new file mode 100644
index 0000000000..c5c9ea2040
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/automatic-operating-system-installs/preseed_ubuntu.mdx
@@ -0,0 +1,176 @@
+---
+page_title: Unattended Debian/Ubuntu Installation
+description: |-
+ Learn how to use a preseed file to automatically answer installation
+ questions and enable Packer to connect to your Debian instance.
+---
+
+# Unattended Installation for Debian
+
+Unattended Debian/Ubuntu installation is done via "preseed" files
+
+These files are generally named "preseed.cfg". They are not
+Packer-specific tools, though we do make use of them.
+
+If, after following this guide, you're still having issues getting a preseed
+file working, We recommend you read the official documentation on
+[preseed files](https://wiki.debian.org/DebianInstaller/Preseed).
+
+The guide here is hopefully enough to get you started, but isn't a replacement
+for the official documentation.
+
+## When To Use a Preseed File
+
+If you are installing the operating system from a mounted iso as part of
+your Packer build, you will need to use a preseed file. For example, you're
+building an image from scratch using the [vmware-iso](/packer/plugins/builders/vmware/iso),
+[virtualbox-iso](/packer/plugins/builders/virtualbox/iso), or
+[hyperv-iso](/packer/plugins/builders/hyperv/iso) builders.
+
+If you are not installing the operating system, you won't need to provide a
+preseed file. If you are using a pre-built image in a cloud, you don't need to
+worry about preseed files.
+
+## How to make a Preseed File
+
+You can either start from an example preseed file from a known repo (take a look
+at the examples links below), or you can start with the official [example
+preseed](https://www.debian.org/releases/stable/example-preseed.txt), and
+comment or uncomment the options as you need them.
+
+## Where to put the preseed file
+
+The `-iso` builders mentioned above all have an `http_dir` or an `http_content`
+option. Any file inside of your `http_dir` or `http_content` will be served on a
+local fileserver for your virtual machine to be able to access. One very common
+use for this directory is to use it to provide your preseed file.
+
+You then reference the file using a `boot_command` to kick off the installation.
+In the example below, see how the `preseed/url` command line option is being
+used in the `/install/vmlinuz command`. The `{{ .HTTPIP }}` and
+`{{ .HTTPPort }}` options are special Packer template options that will get set
+by Packer to point to the HTTP server we create, so that your boot command can
+access it. For an example of a working boot_command, see the Examples section
+below. For more information on how boot_command works, see the
+boot_command section of the docs for whatever builder you are using.
+
+## What does Packer _need_ the preseed file to do?
+
+Packer needs the preseed file to handle any questions that would normally be
+answered interactively during a Debian installation.
+
+If you want to be able to use provisioners, the preseed file must also install
+SSH so that Packer can connect to the instance.
+
+## Examples
+
+A very minimal example of a preseed file can be found below. Much of this was
+copied from the official example-preseed shared above. Notice that we are
+installing ssh via `d-i pkgsel/include string openssh-server` and configuring
+a username so that Packer will be able to connect.
+
+You need to make sure that your mirror settings are properly configured for your
+specific distribution of Debian.
+
+```shell
+# Preseeding only locale sets language, country and locale.
+d-i debian-installer/locale string en_US
+
+# Keyboard selection.
+d-i console-setup/ask_detect boolean false
+d-i keyboard-configuration/xkb-keymap select us
+
+choose-mirror-bin mirror/http/proxy string
+
+### Clock and time zone setup
+d-i clock-setup/utc boolean true
+d-i time/zone string UTC
+
+# Avoid that last message about the install being complete.
+d-i finish-install/reboot_in_progress note
+
+# This is fairly safe to set, it makes grub install automatically to the MBR
+# if no other operating system is detected on the machine.
+d-i grub-installer/only_debian boolean true
+
+# This one makes grub-installer install to the MBR if it also finds some other
+# OS, which is less safe as it might not be able to boot that other OS.
+d-i grub-installer/with_other_os boolean true
+
+### Mirror settings
+# If you select ftp, the mirror/country string does not need to be set.
+d-i mirror/country string manual
+d-i mirror/http/directory string /ubuntu/
+d-i mirror/http/hostname string archive.ubuntu.com
+d-i mirror/http/proxy string
+
+### Partitioning
+d-i partman-auto/method string lvm
+
+# This makes partman automatically partition without confirmation.
+d-i partman-md/confirm boolean true
+d-i partman-partitioning/confirm_write_new_label boolean true
+d-i partman/choose_partition select finish
+d-i partman/confirm boolean true
+d-i partman/confirm_nooverwrite boolean true
+
+### Account setup
+d-i passwd/user-fullname string vagrant
+d-i passwd/user-uid string 1000
+d-i passwd/user-password password vagrant
+d-i passwd/user-password-again password vagrant
+d-i passwd/username string vagrant
+
+# The installer will warn about weak passwords. If you are sure you know
+# what you're doing and want to override it, uncomment this.
+d-i user-setup/allow-password-weak boolean true
+d-i user-setup/encrypt-home boolean false
+
+### Package selection
+tasksel tasksel/first standard
+d-i pkgsel/include string openssh-server build-essential
+d-i pkgsel/install-language-support boolean false
+
+# disable automatic package updates
+d-i pkgsel/update-policy select none
+d-i pkgsel/upgrade select full-upgrade
+```
+
+Here's an example of the vmware-iso builder being used to call this preseed.
+In this case, it is assumed that the file is saved as preseed.cfg inside of a
+directory called "http", and Packer is being called from the directory
+containing the "http" directory.
+
+```hcl
+ "builders": [
+ {
+ "boot_command": [
+ "",
+ "",
+ "",
+ "/install/vmlinuz",
+ " initrd=/install/initrd.gz",
+ " auto-install/enable=true",
+ " debconf/priority=critical",
+ " preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/preseed_2.cfg",
+ " -- ",
+ ""
+ ],
+ "boot_wait": "10s",
+ "guest_os_type": "ubuntu-64",
+ "http_directory": "http",
+ "iso_checksum": "file:///Users/mmarsh/dev/repro_cases/packer_cache/shasums.txt",
+ "iso_url": "http://old-releases.ubuntu.com/releases/14.04.1/ubuntu-14.04.1-server-amd64.iso",
+ "shutdown_command": "echo 'vagrant' | sudo -S shutdown -P now",
+ "ssh_password": "vagrant",
+ "ssh_username": "vagrant",
+ "ssh_wait_timeout": "10000s",
+ "tools_upload_flavor": "linux",
+ "type": "vmware-iso"
+ }
+ ],
+```
+
+For more functional examples of a debian preseeded installation, you can see the
+Chef-maintained bento boxes for [Debian](https://github.com/chef/bento/tree/master/packer_templates/debian)
+and [Ubuntu](https://github.com/chef/bento/tree/master/packer_templates/ubuntu)
diff --git a/content/packer/v1.10.x/content/guides/hcl/component-object-spec.mdx b/content/packer/v1.10.x/content/guides/hcl/component-object-spec.mdx
new file mode 100644
index 0000000000..9ca8c29a6b
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/hcl/component-object-spec.mdx
@@ -0,0 +1,41 @@
+---
+page_title: Generating code for config spec.
+description: Learn how to generate the HCL2 configuration of your component easily.
+---
+
+# Auto Generate the HCL2 code of a plugin
+
+From v1.5, Packer can be configured using HCL2. Because Packer has so many
+builders, provisioners, and post-processors, we created a on code generation
+tool to add the HCL2-enabling code more easily. You can use this code generator
+to create the HCL2 spec code of your custom plugin simply.
+It's a Go binary package made available through the Packer plugin SDK
+
+Say you want to configure the `Config` struct of a `Builder` in a package
+located in `my/example-plugin/config.go`. Here are some simple steps you can
+follow to make it HCL2 enabled:
+
+- run `go install github.com/hashicorp/packer-plugin-sdk/cmd/packer-sdc@latest`
+
+- Add `//go:generate packer-sdc mapstructure-to-hcl2 -type Config` at the top of
+ `config.go`
+
+- run `go generate ./my/example-plugin/...`
+
+ This will generate a `my/example-plugin/config.hcl2spec.go` file containing
+ the configuration fields of `Config`.
+
+- Make sure that all the nested structs of `Config` are also auto generated the
+ same way.
+
+- Now we only need to make your Builder implement the interface by adding the
+ following snippet:
+
+ ```go
+ func (b *Builder) ConfigSpec() hcldec.ObjectSpec { return b.config.FlatMapstructure().HCL2Spec() }
+ ```
+
+ From now on every time you add or change a field of Config you will need to
+ run the `go generate` command again.
+
+A good example of this is the [Config struct of the amazon-ebs builder](https://github.com/hashicorp/packer-plugin-amazon/blob/main/builder/ebs/builder.go)
diff --git a/content/packer/v1.10.x/content/guides/hcl/index.mdx b/content/packer/v1.10.x/content/guides/hcl/index.mdx
new file mode 100644
index 0000000000..aa8d779b49
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/hcl/index.mdx
@@ -0,0 +1,90 @@
+---
+page_title: Getting started configuring Packer with HCL2 files
+description: >-
+ Use the HCL2 syntax for your Packer templates. Learn about arguments and blocks, comments, and multi-line strings.
+---
+
+# Introduction to Packer HCL2
+
+@include 'guides/hcl2-beta-note.mdx'
+
+It is not necessary to know all of the details of the HCL syntax in order to
+use Packer, and so this page summarizes the most important details to get you
+started. If you are interested, you can find a [full definition of HCL
+syntax](https://github.com/hashicorp/hcl2/blob/master/hcl/hclsyntax/spec.md) in
+the HCL native syntax specification.
+
+## Arguments and Blocks
+
+The HCL syntax is built around two key syntax constructs: arguments and blocks.
+
+```hcl
+# block
+source "amazon-ebs" "example" {
+
+ # argument
+ ami_name = "abc123"
+}
+```
+
+## Comments
+
+The HCL language supports three different syntaxes for comments:
+
+- `#` begins a single-line comment, ending at the end of the line.
+- `//` also begins a single-line comment, as an alternative to `#`.
+- `/*` and `*/` are start and end delimiters for a comment that might
+ span over multiple lines.
+
+## Multi-line strings
+
+A multi-line string value can be provided using heredoc syntax.
+
+```hcl
+variable "long_key" {
+ type = "string"
+ default = <
+/install/vmlinuz noapic
+...
+EOF
+}
+```
+
+```hcl
+# folder/build.pkr.hcl
+build {
+ sources = [
+ "source.amazon-ebs.example-1",
+ "source.virtualbox-iso.example-2"
+ ]
+
+ provisioner "shell" {
+ inline = [
+ "echo 'it is alive !'"
+ ]
+ }
+}
+```
diff --git a/content/packer/v1.10.x/content/guides/hcl/variables.mdx b/content/packer/v1.10.x/content/guides/hcl/variables.mdx
new file mode 100644
index 0000000000..b8952c7cdf
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/hcl/variables.mdx
@@ -0,0 +1,373 @@
+---
+page_title: Input and Local Variables guide
+description: |-
+ This page introduces input variables and local variables as a way to
+ parameterize a configuration.
+---
+
+# Input Variables and local variables
+
+@include 'guides/hcl2-beta-note.mdx'
+
+This page introduces input variables and local variables as a way to
+parameterize a configuration. Once defined, input variables are settable from a
+default value, environment, special var files, and command line arguments.
+Local variables can be a compound of input variables and local variables.
+
+## Defining Variables and locals
+
+In the legacy JSON Packer templates, any variables we hadn't already defined in
+the "variables" stanza of our json template could simply be passed in via the
+command line or a `var-file`; if a variable was never defined it would generally
+be interpolated to an empty string.
+
+_In the HCL2 Packer templates, we must always pre-define our variables in the
+HCL equivalent of the "variables" stanza._
+
+Another difference between JSON and HCL Packer templates is that in JSON packer
+templates, the "variables" stanza, if used, was always in the same .json file
+as the builds and builders. In HCL, it can exist in its own file if you want it
+to.
+
+To demonstrate, let's create a file `variables.pkr.hcl` with the following
+contents.
+
+-> **Note**: that the file can be named anything, since Packer loads all
+files ending in `.pkr.hcl` in a directory. If you split your configuration
+across multiple files, use
+`packer build ` to initiate a build.
+
+```hcl
+// variables.pkr.hcl
+
+// For those variables that you don't provide a default for, you must
+// set them from the command line, a var-file, or the environment.
+
+variable "weekday" {}
+
+variable "sudo_password" {
+ type = string
+ default = "mypassword"
+ // Sensitive vars are hidden from output as of Packer v1.6.5
+ sensitive = true
+}
+
+variable "flavor" {
+ type = string
+ default = "strawberry"
+}
+
+variable "exit_codes" {
+ type = list(number)
+ default = [0]
+}
+
+locals {
+ ice_cream_flavor = "${var.flavor}-ice-cream"
+ foo = "bar"
+}
+```
+
+This defines several variables within your Packer configuration, each showing
+off a different way to set them. The first variable, "weekday", is an empty
+block `{}`, without a type or a default.
+
+However, it's generally best to provide the type in your variable definition,
+as you can see in variable "flavor", which we have given a type of "string",
+and variable "exit_codes", which we have given a type of "list(number)",
+meaning it is a list/array of numbers.
+
+When a variable is passed from the cli or environment and the variable's type
+is not set, Packer will expect it to be a string. But if it is passed from a
+var-file where Packer can interpret HCL properly it can be a slice or any
+supported type.
+
+In addition to setting the type, the "flavor" and "exit_codes" variables also
+provide a default. If you set a default value, then you don't need to set the
+variable at run time. Packer will use a provided command-line var,
+var-file, or environment var if it exists, but if not Packer will fall back to
+this default value.
+
+If you do not set a default value, Packer will fail immediately when you try to
+run a `build` if you have not provided the missing variable via the
+command-line, a var-file, or the environment. The `validate`, `inspect` and
+`console` commands will work, but variables with unknown values will be
+``.
+
+This also defines two locals: `ice_cream_flavor` and `foo`.
+
+-> **Note**: that it is _not_ possible to reference a variable in the
+definition of another variable. But it _is_ possible to use locals and
+variables in the definition of a local, as shown in the ice_cream_flavor
+definition.
+
+## Using Variables and locals in Configuration
+
+For simplicity's sake, we're going to put a null source in the same file as
+we are putting the build configuration. This file demonstrates how to use the
+variables we previously defined.
+
+```hcl
+// null_example.pkr.hcl
+
+source "null" "example" {
+ communicator = "none"
+}
+
+build {
+ sources = [
+ "source.null.example"
+ ]
+ provisioner "shell-local" {
+ // Note that for options that are documented as template engines,
+ // we still have to use the Go template engine syntax rather than our
+ // specialized HCL2 variable syntax. This example shows a combination of
+ // an HCL2 variable and the Go template engines built into the
+ // execute_command option
+ execute_command = ["/bin/sh", "-c", "echo ${var.sudo_password}| {{.Vars}} {{.Script}}"]
+ environment_vars = ["HELLO_USER=packeruser", "UUID=${build.PackerRunUUID}"]
+ inline = ["echo the Packer run uuid is $UUID"]
+ }
+ provisioner "shell-local" {
+ inline = ["echo var.flavor is: ${var.flavor}",
+ "echo local.ice_cream_flavor is: ${local.ice_cream_flavor}"]
+ valid_exit_codes = var.exit_codes
+ }
+}
+```
+
+As you can see in the example, you can access your variables directly by
+giving them the `var.` or `local.` prefix. If you want to embed the variables
+in a string, you can do so with the `${}` HCL interpolation syntax. If you are
+using an option that is a template engine, you still need to use the Go
+templating engine syntax `{{ .OPTION }}` for those engines.
+
+## Assigning Variables
+
+There are multiple ways to assign variables. Below is also the order
+in which variable values are chosen. The following is the descending order
+of precedence in which variables are considered. So first defined; first used.
+
+#### Command-line flags
+
+You can set variables directly on the command-line with the
+`-var` flag.:
+
+```shell-session
+$ packer build \
+ -var "weekday=Sunday" \
+ -var "flavor=chocolate" \
+ -var "sudo_password=hunter42" .
+```
+
+Once again, setting variables this way will not save them, and they'll
+have to be input repeatedly as commands are executed.
+
+If you plan to assign variables via the command line, we strongly recommend that
+you at least set a default type instead of using empty blocks; this helps the
+HCL parser understand what is being set. Otherwise it will interpret all of your
+command line variables as strings.
+
+#### From a file
+
+To persist variable values, create a file and assign variables within
+this file. A variable definitions file uses the same basic syntax as Packer language files,
+but consists only of variable name assignments.
+
+```hcl
+sudo_password = "partyparrot"
+weekday = "Sunday"
+```
+
+When assigning values in a variable definitions file please make sure to quote any string values,
+wrap list values within brackets `[...]`, and wrap maps within curly-braces `{...}`.
+
+Given a file named `variables.pkrvars.hcl` Packer can be instructed to use the
+variable definitions file by using the `-var-file` command line flag.
+
+```shell-session
+$ packer build -var-file="variables.pkrvars.hcl" .
+```
+
+Packer will automatically load any var file that matches the name
+`*.auto.pkrvars.hcl`, without the need to pass the file via the command line.
+If we rename the above variable definitions file from `variables.pkrvars.hcl` to
+`variables.auto.pkrvars.hcl`, then we can run our build simply by calling
+
+```shell-session
+$ packer build .
+```
+
+You may provide as many -var-file flags as you would like:
+
+```shell-session
+$ packer build \
+ -var-file="secret.pkrvars.hcl" \
+ -var-file="production.pkrvars.hcl" .
+```
+
+These files can also be JSON:
+
+variables.json:
+
+```json
+{
+ "weekday": "sunday",
+ "flavor": "mint"
+}
+```
+
+```shell-session
+$ packer build -var-file=variables.json
+```
+
+We don't recommend saving sensitive information to version control, but you
+can create a local secret variables file and use `-var-file` to load it.
+
+You can use multiple `-var-file` arguments in a single command, with some
+checked in to version control and others not checked in. For example:
+
+```shell-session
+$ packer build \
+ -var-file="secret.pkrvars.hcl" \
+ -var-file="production.pkrvars.hcl" .
+```
+
+#### From environment variables
+
+Packer will read environment variables in the form of `PKR_VAR_name` to find
+the value for a variable. For example, the `PKR_VAR_access_key` variable can be
+set to set the `access_key` variable.
+
+```shell-session
+$ export PKR_VAR_weekday=Monday
+$ packer build .
+```
+
+#### Variable Defaults
+
+If no value is assigned to a variable via any of these methods and the
+variable has a `default` key in its declaration, that value will be used
+for the variable.
+
+If all of your variables have defaults, then you can call a packer build using:
+
+```shell-session
+$ packer build .
+```
+
+You can make this work for yourself using the variable example file above by
+commenting out or removing the "weekday" variable declaration, since it is not
+actually used in the example build.
+
+If your variable definitions are stored in the same file as your source and
+build, you can call the build against that specific file:
+
+```shell-session
+$ packer build self_contained_example.pkr.hcl
+```
+
+#### Unspecified Values Fail
+
+If you call `packer build` with any variables defined but not set, Packer will
+error.
+
+## Variable Type Reference
+
+### Lists
+
+Lists are defined either explicitly or implicitly
+
+```hcl
+# implicitly by using brackets [...]
+variable "cidrs" { default = [] }
+
+# explicitly
+variable "cidrs" { type = list }
+```
+
+You can specify lists in a `variables.pkrvars.hcl` file:
+
+```hcl
+cidrs = [ "10.0.0.0/16", "10.1.0.0/16" ]
+```
+
+### Maps
+
+Maps are a way to create variables that are lookup tables. An example
+will show this best. Let's extract our AMIs into a map and add
+support for the `us-west-2` region as well:
+
+```hcl
+variable "amis" {
+ type = map(string)
+ default = {
+ "us-east-1" = "ami-b374d5a5"
+ "us-west-2" = "ami-4b32be2b"
+ }
+}
+```
+
+A variable can have a `map` type assigned explicitly, or it can be implicitly
+declared as a map by specifying a default value that is a map. The above
+demonstrates both.
+
+Then we can `lookup` in maps like in the following:
+
+```hcl
+source "amazon-ebs" "example" {
+ source_ami = "${lookup(var.amis, var.region)}"
+ instance_type = "t2.micro"
+}
+```
+
+This introduces a new type of interpolation: a function call. The
+`lookup` function does a dynamic lookup in a map for a key. The
+key is `var.region`, which specifies that the value of the region
+variables is the key.
+
+You can also do a static lookup of a map directly with
+`${var.amis["us-east-1"]}`.
+
+## Assigning Maps
+
+We set defaults above, but maps can also be set using the `-var` and
+`-var-file` values. For example:
+
+```shell-session
+$ packer build -var 'amis={ us-east-1 = "foo", us-west-2 = "bar" }'
+# ...
+```
+
+Here is an example of setting a map's keys from a file. Starting with these
+variable definitions:
+
+```hcl
+variable "region" {}
+variable "amis" {
+ type = map
+}
+```
+
+You can specify keys in a `variables.pkrvars.hcl` file:
+
+```hcl
+amis = {
+ "us-east-1" = "ami-abc123"
+ "us-west-2" = "ami-def456"
+}
+```
+
+And access them via `lookup()`:
+
+```hcl
+output "ami" {
+ value = "${lookup(var.amis, var.region)}"
+}
+```
+
+Like so:
+
+```shell-session
+$ packer build -var region=us-west-2
+```
diff --git a/content/packer/v1.10.x/content/guides/index.mdx b/content/packer/v1.10.x/content/guides/index.mdx
new file mode 100644
index 0000000000..347e876c16
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/index.mdx
@@ -0,0 +1,17 @@
+---
+page_title: Guides
+description: |-
+ Welcome to the Packer guides. If you are just getting started with Packer,
+ please see the Packer introduction instead and then continue on to the guides.
+ These guides provide examples for common Packer workflows and actions for
+ users of Packer.
+---
+
+# Packer
+
+Welcome to the Packer guides. If you are just getting started with Packer,
+please see the [Packer introduction][intro] instead and then continue on to the
+guides. These guides provide examples for common Packer workflows and actions
+for users of Packer.
+
+[intro]: /packer/docs/intro
diff --git a/content/packer/v1.10.x/content/guides/packer-on-cicd/build-image-in-cicd.mdx b/content/packer/v1.10.x/content/guides/packer-on-cicd/build-image-in-cicd.mdx
new file mode 100644
index 0000000000..4efc595153
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/packer-on-cicd/build-image-in-cicd.mdx
@@ -0,0 +1,29 @@
+---
+page_title: Build Images in CI/CD
+description: >-
+ Learn how to build Packer images within a continuous integration / continuous delivery pipeline.
+---
+
+# Build Images in CI/CD
+
+The following guides from our partners show how to use their services to build
+images with Packer.
+
+- [How to Build Immutable Infrastructure with Packer and CircleCI Workflows](https://circleci.com/blog/how-to-build-immutable-infrastructure-with-packer-and-circleci-workflows/)
+- [Using Packer and Ansible to Build Immutable Infrastructure in CodeShip](https://blog.codeship.com/packer-ansible/)
+
+The majority of the [Packer Builders](/packer/docs/builders) can run just fine in a
+container, a common model used by most CI/CD services. However, while it is
+possible to run many builders in containers or nested virtualization, this may
+require advanced configuration; examples include the [QEMU
+builder](/packer/plugins/builders/qemu) for
+[KVM](https://www.linux-kvm.org/page/Main_Page) or
+[Xen](https://www.xenproject.org/), the [VirtualBox
+builder](/packer/plugins/builders/virtualbox) for OVA or OVF virtual machines, and the
+[VMware builder](/packer/plugins/builders/vmware) for use with VMware products that are
+all designed to run on a bare-metal machine or within nested virtualization.
+
+The [Building a VirtualBox Image with Packer in
+TeamCity](/packer/guides/packer-on-cicd/build-virtualbox-image) guide shows
+how to create a VirtualBox image using TeamCity's support for running scripts
+on bare-metal machines.
diff --git a/content/packer/v1.10.x/content/guides/packer-on-cicd/build-virtualbox-image.mdx b/content/packer/v1.10.x/content/guides/packer-on-cicd/build-virtualbox-image.mdx
new file mode 100644
index 0000000000..69e4701840
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/packer-on-cicd/build-virtualbox-image.mdx
@@ -0,0 +1,149 @@
+---
+page_title: Build a VirtualBox Image with Packer in TeamCity
+description: >-
+ Use Packer to build VirtualBox images in TeamCity. Learn how to provision a bare-metal machine, install dependencies, and create and run a build in TeamCity.
+---
+
+# Build a VirtualBox Image with Packer in TeamCity
+
+This guide walks through the process of building a VirtualBox image using
+Packer on a new TeamCity Agent. Before getting started you should have access
+to a TeamCity Server.
+
+The Packer VirtualBox builder requires access to VirtualBox. Virtualization is
+not universally supported on cloud instances, so we recommend you run these
+builds on either a bare metal server, or cloud instances which support nested
+virtualization, such as Azure or GCP. This is also true for the
+[VMware](/packer/plugins/builders/vmware) and the [QEMU](/packer/plugins/builders/qemu)
+Packer builders.
+
+We will use Chef's [Bento boxes](https://github.com/chef/bento) to provision an
+Ubuntu image on VirtualBox. For this example, we will use the repository
+directly, but you may also fork it for the same results.
+
+## 1. Provision a Bare-metal Machine
+
+For the purposes of this example, we will run on a bare-metal instance from
+[Packet](https://www.packet.net/). If you are a first time user of Packet, the
+Packet team has provided HashiCorp the coupon code `hashi25` which you can use
+for `$25` off to test out this guide and up to 30% if you decide to
+reserve ongoing servers (email help@packet.net for details). You can use
+a `baremetal_0` server type for testing, but for regular use, the `baremetal_1`
+instance may be a better option.
+
+There is also a [Packet
+Provider](https://registry.terraform.io/providers/packethost/packet/latest/docs) in
+Terraform you can use to provision the project and instance.
+
+```hcl
+provider "packet" { }
+
+resource "packet_project" "teamcity_agents" {
+ name = "TeamCity"
+}
+
+resource "packet_device" "agent" {
+ hostname = "teamcity-agent"
+ plan = "baremetal_0"
+ facility = "ams1"
+ operating_system = "ubuntu_16_04"
+ billing_cycle = "hourly"
+ project_id = "${packet_project.teamcity_project.id}"
+}
+```
+
+## 2. Install VirtualBox and TeamCity dependencies
+
+VirtualBox must be installed on the new instance, and TeamCity requires the JDK
+prior to installation. This guide uses Ubuntu as the Linux distribution, so you
+may need to adjust these commands for your distribution of choice.
+
+**Install Teamcity Dependencies**
+
+```shell-session
+$ apt-get upgrade
+$ apt-get install -y zip linux-headers-generic linux-headers-4.13.0-16-generic build-essential openjdk-8-jdk
+```
+
+**Install VirtualBox**
+
+```shell-session
+$ curl -OL "https://download.virtualbox.org/virtualbox/5.2.2/virtualbox-5.2_5.2.2-119230~Ubuntu~xenial_amd64.deb"
+$ dpkg -i virtualbox-5.2_5.2.2-119230~Ubuntu~xenial_amd64.deb
+```
+
+You can also use the [`remote-exec`
+provisioner](/terraform/docs/provisioners/remote-exec) in
+your Terraform configuration to automatically run these commands when
+provisioning the new instance.
+
+## 3. Install Packer
+
+The TeamCity Agent machine will also need Packer Installed. You can find the
+latest download link from the [Packer
+Download](/packer/downloads) page.
+
+```shell-session
+$ curl -OL "https://releases.hashicorp.com/packer/1.1.2/packer_1.1.2_linux_amd64.zip"
+$ unzip ./packer_1.1.2_linux_amd64.zip
+```
+
+Packer is installed at the `/root/packer` path which is used in subsequent
+steps. If it is installed elsewhere, take note of the path.
+
+## 4. Install TeamCity Agent
+
+This guide assume you already have a running instance of TeamCity Server. The
+new TeamCity Agent can be installed by [downloading a zip file and installing
+manually](https://confluence.jetbrains.com/display/TCD10//Setting+up+and+Running+Additional+Build+Agents#SettingupandRunningAdditionalBuildAgents-InstallingAdditionalBuildAgents),
+or using [Agent
+Push](https://confluence.jetbrains.com/display/TCD10//Setting+up+and+Running+Additional+Build+Agents#SettingupandRunningAdditionalBuildAgents-InstallingviaAgentPush).
+Once it is installed it should appear in TeamCity as a new Agent.
+
+Create a new Agent Pool for agents responsible for VirtualBox Packer builds and
+assign the new Agent to it.
+
+## 5. Create a New Build in TeamCity
+
+In TeamCity Server, create a new build. To use the upstream Bento repository,
+we'll choose _From a repository URL_, and enter
+`https://github.com/chef/bento.git` as the **Repository URL**.
+
+
+
+Click **Proceed**.
+
+
+
+And **Proceed** again.
+
+We won't use the _Auto-detected Build Steps_. Instead, click _configure build
+steps manually_. For the _runner type_, pick **Command Line**, and enter the
+following values. Make sure to click _Show advanced options_, as we need to set
+the working directory.
+
+
+
+This will use the `build` command in Packer to build the image defined in
+`ubuntu/ubuntu-16.04-amd64.json`. It assumes that the VCS repository you're
+using is a fork of [Chef/Bento](https://github.com/chef/bento). Packer defaults
+to building VirtualBox machines by launching a GUI that shows the console.
+Since this will run in CI/CD, use the [`headless`
+variable](/packer/plugins/builders/virtualbox/iso#headless) to instruct Packer to
+start the machine without the console. Packer can build multiple image types,
+so the [`-only=virtualbox-iso`
+option](/packer/docs/commands/build#only-foo-bar-baz) instructs Packer to only
+build the builds with the name `virtualbox-iso`.
+
+## 6. Run a build in TeamCity
+
+The entire configuration is ready for a new build. Start a new run in TeamCity
+by pressing “Run”.
+
+The new run should be triggered and the virtual box image will be built.
+
+
+
+Once complete, the build status should be updated to complete and successful.
+
+
diff --git a/content/packer/v1.10.x/content/guides/packer-on-cicd/index.mdx b/content/packer/v1.10.x/content/guides/packer-on-cicd/index.mdx
new file mode 100644
index 0000000000..d083ed4766
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/packer-on-cicd/index.mdx
@@ -0,0 +1,17 @@
+---
+page_title: Build Immutable Infrastructure with Packer in CI/CD
+description: >-
+ Learn how to use Packer to build immutable infrastructure within a continuous integration / continuous delivery pipeline.
+---
+
+# Build Immutable Infrastructure with Packer in CI/CD
+
+This guide focuses on the following workflow for building immutable
+infrastructure. This workflow can be manual or automated and it can be
+implemented with a variety of technologies. The goal of this guide is to show
+how this workflow can be fully automated using Packer for building images from
+a continuous integration/continuous deployment (CI/CD) pipeline.
+
+1. [Build Images using Packer in CI/CD](/packer/guides/packer-on-cicd/build-image-in-cicd)
+2. [Upload the new image to S3](/packer/guides/packer-on-cicd/upload-images-to-artifact) for future deployment or use during development
+3. [Create new Terraform Enterprise runs](/packer/guides/packer-on-cicd/trigger-tfe) to provision new instances with the images
diff --git a/content/packer/v1.10.x/content/guides/packer-on-cicd/pipelineing-builds.mdx b/content/packer/v1.10.x/content/guides/packer-on-cicd/pipelineing-builds.mdx
new file mode 100644
index 0000000000..2a7e692109
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/packer-on-cicd/pipelineing-builds.mdx
@@ -0,0 +1,354 @@
+---
+page_title: Packer Build Pipelines
+description: >-
+ Learn how to shorten Packer build times and improve reliability. Start from an ISO, customize using the virtualbox-ovf builder, and improve efficiency.
+---
+
+# Why Create a Template Pipeline?
+
+A common issue users face when beginning to create their Packer templates is
+that while they may need several specialized images, the early provisioning
+steps are all the same. It can feel tedious to copy all of those images' basic
+configuraton into each build template. It can feel even more tedious to wait a
+long time for similar builds to run duplicate steps.
+
+This is one reason why Packer recommends breaking your builds into small,
+discrete steps. Not only does it allow you to create "base" images that you can
+build from to create further customizations, but it also allows you to save
+time in your build process because the "base" images are likely to change less
+than your customizations.
+
+It also makes it so that a failing build takes less time to debug and re-run.
+
+In this example, we will use the Virtualbox builders, but the concepts from
+this example can be applied to other builders as well.
+
+## Starting from an ISO
+
+Here is an extremely basic virtualbox-iso template:
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "virtualbox-iso",
+ "vm_name": "vbox-example",
+ "boot_command": [
+ "",
+ "",
+ "",
+ "/install/vmlinuz",
+ " initrd=/install/initrd.gz",
+ " auto-install/enable=true",
+ " debconf/priority=critical",
+ " preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/ubuntu_preseed.cfg",
+ " -- ",
+ ""
+ ],
+ "http_directory": "./http",
+
+ "disk_size": "40960",
+ "guest_os_type": "Ubuntu_64",
+ "iso_checksum": "sha256:946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2",
+ "iso_url": "http://old-releases.ubuntu.com/releases/14.04.1/ubuntu-14.04-server-amd64.iso",
+
+ "shutdown_command": "echo 'vagrant' | sudo -S shutdown -P now",
+
+ "ssh_port": 22,
+ "ssh_username": "vagrant",
+ "ssh_password": "vagrant"
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "shell",
+ "inline": ["echo initial provisioning"]
+ }
+ ],
+ "post-processors": [
+ {
+ "type": "manifest",
+ "output": "stage-1-manifest.json"
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+source "virtualbox-iso" "step_1" {
+ boot_command = ["", "", "",
+ "/install/vmlinuz", " initrd=/install/initrd.gz",
+ " auto-install/enable=true", " debconf/priority=critical",
+ " preseed/url=http://{{ .HTTPIP }}:{{ .HTTPPort }}/ubuntu_preseed.cfg",
+ " -- ", ""]
+ disk_size = "40960"
+ guest_os_type = "Ubuntu_64"
+ http_directory = "./http"
+ iso_checksum = "sha256:946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2"
+ iso_url = "http://old-releases.ubuntu.com/releases/14.04.1/ubuntu-14.04-server-amd64.iso"
+ shutdown_command = "echo 'vagrant' | sudo -S shutdown -P now"
+ ssh_password = "vagrant"
+ ssh_port = 22
+ ssh_username = "vagrant"
+ vm_name = "vbox-example"
+}
+build {
+ sources = ["source.virtualbox-iso.step_1"]
+
+
+ provisioner "shell" {
+ inline = ["echo initial provisioning"]
+ }
+ post-processor "manifest" {
+ output = "stage-1-manifest.json"
+ }
+}
+```
+
+
+
+
+In order to build using this template, create a directory named "http" in your
+current working directory. Copy the minimal example from our
+[preseed guide](/packer/guides/automatic-operating-system-installs/preseed_ubuntu#examples)
+into a file in your http directory and name it "ubuntu_preseed.cfg". Copy the
+above json template into your current working directory and save it as
+"example_virtualbox_iso.json"
+
+To run the build, call `packer build example_virtualbox_iso.json`.
+
+This example does not set the output_directory or output_filename, so the file
+will be placed in a default name of "output-virtualbox-iso/vbox-example.ovf" --
+the builder will print this file name to the UI output, but in this example the
+[manifest](/packer/docs/post-processors/manifest) post-processor
+to will store build information, including the names of the output files, in a
+json file named "stage-1-manifest.json". From there, you can programmatically
+look up the output file information.
+
+## Customizing the iso using the virtualbox-ovf builder
+
+That output filename generated in the first stage can be used as the
+[source_path](/packer/plugins/builders/virtualbox/ovf#source_path)
+for the virtualbox-ovf builder.
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "virtualbox-ovf",
+ "vm_name": "virtualbox-example-ovf",
+
+ "shutdown_command": "echo 'vagrant' | sudo -S shutdown -P now",
+ "source_path": "output-virtualbox-iso/vbox-example.ovf",
+
+ "ssh_password": "vagrant",
+ "ssh_port": 22,
+ "ssh_username": "vagrant"
+ }
+ ],
+ "provisioners": [
+ {
+ "inline": ["echo secondary provisioning"],
+ "type": "shell"
+ }
+ ]
+}
+```
+
+
+
+
+```hcl
+source "virtualbox-ovf" "step_2" {
+ shutdown_command = "echo 'vagrant' | sudo -S shutdown -P now"
+ source_path = "output-virtualbox-iso/vbox-example.ovf"
+ ssh_password = "vagrant"
+ ssh_port = 22
+ ssh_username = "vagrant"
+ vm_name = "virtualbox-example-ovf"
+}
+
+build {
+ sources = ["source.virtualbox-ovf.step_2"]
+
+ provisioner "shell" {
+ inline = ["echo secondary provisioning"]
+ }
+}
+
+```
+
+
+
+
+## More efficiencies
+
+You may find that you want to run time-consuming import post-processors like
+the "amazon-import" post-processor independently of the build that produces
+the artifacts you want to process.
+
+In this case, you can use a null builder
+and manually modify the input to the post-processing chain so that you can get
+the behavior you want. The below example shows a "vagrant" post-processor
+being used with a null builder, and manually sets the artifact from our
+stage-2 ovf build:
+
+
+
+
+```json
+{
+ "builders": [
+ {
+ "type": "null",
+ "communicator": "none"
+ }
+ ],
+ "post-processors": [
+ [
+ {
+ "type": "artifice",
+ "files": [
+ "output-virtualbox-ovf/virtualbox-example-ovf.ovf",
+ "output-virtualbox-ovf/virtualbox-example-ovf-disk001.vmdk"
+ ]
+ },
+ {
+ "type": "vagrant",
+ "provider_override": "virtualbox"
+ }
+ ]
+ ]
+}
+```
+
+
+
+
+```hcl
+source "null" "step_3" {
+ communicator = "none"
+}
+
+build {
+ sources = ["source.null.step_3"]
+
+ post-processors {
+ post-processor "artifice" {
+ files = ["output-virtualbox-ovf/virtualbox-example-ovf.ovf", "output-virtualbox-ovf/virtualbox-example-ovf-disk001.vmdk"]
+ }
+ post-processor "vagrant" {
+ provider_override = "virtualbox"
+ }
+ }
+}
+```
+
+
+
+
+By using the null builder instead of just running an ovf builder, we can spare
+ourselves all of the time Packer would normally spend launching and destroying
+VMs.
+
+## Putting it all together
+
+Packer templates don't come with a custom "glue" to bind them together. We
+recommend using your CI system or wrapping scripts to connect the templates
+into a chain.
+
+## Chaining together several of the same builders to make "save points"
+
+If you want to use the same builder for several builds in a row, this can feel
+tedious to implement in json. We recommend you try using HCL configs so that
+you can reuse the same source in several builds:
+
+HCL templates work by allowing you to draw sources and variables from multiple
+different files in a single directory, so the following files are assumed to
+exist in their own folder:
+
+sources.pkr.hcl
+
+```hcl
+// In your sources file, you can create a configuration for a builder that you
+// want to reuse between multiple steps in the build. Just leave the source
+// and destination images out of this source, and set them specifically in each
+// step without having to set all of the other options over and over again.
+
+source "docker" "example" {
+ commit = true
+ // any other configuration you want for your Docker containers
+}
+```
+
+build.pkr.hcl
+
+```hcl
+build {
+ // Make sure to name your builds so that you can selectively run them one at
+ // a time.
+ name = "step1"
+
+ source "source.docker.example" {
+ image = "ubuntu"
+ }
+
+ provisioner "shell" {
+ inline = ["echo example provisioner"]
+ }
+ provisioner "shell" {
+ inline = ["echo another example provisioner"]
+ }
+ provisioner "shell" {
+ inline = ["echo a third example provisioner"]
+ }
+
+ // Make sure that the output from your build can be used in the next build.
+ // In this example, we're tagging the Docker image so that the step-2
+ // builder can find it without us having to track it down in a manifest.
+ post-processor "docker-tag" {
+ repository = "ubuntu"
+ tag = ["step-1-output"]
+ }
+}
+
+build {
+ name = "step2"
+
+ source "source.docker.example" {
+ // This is the tagged artifact from the stage 1 build. You can retrieve
+ // this from a manifest file and setting it as a variable on the command
+ // line, or by making sure you define and know the output of the build,
+ // if it's something you can define like an output name or directory.
+ image = "ubuntu:step-1-output"
+ // disable the pull if your image tag only exists locally
+ pull = false
+ }
+
+ provisioner "shell" {
+ inline = ["echo another provision!"]
+ }
+}
+```
+
+pipeline.sh
+
+```sh
+#!/bin/bash
+set -e # abort if there is an issue with any build
+packer build -only='step1.docker.example' .
+packer build -only='step2.docker.example' .
+```
+
+To run the pipeline, call pipeline.sh. You can create as many build steps as
+you want. Each can either inhabit one file, or you can put multiple steps in
+a single file like shown in the example above.
diff --git a/content/packer/v1.10.x/content/guides/packer-on-cicd/trigger-tfe.mdx b/content/packer/v1.10.x/content/guides/packer-on-cicd/trigger-tfe.mdx
new file mode 100644
index 0000000000..14b2643bd1
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/packer-on-cicd/trigger-tfe.mdx
@@ -0,0 +1,60 @@
+---
+page_title: Trigger Terraform Enterprise runs
+description: >-
+ Learn how to Terraform Enterprise from your CI/CD pipeline to provision infrastructure.
+---
+
+# Create Terraform Enterprise Runs
+
+Once an image is built and uploaded to an artifact store, the next step is to
+use this new image. In some cases the image will be downloaded by the dev team
+and used locally in development, like is often done with VirtualBox images with
+Vagrant. In most other cases, the new image will be used to provision new
+infrastructure.
+
+[Terraform](https://www.terraform.io/) is a community tool that is ideal for
+provisioning new infrastructure with images generated by Packer, and [Terraform
+Enterprise](https://www.hashicorp.com/products/terraform/) is the best way to
+perform automated Terraform runs.
+
+## Create a Terraform Configuration and Workspace
+
+The following is a sample Terraform configuration which provisions a new AWS
+EC2 instance. The `aws_ami_id` is a variable which will be provided when
+running `terraform plan` and `terraform apply`. This variable references the
+latest AMI generated with the Packer build in CI/CD.
+
+```hcl
+variable "aws_ami_id" { }
+
+provider "aws" {
+ region = "us-west-2"
+}
+
+resource "aws_instance" "web" {
+ ami = "${var.aws_ami_id}"
+ instance_type = "t2.micro"
+}
+```
+
+Terraform Enterprise should have a workspace with this terraform configuration
+and a placeholder variable `aws_ami_id`.
+
+## Include Terraform Enterprise in Your CI Builds
+
+Follow these steps to create a new run from CI/CD after a Packer build is
+complete and uploaded.
+
+1. Add a new step to the CI/CD pipeline.
+2. In the new step add a `curl` call to update the variables in the workspace
+ using the [update variables
+ API](/terraform/docs/enterprise/api/variables#update-variables),
+ so that Terraform has a reference to the latest image. For the sample
+ configuration above, the `aws_ami_id` variable should be updated to the AMI
+ ID of the latest image.
+3. In that same step, add another `curl` call to [create a new run via the
+ API](/terraform/docs/enterprise/api/run#create-a-run).
+ A run performs a plan and apply on the last configuration version created,
+ using the variables set in the workspace. In the previous step we update the
+ variables, so the new run can be created using the previous configuration
+ version.
diff --git a/content/packer/v1.10.x/content/guides/packer-on-cicd/upload-images-to-artifact.mdx b/content/packer/v1.10.x/content/guides/packer-on-cicd/upload-images-to-artifact.mdx
new file mode 100644
index 0000000000..6728a19338
--- /dev/null
+++ b/content/packer/v1.10.x/content/guides/packer-on-cicd/upload-images-to-artifact.mdx
@@ -0,0 +1,45 @@
+---
+page_title: Upload VirtualBox Image to S3
+description: >-
+ Learn how to upload a VirtualBox image built with Packer to S3 within a TeamCity build.
+---
+
+# Upload VirtualBox Image to S3
+
+Once the image is generated it will be used by other parts of your operations
+workflow. For example, it is common to build VirtualBox images with Packer to
+be used as base boxes in Vagrant.
+
+The exact process for uploading images depends on the artifact store and CI
+system you use. TeamCity provides a [Build
+Artifacts](https://confluence.jetbrains.com/display/TCD9/Build+Artifact)
+feature which can be used to store the newly generated image. Other CI/CD
+services also have similar build artifacts features built in, like [Circle CI
+Build Artifacts](https://circleci.com/docs/2.0/artifacts/). In addition to the
+built in artifact stores in CI/CD tools, there are also dedicated universal
+artifact storage services like
+[Artifactory](https://confluence.jetbrains.com/display/TCD9/Build+Artifact).
+All of these are great options for image artifact storage.
+
+The following example uses TeamCity and Amazon S3.
+
+## Example: Uploading to S3 in a TeamCity Build
+
+On the agent machine responsible for building images, install the [AWS Command
+Line Tool](https://aws.amazon.com/cli/). Since this is a one-time operation,
+this can be incorporated into the initial agent provisioning step when
+installing other dependencies. The AWS Command Line tool may require installing
+additional
+[dependencies](http://docs.aws.amazon.com/cli/latest/userguide/installing.html)
+prior.
+
+```shell-session
+$ pip install awscli
+```
+
+In your build configuration in TeamCity Server, add an additional **Build Step:
+Command Line** and set the **Script content** field to the following:
+
+```shell-session
+$ awscli s3 cp . s3://bucket/ --exclude “*” --include “*.ovf"
+```
diff --git a/content/packer/v1.10.x/content/partials/builders/community_builders.mdx b/content/packer/v1.10.x/content/partials/builders/community_builders.mdx
new file mode 100644
index 0000000000..ad9482b602
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/builders/community_builders.mdx
@@ -0,0 +1,12 @@
+### Community Builders
+
+- ARM builders
+
+ - [packer-plugin-arm-image](https://github.com/solo-io/packer-plugin-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).
+
+- [Exoscale builder](https://github.com/exoscale/packer-plugin-exoscale) - A builder to create Exoscale custom templates based on a Compute instance snapshot.
+
+- [Citrix XenServer/Citrix Hypervisor](https://github.com/xenserver/packer-builder-xenserver) - Plugin for creating [Citrix XenServer/Citrix Hypervisor](https://xenserver.org/) images from an iso image or from an existing template.
+
+- [XCP-NG/Citrix XenServer/Citrix Hypervisor/Updated Fork](https://github.com/ddelnano/packer-plugin-xenserver) - Plugin for creating [XCP-NG/Citrix XenServer/Citrix Hypervisor](https://xcp-ng.org/) images from an iso image or from an existing template. This is a fork of the orginal, and reccomended by the developers of XCP-NG.
diff --git a/content/packer/v1.10.x/content/partials/commands/except.mdx b/content/packer/v1.10.x/content/partials/commands/except.mdx
new file mode 100644
index 0000000000..5677c0e119
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/commands/except.mdx
@@ -0,0 +1,10 @@
+- `-except=foo,bar,baz` - Run all the builds and post-processors except those
+ with the given comma-separated names. In legacy JSON templates, build names default to the
+ types of their builders (e.g. `docker` or
+ `amazon-ebs` or `virtualbox-iso`), unless a specific `name` attribute is
+ specified within the configuration. In HCL2 templates, the "name" is the
+ source block's "name" label, unless an in-build source definition adds the
+ "name" configuration option. Any post-processor following
+ a skipped post-processor will not run. Because post-processors can be nested
+ in arrays a different post-processor chain can still run. A post-processor
+ with an empty name will be ignored.
diff --git a/content/packer/v1.10.x/content/partials/commands/only.mdx b/content/packer/v1.10.x/content/partials/commands/only.mdx
new file mode 100644
index 0000000000..a6c901cb25
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/commands/only.mdx
@@ -0,0 +1,7 @@
+- `-only=foo,bar,baz` - Only run the builds with the given comma-separated
+ names. In legacy JSON templates, build names default to the
+ types of their builders (e.g. `docker` or
+ `amazon-ebs` or `virtualbox-iso`), unless a specific `name` attribute is
+ specified within the configuration. In HCL2 templates, the "name" is the
+ source block's "name" label, unless an in-build source definition adds the
+ "name" configuration option.
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/Config-not-required.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/Config-not-required.mdx
new file mode 100644
index 0000000000..f8b0957fe2
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/Config-not-required.mdx
@@ -0,0 +1,6 @@
+
+
+- `component_type` (string) - The specific Packer builder used to create the artifact.
+ For example, "amazon-ebs.example"
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/Config-required.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/Config-required.mdx
new file mode 100644
index 0000000000..2053ddc1d6
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/Config-required.mdx
@@ -0,0 +1,22 @@
+
+
+- `bucket_name` (string) - The name of the bucket your artifact is in.
+
+- `channel_name` (string) - The name of the channel to use when retrieving your artifact.
+ Either `channel_name` or `version_fingerprint` MUST be set.
+ If using several artifacts from a single version, you may prefer sourcing a version first,
+ and referencing it for subsequent uses, as every `hcp_packer_artifact` with the channel set will generate a
+ potentially billable HCP Packer request, but if several `hcp_packer_artifact`s use a shared `hcp_packer_version`
+ that will only generate one potentially billable request.
+
+- `version_fingerprint` (string) - The fingerprint of the version to use when retrieving your artifact.
+ Either this or `channel_name` MUST be set.
+ Mutually exclusive with `channel_name`
+
+- `platform` (string) - The name of the platform that your artifact is for.
+ For example, "aws", "azure", or "gce".
+
+- `region` (string) - The name of the region your artifact is in.
+ For example "us-east-1".
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/DatasourceOutput.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/DatasourceOutput.mdx
new file mode 100644
index 0000000000..dcd90f5909
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-artifact/DatasourceOutput.mdx
@@ -0,0 +1,31 @@
+
+
+- `platform` (string) - The name of the platform that the artifact exists in.
+ For example, "aws", "azure", or "gce".
+
+- `component_type` (string) - The specific Packer builder or post-processor used to create the artifact.
+
+- `created_at` (string) - The date and time at which the artifact was created.
+
+- `build_id` (string) - The ID of the build that created the artifact. This is a ULID, which is a
+ unique identifier similar to a UUID. It is created by the HCP Packer
+ Registry when a build is first created, and is unique to this build.
+
+- `version_id` (string) - The version ID. This is a ULID, which is a unique identifier similar
+ to a UUID. It is created by the HCP Packer Registry when a version is
+ first created, and is unique to this version.
+
+- `channel_id` (string) - The ID of the channel used to query the version. This value will be empty if the `version_fingerprint` was used
+ directly instead of a channel.
+
+- `packer_run_uuid` (string) - The UUID associated with the Packer run that created this artifact.
+
+- `external_identifier` (string) - Identifier or URL of the remote artifact as given by a build.
+ For example, ami-12345.
+
+- `region` (string) - The region as given by `packer build`. eg. "ap-east-1".
+ For locally managed clouds, this may map instead to a cluster, server or datastore.
+
+- `labels` (map[string]string) - The key:value metadata labels associated with this build.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/Config-not-required.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/Config-not-required.mdx
new file mode 100644
index 0000000000..70e7cd0d00
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/Config-not-required.mdx
@@ -0,0 +1,6 @@
+
+
+- `component_type` (string) - The specific Packer builder used to create the image.
+ For example, "amazon-ebs.example"
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/Config-required.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/Config-required.mdx
new file mode 100644
index 0000000000..95abfd1fe8
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/Config-required.mdx
@@ -0,0 +1,24 @@
+
+
+- `bucket_name` (string) - The name of the bucket your image is in.
+
+- `channel` (string) - The name of the channel to use when retrieving your image.
+ Either this or `iteration_id` MUST be set.
+ Mutually exclusive with `iteration_id`.
+ If using several images from a single iteration, you may prefer
+ sourcing an iteration first, and referencing it for subsequent uses,
+ as every `hcp-packer-image` with the channel set will generate a
+ potentially billable HCP Packer request, but if several
+ `hcp-packer-image`s use a shared `hcp-packer-iteration` that will
+ only generate one potentially billable request.
+
+- `iteration_id` (string) - The ID of the iteration to use when retrieving your image
+ Either this or `channel` MUST be set.
+ Mutually exclusive with `channel`
+
+- `cloud_provider` (string) - The name of the cloud provider that your image is for. For example,
+ "aws" or "gce".
+
+- `region` (string) - The name of the cloud region your image is in. For example "us-east-1".
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/DatasourceOutput.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/DatasourceOutput.mdx
new file mode 100644
index 0000000000..07e53af6f3
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-image/DatasourceOutput.mdx
@@ -0,0 +1,31 @@
+
+
+- `cloud_provider` (string) - The name of the cloud provider that the image exists in. For example,
+ "aws", "azure", or "gce".
+
+- `component_type` (string) - The specific Packer builder or post-processor used to create the image.
+
+- `created_at` (string) - The date and time at which the image was created.
+
+- `build_id` (string) - The ID of the build that created the image. This is a ULID, which is a
+ unique identifier similar to a UUID. It is created by the HCP Packer
+ Registry when an build is first created, and is unique to this build.
+
+- `iteration_id` (string) - The iteration ID. This is a ULID, which is a unique identifier similar
+ to a UUID. It is created by the HCP Packer Registry when an iteration is
+ first created, and is unique to this iteration.
+
+- `channel_id` (string) - The ID of the channel used to query the image iteration. This value will be empty if the `iteration_id` was used
+ directly instead of a channel.
+
+- `packer_run_uuid` (string) - The UUID associated with the Packer run that created this image.
+
+- `id` (string) - ID or URL of the remote cloud image as given by a build.
+
+- `region` (string) - The cloud region as given by `packer build`. eg. "ap-east-1".
+ For locally managed clouds, this may map instead to a cluster, server
+ or datastore.
+
+- `labels` (map[string]string) - The key:value metadata labels associated with this build.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-iteration/Config-required.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-iteration/Config-required.mdx
new file mode 100644
index 0000000000..582bb82902
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-iteration/Config-required.mdx
@@ -0,0 +1,7 @@
+
+
+- `bucket_name` (string) - The name of the bucket your image is in.
+
+- `channel` (string) - The name of the channel to use when retrieving your image
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-iteration/DatasourceOutput.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-iteration/DatasourceOutput.mdx
new file mode 100644
index 0000000000..469a09f051
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-iteration/DatasourceOutput.mdx
@@ -0,0 +1,32 @@
+
+
+- `author_id` (string) - who created the iteration
+
+- `bucket_name` (string) - Name of the bucket that the iteration was retrieved from
+
+- `complete` (bool) - If true, this iteration is considered "ready to use" and will be
+ returned even if the include_incomplete flag is "false" in the
+ list iterations request. Note that if you are retrieving an iteration
+ using a channel, this will always be "true"; channels cannot be assigned
+ to incomplete iterations.
+
+- `created_at` (string) - The date the iteration was created.
+
+- `fingerprint` (string) - The fingerprint of the build; this could be a git sha or other unique
+ identifier as set by the Packer build that created this iteration.
+
+- `id` (string) - The iteration ID. This is a ULID, which is a unique identifier similar
+ to a UUID. It is created by the HCP Packer Registry when an iteration is
+ first created, and is unique to this iteration.
+
+- `incremental_version` (int32) - The version number assigned to an iteration. This number is an integer,
+ and is created by the HCP Packer Registry once an iteration is
+ marked "complete". If a new iteration is marked "complete", the version
+ that HCP Packer assigns to it will always be the highest previous
+ iteration version plus one.
+
+- `updated_at` (string) - The date when this iteration was last updated.
+
+- `channel_id` (string) - The ID of the channel used to query the image iteration.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-version/Config-required.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-version/Config-required.mdx
new file mode 100644
index 0000000000..f97aced7e3
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-version/Config-required.mdx
@@ -0,0 +1,7 @@
+
+
+- `bucket_name` (string) - The bucket name in the HCP Packer Registry.
+
+- `channel_name` (string) - The channel name in the given bucket to use for retrieving the version.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/hcp-packer-version/DatasourceOutput.mdx b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-version/DatasourceOutput.mdx
new file mode 100644
index 0000000000..3a14240ce0
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/hcp-packer-version/DatasourceOutput.mdx
@@ -0,0 +1,25 @@
+
+
+- `author_id` (string) - Name of the author who created this version.
+
+- `bucket_name` (string) - The name of the bucket that this version is associated with.
+
+- `status` (string) - Current state of the version.
+
+- `created_at` (string) - The date the version was created.
+
+- `fingerprint` (string) - The fingerprint of the version; this is a unique identifier set by the Packer build
+ that created this version.
+
+- `id` (string) - The version ID. This is a ULID, which is a unique identifier similar
+ to a UUID. It is created by the HCP Packer Registry when a version is
+ first created, and is unique to this version.
+
+- `name` (string) - The version name is created by the HCP Packer Registry once a version is
+ "complete". Incomplete or failed versions currently default to having a name "v0".
+
+- `updated_at` (string) - The date when this version was last updated.
+
+- `channel_id` (string) - The ID of the channel used to query this version.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/http/Config-not-required.mdx b/content/packer/v1.10.x/content/partials/datasource/http/Config-not-required.mdx
new file mode 100644
index 0000000000..24814625fd
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/http/Config-not-required.mdx
@@ -0,0 +1,5 @@
+
+
+- `request_headers` (map[string]string) - A map of strings representing additional HTTP headers to include in the request.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/http/Config-required.mdx b/content/packer/v1.10.x/content/partials/datasource/http/Config-required.mdx
new file mode 100644
index 0000000000..a9cc5183bc
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/http/Config-required.mdx
@@ -0,0 +1,5 @@
+
+
+- `url` (string) - The URL to request data from. This URL must respond with a `200 OK` response and a `text/*` or `application/json` Content-Type.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/http/DatasourceOutput.mdx b/content/packer/v1.10.x/content/partials/datasource/http/DatasourceOutput.mdx
new file mode 100644
index 0000000000..8581fa9622
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/http/DatasourceOutput.mdx
@@ -0,0 +1,10 @@
+
+
+- `url` (string) - The URL the data was requested from.
+
+- `body` (string) - The raw body of the HTTP response.
+
+- `request_headers` (map[string]string) - A map of strings representing the response HTTP headers.
+ Duplicate headers are concatenated with, according to [RFC2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2).
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/null/Config-required.mdx b/content/packer/v1.10.x/content/partials/datasource/null/Config-required.mdx
new file mode 100644
index 0000000000..c1b02ed656
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/null/Config-required.mdx
@@ -0,0 +1,5 @@
+
+
+- `input` (string) - This variable will get stored as "output" in the output spec.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/null/Config.mdx b/content/packer/v1.10.x/content/partials/datasource/null/Config.mdx
new file mode 100644
index 0000000000..7160ef43d0
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/null/Config.mdx
@@ -0,0 +1,7 @@
+
+
+The Null data source is designed to demonstrate how data sources work, and
+to provide a test plugin. It does not do anything useful; you assign an
+input string and it gets returned as an output string.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasource/null/DatasourceOutput.mdx b/content/packer/v1.10.x/content/partials/datasource/null/DatasourceOutput.mdx
new file mode 100644
index 0000000000..99cb08159d
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasource/null/DatasourceOutput.mdx
@@ -0,0 +1,5 @@
+
+
+- `output` (string) - Output will return the input variable, as output.
+
+
diff --git a/content/packer/v1.10.x/content/partials/datasources/local-dependency-limitation.mdx b/content/packer/v1.10.x/content/partials/datasources/local-dependency-limitation.mdx
new file mode 100644
index 0000000000..8da7f51c90
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/datasources/local-dependency-limitation.mdx
@@ -0,0 +1,42 @@
+
+At this present time the use of locals within data sources such as the example below is not supported.
+
+```hcl
+locals {
+ cloud_owners = ["happycloud"]
+ cloud_base_filter_name = "cloud-hvm-2.0.*-x86_64-gp2"
+}
+
+data "happycloud" "happycloud-linux2-east" {
+ filters = {
+ name = local.cloud_base_filter_name
+ }
+ most_recent = true
+ owners = local.cloud_owners
+}
+```
+
+Locals can reference data sources but data sources can not reference locals to avoid cyclic dependencies, where a local
+may reference a data source that references the same local or some other locals variable. The preferred method, at this time,
+for referencing user input data within a data source is to use the `variable` block.
+
+```hcl
+variable "cloud_base_filter_name" {
+ type = string
+ default = "cloud-hvm-2.0.*-x86_64-gp2"
+}
+
+variable "cloud_owners" {
+ type = string
+ default = "happycloud"
+}
+
+data "happycloud" "happycloud-linux2-east" {
+ filters = {
+ name = var.cloud_base_filter_name
+ }
+ most_recent = true
+ owners = var.cloud_owners
+}
+```
+
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/beta-hcl2-note.mdx b/content/packer/v1.10.x/content/partials/from-1.5/beta-hcl2-note.mdx
new file mode 100644
index 0000000000..190ee93e6e
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/beta-hcl2-note.mdx
@@ -0,0 +1,7 @@
+-> **Note:** This page is about HCL2 Packer templates. HCL2 templates
+were first introduced as a beta feature into Packer version 1.5. As of v1.7,
+HCL2 support is no longer in beta, and is the preferred way to write Packer
+configuration. For the old-style stable configuration language see
+[template docs](/packer/docs/templates/legacy_json_templates). As of v1.6.2, you can
+convert your legacy JSON template into an HCL2 config file using the
+[hcl2_upgrade command](/packer/docs/commands/hcl2_upgrade).
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/builds/example-block.mdx b/content/packer/v1.10.x/content/partials/from-1.5/builds/example-block.mdx
new file mode 100644
index 0000000000..2eb34b51f8
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/builds/example-block.mdx
@@ -0,0 +1,31 @@
+```hcl
+# build.pkr.hcl
+build {
+ # use the `name` field to name a build in the logs.
+ # For example this present config will display
+ # "buildname.amazon-ebs.example-1" and "buildname.amazon-ebs.example-2"
+ name = "buildname"
+
+ sources = [
+ # use the optional plural `sources` list to simply use a `source`
+ # without changing any field.
+ "source.amazon-ebs.example-1",
+ ]
+
+ source "source.amazon-ebs.example-2" {
+ # Use the singular `source` block set specific fields.
+ # Note that fields cannot be overwritten, in other words, you cannot
+ # set the 'output' field from the top-level source block and here.
+ output = "different value"
+ name = "differentname"
+ }
+
+ provisioner "shell" {
+ scripts = fileset(".", "scripts/{install,secure}.sh")
+ }
+
+ post-processor "shell-local" {
+ inline = ["echo Hello World from ${source.type}.${source.name}"]
+ }
+}
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/contextual-source-variables.mdx b/content/packer/v1.10.x/content/partials/from-1.5/contextual-source-variables.mdx
new file mode 100644
index 0000000000..db375ef707
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/contextual-source-variables.mdx
@@ -0,0 +1,36 @@
+# Source Variables
+
+It is possible to access the `name` and `type` of your `source` from
+provisioners and post-processors:
+
+```hcl
+source "null" "first-example" {
+ communicator = "none"
+}
+
+build {
+ name = "roles"
+
+ source "null.first-example" {
+ name = "consul"
+ }
+ source "null.first-example" {
+ name = "nomad"
+ }
+ source "null.first-example" {
+ name = "vault"
+ }
+ sources = ["null.first-example"]
+
+ provisioner "shell-local" {
+ 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
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/datasources/example-block.mdx b/content/packer/v1.10.x/content/partials/from-1.5/datasources/example-block.mdx
new file mode 100644
index 0000000000..b77bae8e80
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/datasources/example-block.mdx
@@ -0,0 +1,6 @@
+```hcl
+# datasource.pkr.hcl
+data "amazon-ami" "basic-example" {
+ // ...
+}
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/legacy-json-warning.mdx b/content/packer/v1.10.x/content/partials/from-1.5/legacy-json-warning.mdx
new file mode 100644
index 0000000000..026ac2368d
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/legacy-json-warning.mdx
@@ -0,0 +1,6 @@
+-> **Note:** This page is about older-style JSON Packer templates. JSON
+templates are still supported by the Packer core, but new features added to the
+Packer core may not be implemented for JSON templates. We recommend you
+transition to HCL templates as soon as is convenient for you, in order to have
+the best possible experience with Packer. To help you upgrade your templates,
+we have written an [hcl2_upgrade command](/packer/docs/commands/hcl2_upgrade) command.
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/locals/example-block.mdx b/content/packer/v1.10.x/content/partials/from-1.5/locals/example-block.mdx
new file mode 100644
index 0000000000..ed151e746c
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/locals/example-block.mdx
@@ -0,0 +1,15 @@
+```hcl
+# locals.pkr.hcl
+locals {
+ # locals can be bare values like:
+ wee = local.baz
+ # locals can also be set with other variables :
+ baz = "Foo is '${var.foo}' but not '${local.wee}'"
+}
+
+# Use the singular local block if you need to mark a local as sensitive
+local "mylocal" {
+ expression = "${var.secret_api_key}"
+ sensitive = true
+}
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/sources/example-block.mdx b/content/packer/v1.10.x/content/partials/from-1.5/sources/example-block.mdx
new file mode 100644
index 0000000000..652371c3ce
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/sources/example-block.mdx
@@ -0,0 +1,6 @@
+```hcl
+# sources.pkr.hcl
+source "happycloud" "foo" {
+ // ...
+}
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/variables/assignment.mdx b/content/packer/v1.10.x/content/partials/from-1.5/variables/assignment.mdx
new file mode 100644
index 0000000000..737508a996
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/variables/assignment.mdx
@@ -0,0 +1,7 @@
+## Assigning Values to input Variables
+
+Once a variable is declared in your configuration, you can set it:
+
+- Individually, with the `-var foo=bar` command line option.
+- In variable definitions files, either specified on the command line with the `-var-files values.pkrvars.hcl` or automatically loaded (`*.auto.pkrvars.hcl`).
+- As environment variables, for example: `PKR_VAR_foo=bar`
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/variables/custom-validation.mdx b/content/packer/v1.10.x/content/partials/from-1.5/variables/custom-validation.mdx
new file mode 100644
index 0000000000..c89806fe1d
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/variables/custom-validation.mdx
@@ -0,0 +1,75 @@
+### Custom Validation Rules
+
+[inpage-validation]: #custom-validation-rules
+
+In addition to Type Constraints, you can specify arbitrary custom validation
+rules for a particular variable using one or more `validation` block nested
+within the corresponding `variable` block:
+
+```hcl
+variable "image_id" {
+ type = string
+ description = "The ID of the machine image (AMI) to use for the server."
+
+ validation {
+ condition = length(var.image_id) > 4 && substr(var.image_id, 0, 4) == "ami-"
+ error_message = "The image_id value must be a valid AMI ID, starting with \"ami-\"."
+ }
+}
+```
+
+The `condition` argument is an expression that must use the value of the
+variable to return `true` if the value is valid or `false` if it is invalid.
+The expression can refer only to the variable that the condition applies to,
+and _must not_ produce errors.
+
+If the failure of an expression is the basis of the validation decision, use
+[the `can` function](/packer/docs/templates/hcl_templates/functions/conversion/can) to detect such errors. For example:
+
+```hcl
+variable "image_id" {
+ type = string
+ description = "The ID of the machine image (AMI) to use for the server."
+
+ validation {
+ # regex(...) fails if it cannot find a match
+ condition = can(regex("^ami-", var.image_id))
+ error_message = "The image_id value must be a valid AMI ID, starting with \"ami-\"."
+ }
+}
+```
+
+If `condition` evaluates to `false`, an error message including the sentences
+given in `error_message` will be produced. The error message string should be
+at least one full sentence explaining the constraint that failed, using a
+sentence structure similar to the above examples.
+
+Validation also works with more complex cases:
+
+```hcl
+variable "image_metadata" {
+
+ default = {
+ key: "value",
+ something: {
+ foo: "bar",
+ }
+ }
+
+ validation {
+ condition = length(var.image_metadata.key) > 4
+ error_message = "The image_metadata.key field must be more than 4 runes."
+ }
+
+ validation {
+ condition = can(var.image_metadata.something.foo)
+ error_message = "The image_metadata.something.foo field must exist."
+ }
+
+ validation {
+ condition = substr(var.image_metadata.something.foo, 0, 3) == "bar"
+ error_message = "The image_metadata.something.foo field must start with \"bar\"."
+ }
+
+}
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/variables/foo-block.mdx b/content/packer/v1.10.x/content/partials/from-1.5/variables/foo-block.mdx
new file mode 100644
index 0000000000..5b68c1c087
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/variables/foo-block.mdx
@@ -0,0 +1,11 @@
+```hcl
+# variables.pkr.hcl
+variable "foo" {
+ type = string
+ default = "the default value of the `foo` variable"
+ description = "description of the `foo` variable"
+ sensitive = false
+ # When a variable is sensitive all string-values from that variable will be
+ # obfuscated from Packer's output.
+}
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/variables/foo-pkrvar.mdx b/content/packer/v1.10.x/content/partials/from-1.5/variables/foo-pkrvar.mdx
new file mode 100644
index 0000000000..04f44e1be0
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/variables/foo-pkrvar.mdx
@@ -0,0 +1,4 @@
+```hcl
+# foo.pkrvars.hcl
+foo = "value"
+```
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/variables/must-be-set.mdx b/content/packer/v1.10.x/content/partials/from-1.5/variables/must-be-set.mdx
new file mode 100644
index 0000000000..ecf887360c
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/variables/must-be-set.mdx
@@ -0,0 +1,35 @@
+## 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.
diff --git a/content/packer/v1.10.x/content/partials/from-1.5/variables/sensitive.mdx b/content/packer/v1.10.x/content/partials/from-1.5/variables/sensitive.mdx
new file mode 100644
index 0000000000..5e53f4c85c
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/from-1.5/variables/sensitive.mdx
@@ -0,0 +1,26 @@
+### Suppressing Sensitive Variables
+
+[inpage-sensitive]: #suppressing-sensitive-variables
+
+
+When a variable is sensitive all string-values from that variable will be
+obfuscated from Packer's output :
+
+```hcl
+# var-foo.pkr.hcl
+variable "foo" {
+ sensitive = true
+ default = {
+ key = "SECR3TP4SSW0RD"
+ }
+}
+```
+
+```shell-session
+$ packer inspect var-foo.pkr.hcl
+Packer Inspect: HCL2 mode
+
+> input-variables:
+var.foo: "{\n \"key\" = \"\"\n }"
+...
+```
diff --git a/content/packer/v1.10.x/content/partials/guides/hcl2-beta-note.mdx b/content/packer/v1.10.x/content/partials/guides/hcl2-beta-note.mdx
new file mode 100644
index 0000000000..6b8a621aba
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/guides/hcl2-beta-note.mdx
@@ -0,0 +1 @@
+-> **Note:** Packer version **1.5.0** introduced support for HCL2 templates as a beta feature. As of version **1.7.0**, HCL2 support is no longer in beta and is the preferred way to write Packer configuration(s).
diff --git a/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Agent-Auth-not-required.mdx b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Agent-Auth-not-required.mdx
new file mode 100644
index 0000000000..efc409dcb1
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Agent-Auth-not-required.mdx
@@ -0,0 +1,6 @@
+- `ssh_agent_auth` (bool) - If true, the local SSH agent will be used to authenticate connections to
+ the source instance. No temporary keypair will be created, and the
+ values of [`ssh_password`](#ssh_password) and
+ [`ssh_private_key_file`](#ssh_private_key_file) will be ignored. The
+ environment variable `SSH_AUTH_SOCK` must be set for this option to work
+ properly.
diff --git a/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Key-Pair-Name-not-required.mdx b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Key-Pair-Name-not-required.mdx
new file mode 100644
index 0000000000..88e5a7a93a
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Key-Pair-Name-not-required.mdx
@@ -0,0 +1,7 @@
+- `ssh_keypair_name` (string) - If specified, this is the key that will be used for SSH with the
+ machine. The key must match a key pair name loaded up into the remote.
+ By default, this is blank, and Packer will generate a temporary keypair
+ unless [`ssh_password`](#ssh_password) is used.
+ [`ssh_private_key_file`](#ssh_private_key_file) or
+ [`ssh_agent_auth`](#ssh_agent_auth) must be specified when
+ [`ssh_keypair_name`](#ssh_keypair_name) is utilized.
diff --git a/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Private-Key-File-not-required.mdx b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Private-Key-File-not-required.mdx
new file mode 100644
index 0000000000..a1925982a4
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Private-Key-File-not-required.mdx
@@ -0,0 +1,3 @@
+- `ssh_private_key_file` (string) - Path to a PEM encoded private key file to use to authenticate with SSH.
+ The `~` can be used in path and will be expanded to the home directory
+ of current user.
diff --git a/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Temporary-Key-Pair-not-required.mdx b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Temporary-Key-Pair-not-required.mdx
new file mode 100644
index 0000000000..98c2a76378
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/helper/communicator/SSH-Temporary-Key-Pair-not-required.mdx
@@ -0,0 +1,3 @@
+- `temporary_key_pair_name` (string) - The name of the temporary key pair to generate. By default, Packer
+ generates a name that looks like `packer_`, where <UUID> is
+ a 36 character unique identifier.
diff --git a/content/packer/v1.10.x/content/partials/packer-plugin-sdk/bootcommand/BootConfig-not-required.mdx b/content/packer/v1.10.x/content/partials/packer-plugin-sdk/bootcommand/BootConfig-not-required.mdx
new file mode 100644
index 0000000000..74a6556eeb
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/packer-plugin-sdk/bootcommand/BootConfig-not-required.mdx
@@ -0,0 +1,22 @@
+
+
+- `boot_keygroup_interval` (duration string | ex: "1h5m2s") - Time to wait after sending a group of key pressses. The value of this
+ should be a duration. Examples are `5s` and `1m30s` which will cause
+ Packer to wait five seconds and one minute 30 seconds, respectively. If
+ this isn't specified, a sensible default value is picked depending on
+ the builder type.
+
+- `boot_wait` (duration string | ex: "1h5m2s") - The time to wait after booting the initial virtual machine before typing
+ the `boot_command`. The value of this should be a duration. Examples are
+ `5s` and `1m30s` which will cause Packer to wait five seconds and one
+ minute 30 seconds, respectively. If this isn't specified, the default is
+ `10s` or 10 seconds. To set boot_wait to 0s, use a negative number, such
+ as "-1s"
+
+- `boot_command` ([]string) - This is an array of commands to type when the virtual machine is first
+ booted. The goal of these commands should be to type just enough to
+ initialize the operating system installer. Special keys can be typed as
+ well, and are covered in the section below on the boot command. If this
+ is not specified, it is assumed the installer will start itself.
+
+
diff --git a/content/packer/v1.10.x/content/partials/packer-plugin-sdk/bootcommand/BootConfig.mdx b/content/packer/v1.10.x/content/partials/packer-plugin-sdk/bootcommand/BootConfig.mdx
new file mode 100644
index 0000000000..3faa491f04
--- /dev/null
+++ b/content/packer/v1.10.x/content/partials/packer-plugin-sdk/bootcommand/BootConfig.mdx
@@ -0,0 +1,130 @@
+
+
+The boot configuration is very important: `boot_command` specifies the keys
+to type when the virtual machine is first booted in order to start the OS
+installer. This command is typed after boot_wait, which gives the virtual
+machine some time to actually load.
+
+The boot_command is an array of strings. The strings are all typed in
+sequence. It is an array only to improve readability within the template.
+
+There are a set of special keys available. If these are in your boot
+command, they will be replaced by the proper key:
+
+- `` - Backspace
+
+- `` - Delete
+
+- `` - Simulates an actual "enter" or "return" keypress.
+
+- `` - Simulates pressing the escape key.
+
+- `` - Simulates pressing the tab key.
+
+- ` - ` - Simulates pressing a function key.
+
+- `` - Simulates pressing an arrow key.
+
+- `` - Simulates pressing the spacebar.
+
+- `` - Simulates pressing the insert key.
+
+- `` - Simulates pressing the home and end keys.
+
+- `` - Simulates pressing the page up and page down
+ keys.
+
+- `