210 lines
6.7 KiB
Markdown
210 lines
6.7 KiB
Markdown
---
|
|
layout: docs
|
|
sidebar_current: docs-templates-user-variables
|
|
page_title: User Variables - Templates
|
|
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.
|
|
---
|
|
|
|
# Template User Variables
|
|
|
|
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 of the template.
|
|
|
|
Using user variables expects you to know how [configuration
|
|
templates](/docs/templates/engine.html) work. If you don't know
|
|
how configuration templates work yet, please read that page first.
|
|
|
|
## Usage
|
|
|
|
User variables must first be defined in a `variables` section within
|
|
your template. Even if you want a user variable to default to an empty
|
|
string, it must be defined. This explicitness helps reduce the time it
|
|
takes for newcomers to understand what can be modified using variables
|
|
in your template.
|
|
|
|
The `variables` section is a key/value mapping of the user variable name
|
|
to a default value. A default value can be the empty string. An example
|
|
is shown below:
|
|
|
|
```json
|
|
{
|
|
"variables": {
|
|
"aws_access_key": "",
|
|
"aws_secret_key": ""
|
|
},
|
|
|
|
"builders": [{
|
|
"type": "amazon-ebs",
|
|
"access_key": "{{user `aws_access_key`}}",
|
|
"secret_key": "{{user `aws_secret_key`}}",
|
|
// ...
|
|
}]
|
|
}
|
|
```
|
|
|
|
In the above example, the template defines two user variables:
|
|
`aws_access_key` and `aws_secret_key`. They default to empty values.
|
|
Later, the variables are used within the builder we defined in order to
|
|
configure the actual keys for the Amazon builder.
|
|
|
|
If the default value is `null`, then the user variable will be
|
|
*required*. This means that the user must specify a value for this
|
|
variable or template validation will fail.
|
|
|
|
User variables are used by calling the `{{user}}` function in the form of
|
|
<code>{{user \`variable\`}}</code>. This function can be used in *any value*
|
|
but `type` 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 can be used within your template using user variables.
|
|
The `env` function is available *only* within the default value of a user
|
|
variable, allowing you to default a user variable to an environment variable.
|
|
An example is shown below:
|
|
|
|
```json
|
|
{
|
|
"variables": {
|
|
"my_secret": "{{env `MY_SECRET`}}",
|
|
}
|
|
}
|
|
```
|
|
|
|
This will default "my\_secret" to be the value of the "MY\_SECRET" environment
|
|
variable (or an empty string if it does not exist).
|
|
|
|
-> **Why can't I use environment variables elsewhere?** User variables are
|
|
the single source of configurable input to a template. We felt that having
|
|
environment variables used *anywhere* in a template would confuse the user
|
|
about the possible inputs to a template. By allowing environment variables
|
|
only within default values for user variables, user variables remain as the
|
|
single source of input to a template that a user can easily discover using
|
|
`packer inspect`.
|
|
|
|
-> **Why can't I use `~` for home variable?** `~` is an special variable
|
|
that is evaluated by shell during a variable expansion. As Packer doesn't run
|
|
inside a shell, it won't expand `~`.
|
|
|
|
## Setting 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
|
|
|
|
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 above, we could build our template using the command below. The
|
|
command is split across multiple lines for readability, but can of
|
|
course be a single line.
|
|
|
|
```text
|
|
$ packer build \
|
|
-var 'aws_access_key=foo' \
|
|
-var 'aws_secret_key=bar' \
|
|
template.json
|
|
```
|
|
|
|
As you can see, the `-var` flag can be specified multiple times in order to set
|
|
multiple variables. Also, variables set later on the command-line override
|
|
any earlier set variable of the same name.
|
|
|
|
### From a 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
|
|
those variables. An example JSON file may look like this:
|
|
|
|
```json
|
|
{
|
|
"aws_access_key": "foo",
|
|
"aws_secret_key": "bar"
|
|
}
|
|
```
|
|
|
|
It is a single JSON object where the keys are variables and the values are the
|
|
variable values. Assuming this file is in `variables.json`, we can build our
|
|
template using the following command:
|
|
|
|
```text
|
|
$ packer build -var-file=variables.json template.json
|
|
```
|
|
|
|
The `-var-file` flag can be specified multiple times and variables from multiple
|
|
files will be read and applied. As you'd expect, variables read from files
|
|
specified later override a variable set earlier.
|
|
|
|
Combining the `-var` and `-var-file` flags together also works how you'd
|
|
expect. Variables set later in the command override variables set
|
|
earlier. So, for example, in the following command with the above
|
|
`variables.json` file:
|
|
|
|
```text
|
|
$ packer build \
|
|
-var 'aws_access_key=bar' \
|
|
-var-file=variables.json \
|
|
-var 'aws_secret_key=baz' \
|
|
template.json
|
|
```
|
|
|
|
Results in the following variables:
|
|
|
|
| Variable | Value |
|
|
| -------- | --------- |
|
|
| aws_access_key | foo |
|
|
| aws_secret_key | baz |
|
|
|
|
# Recipes
|
|
|
|
## Making 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 do this by referencing the variable within a command that
|
|
you execute. For example, here is how to make a `shell-local`
|
|
provisioner only run if the `do_nexpose_scan` variable is non-empty.
|
|
|
|
```json
|
|
{
|
|
"type": "shell-local",
|
|
"command": "if [ ! -z \"{{user `do_nexpose_scan`}}\" ]; then python -u trigger_nexpose_scan.py; fi"
|
|
}
|
|
```
|
|
|
|
## Using HOME Variable
|
|
|
|
In order to use `$HOME` variable, you can create a `home` variable in Packer:
|
|
|
|
```json
|
|
{
|
|
"variables": {
|
|
"home": "{{env `HOME`}}"
|
|
}
|
|
}
|
|
```
|
|
|
|
And this will be available to be used in the rest of the template, i.e.:
|
|
|
|
```json
|
|
{
|
|
"builders": [
|
|
{
|
|
"type":"google",
|
|
"account_file": "{{ user `home` }}/.secrets/gcp-{{ user `env` }}.json"
|
|
}
|
|
]
|
|
}
|
|
```
|