packer-cn/website/source/docs/templates/user-variables.html.md

layout	sidebar_current	page_title	description
docs	docs-templates-user-variables	User Variables - Templates	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 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:

{
  "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 {{user `variable`}}. 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:

{
  "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.

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

{
  "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:

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

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

{
  "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:

{
  "variables": {
    "home": "{{env `HOME`}}"
  }
}

And this will be available to be used in the rest of the template, i.e.:

{
  "builders": [
    {
      "type":"google",
      "account_file": "{{ user `home` }}/.secrets/gcp-{{ user `env` }}.json"
    }
  ]
}