github.com/kimor79/packer@v0.8.7-0.20151221212622-d507b18eb4cf/website/source/docs/templates/user-variables.html.markdown (about)

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