This is a more substantive rewrite than intended
This is more than I planned but I think it makes things a little clearer and perhaps organizes the page more clearly? I'd be happy to take another example for template variables if someone can posit one.
This commit is contained in:
James Turnbull
parent
cae2170375
commit
0a544082ee
|
|
@ -11,73 +11,69 @@ description: |-
|
|||
# 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.
|
||||
where variables and functions can be used to modify the value of a
|
||||
configuration parameter at runtime.
|
||||
|
||||
For example, the `{{timestamp}}` function can be used in any string to generate
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
The complete syntax is covered in the next section, followed by a reference of
|
||||
globally available functions.
|
||||
|
||||
## 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}}`.
|
||||
|
||||
Here is an example from the VMware VMX template that shows template
|
||||
variables in action:
|
||||
|
||||
```liquid
|
||||
.encoding = "UTF-8"
|
||||
displayName = "{{ .Name }}"
|
||||
guestOS = "{{ .GuestOS }}"
|
||||
```
|
||||
|
||||
In this case, the "Name" and "GuestOS" template variables will be
|
||||
replaced, potentially resulting in a VMX template that looks like this:
|
||||
|
||||
```liquid
|
||||
.encoding = "UTF-8"
|
||||
displayName = "packer"
|
||||
guestOS = "otherlinux"
|
||||
```
|
||||
|
||||
## Global Functions
|
||||
|
||||
While some configuration settings have template variables specific to only that
|
||||
configuration, a set of functions are available globally for use in *any string*
|
||||
in Packer templates. These are listed below for reference.
|
||||
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.
|
||||
- `isotime [FORMAT]` - UTC time, which can be
|
||||
[formatted](https://golang.org/pkg/time/#example_Time_Format). See more
|
||||
examples below.
|
||||
examples below in [the `isotime` format reference](/docs/templates/engine.html#isotime-function-format-reference).
|
||||
- `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.
|
||||
- `user` - Specifies a user variable.
|
||||
|
||||
### isotime Format
|
||||
#### 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}}`.
|
||||
|
||||
## 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.html) builder template variables are available to customize the [`execute_command`](/docs/provisioners/shell.html#execute_command) parameter used to determine how Packer will run the shell command.
|
||||
|
||||
```liquid
|
||||
{
|
||||
"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/user-variables.html) documentation for more information on user variables.
|
||||
|
||||
# isotime Function Format Reference
|
||||
|
||||
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:
|
||||
|
|
@ -177,7 +173,7 @@ Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
|
|||
|
||||
Note that "-0700" is always formatted into "+0000" because `isotime` is always UTC time.
|
||||
|
||||
Here are some example formated time, using the above format options:
|
||||
Here are some example formatted time, using the above format options:
|
||||
|
||||
```liquid
|
||||
isotime = June 7, 7:22:43pm 2014
|
||||
|
|
@ -208,11 +204,3 @@ Please note that double quote characters need escaping inside of templates (in t
|
|||
```
|
||||
|
||||
-> **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}}`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue