diff --git a/website/content/docs/templates/index.mdx b/website/content/docs/templates/index.mdx index b3c0ccd66..2f3e23144 100644 --- a/website/content/docs/templates/index.mdx +++ b/website/content/docs/templates/index.mdx @@ -1,31 +1,26 @@ --- description: | - This section describes the configuration language used to create Packer - templates. -page_title: Templates + Packer templates are configuration files that determine Packer behavior. Learn about the Packer template configuration language. +page_title: Packer templates reference overview --- -# Packer Templates +# Packer templates reference overview -Packer's behavior is determined by the Packer template, which consists of a -series of declarations and commands for Packer to follow. This template tells -Packer what plugins (builders, provisioners, post-processors) to use, how to -configure each of those plugins, and what order to run them in. +This topic provides overview information about Packer templates, which are configuration files that determine Packer behavior. + +## Introduction + +A Packer template contains a series of declarations and commands for Packer to follow. Templates define the following instructions for Packer: + +- Which plugins, such as builders, provisioners, and post-processors to use +- How to configure the plugins +- In what order to run them The template contains flexible variable injection tools, as well as built-in functions to help you customize your builds. -Historically, Packer has used a JSON template for its configuration, but Packer -is transitioning to a new template configuration format that uses HCL2 -- the -same configuration language used by Terraform and HashiCorp's other products. -This format is more flexible, more modular, and more concise than the original -JSON template format. While the JSON format is still supported, certain -new features in the Packer core will only be implemented for the newer HCL -format. Please use the side bar to find documentation for the different -template formats. +## Template language -From version **1.7.0**, HCL2 becomes officially the preferred way to write Packer -configuration(s). +Packer supports templates written in [HCL2](/packer/docs/templates/hcl_templates) or [JSON](/packer/docs/templates/legacy_json_templates). Since v1.7.0, HCL2 is the official format for Packer configurations. -If you need help upgrading a JSON template to an HCL template, check -our upgrade guide [here](/packer/tutorials/configuration-language/hcl2-upgrade). +HCL2 is also the configuration language used in configurations for Terraform other HashiCorp products. It is more flexible, modular, and concise than the JSON template format. Refer to [Upgrade Packer JSON template to HCL2](/packer/tutorials/configuration-language/hcl2-upgrade) for a tutorial on upgrading JSON templates to HCL templates. diff --git a/website/content/docs/templates/json_to_hcl.mdx b/website/content/docs/templates/json_to_hcl.mdx index 2be56685d..77feb1986 100644 --- a/website/content/docs/templates/json_to_hcl.mdx +++ b/website/content/docs/templates/json_to_hcl.mdx @@ -1,20 +1,23 @@ --- description: | - This section highlights the differences between JSON and HCL2 templates and explains the parallels between the specifications. -page_title: JSON to HCL + Learn about the differences between JSON and HCL2 templates and how converting templates to HCL affects plugins. +page_title: Differences between HCL2 and JSON templates --- -# Packer templates +# Differences between HCL2 and JSON templates -Packer uses templates to orchestrate builds for one or more images. -In [legacy JSON templates](/packer/docs/templates/legacy_json_templates), you would declare a series of builders, provisioners and post-processors to build images. -In [HCL2 templates](/packer/docs/templates/hcl_templates), things are different, as the configuration language allows you to specify builders through sources, and weave them in build blocks. +This document explains the differences between JSON to HCL2 templates, including how converting JSON templates to HCL2 affects builder, provisioner, and post-processor behavior. -This document aims to explain the parallels between the two configuration template types, and what you -should expect when moving a template away from JSON to HCL2. +## Introduction + +Packer uses JSON or HCL2 templates to orchestrate builds for one or more artifacts. + +In [legacy JSON templates](/packer/docs/templates/legacy_json_templates), declare a series of builders, provisioners and post-processors to build images. + +In [HCL2 templates](/packer/docs/templates/hcl_templates), you can specify builders through sources and collect them into build blocks. + +You can use the `packer hcl2_upgrade` command when converting your existing JSON templates to HCL2. Refer to the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) page for more information on its usage. -In addition to this document, you may find the `packer hcl2_upgrade` command useful when converting your existing JSON templates to HCL2. -Refer to the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) page for more information on its usage. ## Builders diff --git a/website/content/docs/templates/legacy_json_templates/builders.mdx b/website/content/docs/templates/legacy_json_templates/builders.mdx index 42d3afa15..4996d367e 100644 --- a/website/content/docs/templates/legacy_json_templates/builders.mdx +++ b/website/content/docs/templates/legacy_json_templates/builders.mdx @@ -1,20 +1,21 @@ --- description: > - Within the template, the builders section contains an array of all the - builders - - that Packer should use to generate machine images for the template. -page_title: Builders - Templates + The `builders` block contains builders that create machines and generate images. Learn how to configure the `builders` block in JSON templates for Packer. +page_title: builders reference for JSON templates --- +# `builders` reference for JSON templates + +This topic provides reference information about the `builders` block in JSON templates. + `@include 'from-1.5/legacy-json-warning.mdx'` -# Template Builders +## Introduction -Within the template, the builders section contains an array of all the builders +The `builders` block contains an array of all the builders that Packer should use to generate machine images for the template. -Builders are responsible for creating machines and generating images from them +Builders create machines and generate images from them for various platforms. For example, there are separate builders for EC2, VMware, VirtualBox, etc. Packer comes with many builders by default, and can also be extended to add new builders. diff --git a/website/content/docs/templates/legacy_json_templates/communicator.mdx b/website/content/docs/templates/legacy_json_templates/communicator.mdx index a1c32a9c6..59d4073e0 100644 --- a/website/content/docs/templates/legacy_json_templates/communicator.mdx +++ b/website/content/docs/templates/legacy_json_templates/communicator.mdx @@ -1,19 +1,19 @@ --- description: | - Communicators are the mechanism Packer uses to upload files, execute scripts, - etc. with the machine being created. -page_title: Communicators - Templates + Packer uses communicators to upload files, execute scripts, and perform actions on the machine it creates. Learn how to configure communicators in JSON templates. +page_title: Communicators reference for JSON templates --- -`@include 'from-1.5/legacy-json-warning.mdx'` +# Communicators reference for JSON templates + +This topic describes how to use communicators in Packer templates written in JSON format. -# Template Communicators +`@include 'from-1.5/legacy-json-warning.mdx'` -Communicators are the mechanism Packer uses to upload files, execute scripts, -etc. with the machine being created. +## Description -Communicators are configured within the -[builder](/packer/docs/templates/legacy_json_templates/builders) section. +Packer uses communicators to upload files, execute scripts, and perform other actions on the machine being created. Configure communicators in the +[`builder`](/packer/docs/templates/legacy_json_templates/builders) section. All communicators have the following options: diff --git a/website/content/docs/templates/legacy_json_templates/engine.mdx b/website/content/docs/templates/legacy_json_templates/engine.mdx index e603320c5..20c16ea67 100644 --- a/website/content/docs/templates/legacy_json_templates/engine.mdx +++ b/website/content/docs/templates/legacy_json_templates/engine.mdx @@ -1,19 +1,21 @@ --- description: | - All strings within templates are processed by a common Packer templating - engine, where variables and functions can be used to modify the value of a - configuration parameter at runtime. -page_title: Template Engine - Templates + The JSON template engine procsses strings in JSON templates. Learn how to use JSON template engine functions and variables. +page_title: JSON template engine reference --- -# Template Engine +# JSON template engine reference -All strings within templates are processed by a common Packer templating -engine, where variables and functions can be used to modify the value of a -configuration parameter at runtime. +This topic describe the Packer engine that processes JSON templates. `@include 'from-1.5/legacy-json-warning.mdx'` +## Description + +All strings within templates are processed by a common Packer templating +engine. The engine uses variables and functions to modify the value of a +configuration parameter at runtime. + The syntax of templates uses the following conventions: - Anything template related happens within double-braces: `{{ }}`. @@ -234,9 +236,9 @@ respectively. user variables. See the [user variable](/packer/docs/templates/legacy_json_templates/user-variables) documentation for more information on user variables. -# isotime Function Format Reference +## `isotime` Function Format Reference -The isotime template engine uses Go to generate timestamps. If you're +The `isotime` template engine uses Go to generate timestamps. If you're unfamiliar with Go, then the way you format the timestamp is going to feel a bit unusual compared to how you may be used to formatting datetime strings. @@ -331,7 +333,7 @@ _The values in parentheses are the abbreviated, or 24-hour clock values_ Note that "-0700" is always formatted into "+0000" because `isotime` is always UTC time. -# split Function Format Reference +## `split` Function Format Reference The function `split` takes an input string, a seperator string, and a numeric component value and returns the requested substring. @@ -370,13 +372,13 @@ this case, on the `fixed-string` value): } ``` -# replace Function Format Reference +## `replace` Function Format Reference -Here are some examples using the replace options: +Here are some examples using the `replace` options: ```liquid build_name = foo-bar-provider {{ replace_all "-" "/" build_name }} = foo/bar/provider {{ build_name | replace "-" "/" 1 }} = foo/bar-provider -``` +``` \ No newline at end of file diff --git a/website/content/docs/templates/legacy_json_templates/index.mdx b/website/content/docs/templates/legacy_json_templates/index.mdx index 3a01ca7a5..3c8247537 100644 --- a/website/content/docs/templates/legacy_json_templates/index.mdx +++ b/website/content/docs/templates/legacy_json_templates/index.mdx @@ -1,25 +1,20 @@ --- description: > - The JSON templates are JSON files that configure the various components - of Packer in order to create one or more machine images. Templates are - portable, static, and readable and writable by both humans and computers. - This has the added benefit of being able to not only create and modify - templates by hand, but also write scripts to dynamically create or modify - templates. -page_title: JSON Templates + JSON templates are files that configure the Packer components that create one or more machine images. Learn how to configure JSON templates. +page_title: JSON templates configuration reference --- +# JSON templates configuration reference + +This topic provides reference information for creating JSON templates for Packer. + `@include 'from-1.5/legacy-json-warning.mdx'` -# JSON Templates +## Introduction -These Packer templates are JSON files that configure the various components +You can create Packer templates as JSON files that configure the various components of Packer in order to create one or more machine images. Templates are portable, -static, and readable and writable by both humans and computers. - -Templates are given to commands such as `packer build`, which will take the -template and actually run the builds within it, producing any resulting machine -images. +static, and readable and writable by both humans and computers. Use the Packer CLI to run builds described in the template to produce any resulting machine images. ## JSON Template Structure diff --git a/website/content/docs/templates/legacy_json_templates/post-processors.mdx b/website/content/docs/templates/legacy_json_templates/post-processors.mdx index b694d8eb4..72c5e1a31 100644 --- a/website/content/docs/templates/legacy_json_templates/post-processors.mdx +++ b/website/content/docs/templates/legacy_json_templates/post-processors.mdx @@ -1,27 +1,24 @@ --- description: | - The post-processor section within a template configures any post-processing - that will be done to images built by the builders. Examples of post-processing - would be compressing files, uploading artifacts, etc. -page_title: Post-Processors - Templates + The `post-processor` block defines actions to perform on the images after they are built. Learn how to configure the `post-processor` block in JSON templates. +page_title: post-processors reference for JSON templates --- +# `post-processors` reference for JSON templates + +This documentation describes how to configure a `post-processor` block in JSON +templates. Refer to the documentation for each post-processor type for their specific configuration options. + `@include 'from-1.5/legacy-json-warning.mdx'` -# Template Post-Processors +## Description -The post-processor section within a template configures any post-processing -that will be done to images built by the builders. Examples of post-processing -would be compressing files, uploading artifacts, etc. +The `post-processor` block defines additional actions to perform on the images built by the builders. For example, you can configure the `post-processor` to compress files and upload artifacts. Post-processors are _optional_. If no post-processors are defined within a template, then no post-processing will be done to the image. The resulting artifact of a build is just the image outputted by the builder. -This documentation page will cover how to configure a post-processor in a -template. The specific configuration options available for each post-processor, -however, must be referenced from the documentation for that specific -post-processor. Within a template, a section of post-processor definitions looks like this: diff --git a/website/content/docs/templates/legacy_json_templates/provisioners.mdx b/website/content/docs/templates/legacy_json_templates/provisioners.mdx index 5ecf66023..207790dd9 100644 --- a/website/content/docs/templates/legacy_json_templates/provisioners.mdx +++ b/website/content/docs/templates/legacy_json_templates/provisioners.mdx @@ -1,30 +1,22 @@ --- description: | - Within the template, the provisioners section contains an array of all the - provisioners that Packer should use to install and configure software within - running machines prior to turning them into machine images. -page_title: Provisioners - Templates + The `provisioners` block contains provisioners that Packer should use to install and configure software on machines. Learn how to configure provisioners in JSON templates. +page_title: provisioners reference for JSON templates --- -`@include 'from-1.5/legacy-json-warning.mdx'` +# `provisioners` reference for JSON templates + +This topic provides reference information about the `provisioners` block in JSON templates for Packer. Refer to the documentation for specific provisioner types to learn about their configuration options. -# Template Provisioners +`@include 'from-1.5/legacy-json-warning.mdx'` -Within the template, the provisioners section contains an array of all the -provisioners that Packer should use to install and configure software within -running machines prior to turning them into machine images. +## Description -Provisioners are _optional_. If no provisioners are defined within a template, -then no software other than the defaults will be installed within the resulting -machine images. This is not typical, however, since much of the value of Packer -is to produce multiple identical images of pre-configured software. +The `provisioners` block contains provisioners that Packer should use to install and configure software within running machines prior to turning them into machine images. -This documentation page will cover how to configure a provisioner in a -template. The specific configuration options available for each provisioner, -however, must be referenced from the documentation for that specific -provisioner. +Provisioners are optional. When you omit the `provisioners` block, Packer installs only the default software within the resulting machine images. -Within a template, a section of provisioner definitions looks like this: +Use the following syntax to add the `provisioners` block to your JSON template: ```json { diff --git a/website/content/docs/templates/legacy_json_templates/user-variables.mdx b/website/content/docs/templates/legacy_json_templates/user-variables.mdx index b3c00d620..9f0396c1d 100644 --- a/website/content/docs/templates/legacy_json_templates/user-variables.mdx +++ b/website/content/docs/templates/legacy_json_templates/user-variables.mdx @@ -1,18 +1,18 @@ --- description: | - User variables allow your templates to be further configured with variables - from the command-line, environment variables, or files. This lets you - parameterize your templates so that you can keep secret tokens, - environment-specific data, and other types of information out of your - templates. This maximizes the portability and shareability of the template. -page_title: User Variables - Templates + The `variables` block contains parameterizd values for your templates. Learn how configure `variables` to improve security, portability, and shareability of the template. +page_title: variables reference for JSON templates --- +# `variables` reference for JSON templates + +This topic describes how to use user variables in Packer templates written in JSON. + `@include 'from-1.5/legacy-json-warning.mdx'` -# Template User Variables +## Description -User variables allow your templates to be further configured with variables +The `variables` block ets 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 @@ -68,7 +68,7 @@ User variables are used by calling the `{{user}}` function in the form of within the template: in builders, provisioners, _anywhere outside the `variables` section_. User variables are available globally within the rest of the template. -## Environment Variables +## Environment variables Environment variables can be used within your template using user variables. The `env` function is available _only_ within the default value of a user @@ -119,7 +119,7 @@ The configuration for consul (address, tokens, ...) must be specified as environment variables, as specified in the [Documentation](/consul/docs/commands#environment-variables). -## Vault Variables +## Vault variables Secrets can be read from [Vault](https://www.vaultproject.io/) and used within your template as user variables. the `vault` function is available _only_ @@ -188,14 +188,14 @@ The full list of available environment variables is: and detailed documentation for usage of each of those variables can be found [here](/vault/docs/commands#environment-variables). -## AWS Secrets Manager Variables +## AWS Secrets Manager variables Secrets can be read from [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) and used within your template as user variables. The `aws_secretsmanager` function is available _only_ within the default value of a user variable, allowing you to default a user variable to an AWS Secrets Manager secret. -### Plaintext Secrets +### Plaintext secrets ```json { @@ -209,7 +209,7 @@ In the example above it is assumed that the secret `globalpassword` is not stored as a key pair but as a single non-JSON string value. Which the `aws_secretsmanager` function will return as a raw string. -### Single Key Secrets +### Single key secrets ```json { @@ -223,7 +223,7 @@ In the example above it is assumed that only one key is stored in `sample/app/password` if there are multiple keys stored in it then you need to indicate the specific key you want to fetch as shown below. -### Multiple Key Secrets +### Multiple key secrets ```json { @@ -242,7 +242,7 @@ one of the following methods: - [Container Credentials](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) - [Instance Profile Credentials](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) -## Using array values +## Use array values Some templates call for array values. You can use template variables for these, too. For example, the `amazon-ebs` builder has a configuration parameter called @@ -277,13 +277,13 @@ by a `,`. For example: } ``` -## Setting Variables +## Set variables Now that we covered how to define and use user variables within a template, the next important point is how to actually set these variables. Packer exposes two methods for setting user variables: from the command line or from a file. -### From the Command Line +### CLI To set user variables from the command line, the `-var` flag is used as a parameter to `packer build` (and some other commands). Continuing our example @@ -307,7 +307,7 @@ your variables rather than single-quoting them. For example: `packer build -var "aws_secret_key=foo" template.json` -### From a File +### From file Variables can also be set from an external JSON file. The `-var-file` flag reads a file containing a key/value mapping of variables to values and sets @@ -354,7 +354,7 @@ Results in the following variables: | aws_access_key | foo | | aws_secret_key | baz | -# Sensitive Variables +## Sensitive variables If you use the environment to set a variable that is sensitive, you probably don't want that variable printed to the Packer logs. You can make sure that @@ -380,9 +380,9 @@ instances of "bar" and of whatever the value of "my_secret" is with ``. This allows you to be confident that you are not printing secrets in plaintext to our logs by accident. -# Recipes +## Recipes -## Making a provisioner step conditional on the value of a variable +### Make a provisioner step conditional on the value of a variable There is no specific syntax in Packer templates for making a provisioner step conditional, depending on the value of a variable. However, you may be able to @@ -397,7 +397,7 @@ example, here is how to make a `shell-local` provisioner only run if the } ``` -## Using HOME Variable +### Using HOME Variable In order to use `$HOME` variable, you can create a `home` variable in Packer: @@ -420,4 +420,4 @@ And this will be available to be used in the rest of the template, i.e.: } ] } -``` +``` \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index fc751bdd1..f4b0eafe7 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -667,7 +667,7 @@ "path": "templates/legacy_json_templates" }, { - "title": "Builders", + "title": "builders", "path": "templates/legacy_json_templates/builders" }, { @@ -679,15 +679,15 @@ "path": "templates/legacy_json_templates/engine" }, { - "title": "Post-Processors", + "title": "post-processors", "path": "templates/legacy_json_templates/post-processors" }, { - "title": "Provisioners", + "title": "provisioners", "path": "templates/legacy_json_templates/provisioners" }, { - "title": "User Variables", + "title": "variables", "path": "templates/legacy_json_templates/user-variables" } ]