packer-cn/website/source/docs/templates/engine.html.md

219 lines
5.8 KiB
Markdown
Raw Normal View History

2013-06-10 18:08:14 -04:00
---
2015-07-22 22:31:00 -04:00
layout: docs
sidebar_current: docs-templates-engine
page_title: Template Engine - Templates
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.
---
2013-06-10 18:08:14 -04:00
# Template Engine
2013-06-10 18:08:14 -04:00
2015-07-22 22:31:00 -04:00
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.
2013-08-08 19:56:09 -04:00
2015-07-22 22:31:00 -04:00
For example, the `{{timestamp}}` function can be used in any string to generate
the current timestamp. This is useful for configurations that require unique
2017-05-15 14:52:25 -04:00
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.
2013-08-08 19:56:09 -04:00
In addition to globally available functions like `{{timestamp}}`, some
configurations have special template variables that are available only
for that configuration. Template variables are recognizable because
they're prefixed by a period, such as `{{.Name}}`.
-> **Note:** In addition to template variables, you can specify your own user variables. See the [user variable](/docs/templates/user-variables.html) documentation for more information on user variables.
2013-08-08 19:56:09 -04:00
2015-07-22 22:31:00 -04:00
The complete syntax is covered in the next section, followed by a reference of
globally available functions.
2013-06-10 18:08:14 -04:00
## Syntax
The syntax of templates uses the following conventions:
* Anything template related happens within double-braces: `{{ }}`.
* Template variables are prefixed with a period and capitalized, such as
`{{.Variable}}`.
* Functions are directly within the braces, such as `{{timestamp}}`.
2013-08-08 19:56:09 -04:00
Here is an example from the VMware VMX template that shows template
variables in action:
2013-06-10 18:08:14 -04:00
```liquid
2013-06-10 18:08:14 -04:00
.encoding = "UTF-8"
displayName = "{{ .Name }}"
guestOS = "{{ .GuestOS }}"
```
2013-06-10 18:08:14 -04:00
In this case, the "Name" and "GuestOS" template variables will be
replaced, potentially resulting in a VMX template that looks like this:
2013-06-10 18:08:14 -04:00
```liquid
2013-06-10 18:08:14 -04:00
.encoding = "UTF-8"
displayName = "packer"
guestOS = "otherlinux"
```
2013-08-08 19:56:09 -04:00
## Global Functions
While some configuration settings have template variables specific to only that
2015-07-22 22:31:00 -04:00
configuration, a set of functions are available globally for use in *any string*
2013-08-08 19:56:09 -04:00
in Packer templates. These are listed below for reference.
- `build_name` - The name of the build being run.
- `build_type` - The type of the builder being used currently.
- `isotime [FORMAT]` - UTC time, which can be
2016-01-14 15:31:19 -05:00
[formatted](https://golang.org/pkg/time/#example_Time_Format). See more
2015-07-22 23:25:58 -04:00
examples below.
- `lower` - Lowercases the string.
- `pwd` - The working directory while executing Packer.
- `template_dir` - The directory to the template for the build.
- `timestamp` - The current Unix timestamp in UTC.
- `uuid` - Returns a random UUID.
- `upper` - Uppercases the string.
- `user` - Specify a user variable.
### isotime Format
2015-07-22 22:31:00 -04:00
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>
2015-07-22 22:31:00 -04:00
*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.
2015-07-22 22:31:00 -04:00
Here are some example formated time, using the above format options:
```liquid
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
```
Please note that double quote characters need escaping inside of templates (in this case, on the `ami_name` value):
```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 {{isotime \"2006-01-02\"}}"
}
]
}
```
-> **Note:** See the [Amazon builder](/docs/builders/amazon.html) documentation for more information on how to correctly configure the Amazon builder in this example.
## Amazon Specific Functions
Specific to Amazon builders:
- `clean_ami_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_ami_name}}`.