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 `variable`}}</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.