aherman
/
packer
mirror of https://github.com/hashicorp/packer
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

legacy json template ref

Browse Source
docs/packer-seo-templates-batch1
trujillo-adam 1 year ago
parent 7645ee0ff4
commit ba3c07bf66
10 changed files with 117 additions and 132 deletions
Show Stats Download Patch File Download Diff File

35
website/content/docs/templates/index.mdx vendored
Unescape View File

@ -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.

23
website/content/docs/templates/json_to_hcl.mdx vendored
Unescape View File

@ -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

17
website/content/docs/templates/legacy_json_templates/builders.mdx vendored
Unescape View File

@ -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.

18
website/content/docs/templates/legacy_json_templates/communicator.mdx vendored
Unescape View File

@ -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:

30
website/content/docs/templates/legacy_json_templates/engine.mdx vendored
Unescape View File

@ -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
```
```

23
website/content/docs/templates/legacy_json_templates/index.mdx vendored
Unescape View File

@ -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

21
website/content/docs/templates/legacy_json_templates/post-processors.mdx vendored
Unescape View File

@ -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:

28
website/content/docs/templates/legacy_json_templates/provisioners.mdx vendored
Unescape View File

@ -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
{

46
website/content/docs/templates/legacy_json_templates/user-variables.mdx vendored
Unescape View File

@ -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
`<sensitive>`. 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.:
}
]
}
```
```

8
website/data/docs-nav-data.json
Unescape View File

@ -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"
}
]

Write Preview
Loading…
Cancel
Save