384 lines
16 KiB
Plaintext
384 lines
16 KiB
Plaintext
---
|
|
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
|
|
---
|
|
|
|
`@include 'from-1.5/legacy-json-warning.mdx'`
|
|
|
|
# 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.
|
|
|
|
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](/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](/docs/builders/amazon/chroot#build-shared-information-variables),
|
|
[EBS Volume](/docs/builders/amazon/ebsvolume#build-shared-information-variables),
|
|
[EBS](/docs/builders/amazon/ebs#build-shared-information-variables),
|
|
[EBS Surrogate](/docs/builders/amazon/ebssurrogate#build-shared-information-variables),
|
|
[Instance](/docs/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://golang.org/pkg/time/#example_Time_Format). See more
|
|
examples below in [the `isotime` format
|
|
reference](/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`](/docs/builders/vmware-iso) builder template variables
|
|
are available to customize the
|
|
[`execute_command`](/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](/docs/templates/legacy_json_templates/user-variables)
|
|
documentation for more information on user variables.
|
|
|
|
# isotime Function Format Reference
|
|
|
|
The isotime template engine uses golang to generate timestamps. If you're
|
|
unfamiliar with golang, 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 golang time formatting function can be found
|
|
[here](https://golang.org/pkg/time/#example_Time_Format)
|
|
|
|
However, the formatting basics are worth describing here. From the [golang docs](https://golang.org/pkg/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 11:40:16" |
|
|
| ``"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:
|
|
|
|
<table class="table table-bordered table-condensed">
|
|
<thead>
|
|
<tr>
|
|
<th></th>
|
|
<th align="center">Day of Week</th>
|
|
<th align="center">Month</th>
|
|
<th align="center">Date</th>
|
|
<th align="center">Hour</th>
|
|
<th align="center">Minute</th>
|
|
<th align="center">Second</th>
|
|
<th align="center">Year</th>
|
|
<th align="center">Timezone</th>
|
|
</tr>
|
|
</thead>
|
|
<tr>
|
|
<th>Numeric</th>
|
|
<td align="center">-</td>
|
|
<td align="center">01</td>
|
|
<td align="center">02</td>
|
|
<td align="center">03 (15)</td>
|
|
<td align="center">04</td>
|
|
<td align="center">05</td>
|
|
<td align="center">06</td>
|
|
<td align="center">-0700</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Textual</th>
|
|
<td align="center">Monday (Mon)</td>
|
|
<td align="center">January (Jan)</td>
|
|
<td align="center">-</td>
|
|
<td align="center">-</td>
|
|
<td align="center">-</td>
|
|
<td align="center">-</td>
|
|
<td align="center">-</td>
|
|
<td align="center">MST</td>
|
|
</tr>
|
|
</table>
|
|
|
|
_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 indended 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
|
|
```
|