github.com/jerryclinesmith/packer@v0.3.7/website/source/docs/templates/user-variables.html.markdown (about)

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