github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/templates/user-variables.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "User Variables in Templates"
     4  description: |-
     5    User variables allow your templates to be further configured with variables from the command-line, environmental 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.
     6  ---
     7  
     8  # User Variables
     9  
    10  User variables allow your templates to be further configured with variables
    11  from the command-line, environmental variables, or files. This lets you
    12  parameterize your templates so that you can keep secret tokens,
    13  environment-specific data, and other types of information out of your
    14  templates. This maximizes the portability and shareability of the template.
    15  
    16  Using user variables expects you know how
    17  [configuration templates](/docs/templates/configuration-templates.html) work.
    18  If you don't know how configuration templates work yet, please read that
    19  page first.
    20  
    21  ## Usage
    22  
    23  User variables must first be defined in a `variables` section within your
    24  template. Even if you want a variable to default to an empty string, it
    25  must be defined. This explicitness makes it easy for newcomers to your
    26  template to understand what can be modified using variables in your template.
    27  
    28  The `variables` section is a simple key/value mapping of the variable
    29  name to a default value. A default value can be the empty string. An
    30  example is shown below:
    31  
    32  ```javascript
    33  {
    34    "variables": {
    35      "aws_access_key": "",
    36      "aws_secret_key": ""
    37    },
    38  
    39    "builders": [{
    40      "type": "amazon-ebs",
    41      "access_key": "{{user `aws_access_key`}}",
    42      "secret_key": "{{user `aws_secret_key`}}",
    43      // ...
    44    }]
    45  }
    46  ```
    47  
    48  In the above example, the template defines two variables: `aws_access_key` and
    49  `aws_secret_key`. They default to empty values.
    50  Later, the variables are used within the builder we defined in order to
    51  configure the actual keys for the Amazon builder.
    52  
    53  If the default value is `null`, then the user variable will be _required_.
    54  This means that the user must specify a value for this variable or template
    55  validation will fail.
    56  
    57  Using the variables is extremely easy. Variables are used by calling
    58  the user function in the form of <code>{{user &#96;variable&#96;}}</code>.
    59  This function can be used in _any value_ within the template, in
    60  builders, provisioners, _anything_. The user variable is available globally
    61  within the template.
    62  
    63  ## Environmental Variables
    64  
    65  Environmental variables can be used within your template using user
    66  variables. The `env` function is available _only_ within the default value
    67  of a user variable, allowing you to default a user variable to an
    68  environmental variable. An example is shown below:
    69  
    70  ```javascript
    71  {
    72    "variables": {
    73      "my_secret": "{{env `MY_SECRET`}}",
    74    },
    75  
    76    // ...
    77  }
    78  ```
    79  
    80  This will default "my\_secret" to be the value of the "MY\_SECRET"
    81  environmental variable (or the empty string if it does not exist).
    82  
    83  -> **Why can't I use environmental variables elsewhere?**
    84  User variables are the single source of configurable input to a template.
    85  We felt that having environmental variables used _anywhere_ in a
    86  template would confuse the user about the possible inputs to a template.
    87  By allowing environmental variables only within default values for user
    88  variables, user variables remain as the single source of input to a template
    89  that a user can easily discover using `packer inspect`.
    90  
    91  ## Setting Variables
    92  
    93  Now that we covered how to define and use variables within a template,
    94  the next important point is how to actually set these variables. Packer
    95  exposes two methods for setting variables: from the command line or
    96  from a file.
    97  
    98  ### From the Command Line
    99  
   100  To set variables from the command line, the `-var` flag is used as
   101  a parameter to `packer build` (and some other commands). Continuing our example
   102  above, we could build our template using the command below. The command
   103  is split across multiple lines for readability, but can of course be a single
   104  line.
   105  
   106  ```text
   107  $ packer build \
   108      -var 'aws_access_key=foo' \
   109      -var 'aws_secret_key=bar' \
   110      template.json
   111  ```
   112  
   113  As you can see, the `-var` flag can be specified multiple times in order
   114  to set multiple variables. Also, variables set later on the command-line
   115  override earlier set variables if it has already been set.
   116  
   117  Finally, variables set from the command-line override all other methods
   118  of setting variables. So if you specify a variable in a file (the next
   119  method shown), you can override it using the command-line.
   120  
   121  ### From a File
   122  
   123  Variables can also be set from an external JSON file. The `-var-file`
   124  flag reads a file containing a basic key/value mapping of variables to
   125  values and sets those variables. The JSON file is simple:
   126  
   127  ```javascript
   128  {
   129    "aws_access_key": "foo",
   130    "aws_secret_key": "bar"
   131  }
   132  ```
   133  
   134  It is a single JSON object where the keys are variables and the values are
   135  the variable values. Assuming this file is in `variables.json`, we can
   136  build our template using the following command:
   137  
   138  ```text
   139  $ packer build -var-file=variables.json template.json
   140  ```
   141  
   142  The `-var-file` flag can be specified multiple times and variables from
   143  multiple files will be read and applied. As you'd expect, variables read
   144  from files specified later override a variable set earlier if it has
   145  already been set.
   146  
   147  And as mentioned above, no matter where a `-var-file` is specified, a
   148  `-var` flag on the command line will always override any variables from
   149  a file.