github.com/trawler/terraform@v0.10.8-0.20171106022149-4b1c7a1d9b48/website/docs/configuration/variables.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Configuring Variables" 4 sidebar_current: "docs-config-variables" 5 description: |- 6 Variables define the parameterization of Terraform configurations. Variables can be overridden via the CLI. Variable usage is covered in more detail in the getting started guide. This page covers configuration syntax for variables. 7 --- 8 9 # Variable Configuration 10 11 Variables define the parameterization of Terraform configurations. 12 Variables can be overridden via the CLI. Variable usage is 13 covered in more detail in the 14 [getting started guide](/intro/getting-started/variables.html). 15 This page covers configuration syntax for variables. 16 17 This page assumes you're familiar with the 18 [configuration syntax](/docs/configuration/syntax.html) 19 already. 20 21 ## Example 22 23 A variable configuration looks like the following: 24 25 ```hcl 26 variable "key" { 27 type = "string" 28 } 29 30 variable "images" { 31 type = "map" 32 33 default = { 34 us-east-1 = "image-1234" 35 us-west-2 = "image-4567" 36 } 37 } 38 39 variable "zones" { 40 default = ["us-east-1a", "us-east-1b"] 41 } 42 ``` 43 44 ## Description 45 46 The `variable` block configures a single input variable for 47 a Terraform configuration. Multiple variables blocks can be used to 48 add multiple variables. 49 50 The `name` given to the variable block is the name used to 51 set the variable via the CLI as well as reference the variable 52 throughout the Terraform configuration. 53 54 Within the block (the `{ }`) is configuration for the variable. 55 These are the parameters that can be set: 56 57 - `type` (optional) - If set this defines the type of the variable. Valid values 58 are `string`, `list`, and `map`. If this field is omitted, the variable type 59 will be inferred based on the `default`. If no `default` is provided, the type 60 is assumed to be `string`. 61 62 - `default` (optional) - This sets a default value for the variable. If no 63 default is provided, the variable is considered required and Terraform will 64 error if it is not set. The default value can be any of the data types 65 Terraform supports. This is covered in more detail below. 66 67 - `description` (optional) - A human-friendly description for the variable. This 68 is primarily for documentation for users using your Terraform configuration. A 69 future version of Terraform will expose these descriptions as part of some 70 Terraform CLI command. 71 72 The name of a variable can be any valid identifier. However, due to the 73 interpretation of [module configuration blocks](/docs/configuration/modules.html), 74 the names `source`, `version` and `providers` are reserved for Terraform's own 75 use and are thus not recommended for any module intended to be used as a 76 child module. 77 78 -> **Note**: Default values can be strings, lists, or maps. If a default is 79 specified, it must match the declared type of the variable. 80 81 ### Strings 82 83 String values are simple and represent a basic key to value 84 mapping where the key is the variable name. An example is: 85 86 ```hcl 87 variable "key" { 88 type = "string" 89 default = "value" 90 } 91 ``` 92 93 A multi-line string value can be provided using heredoc syntax. 94 95 ```hcl 96 variable "long_key" { 97 type = "string" 98 default = <<EOF 99 This is a long key. 100 Running over several lines. 101 EOF 102 } 103 ``` 104 105 ### Maps 106 107 A map allows a key to contain a lookup table. This is useful 108 for some values that change depending on some external pivot. 109 A common use case for this is mapping cloud images to regions. 110 An example: 111 112 ```hcl 113 variable "images" { 114 type = "map" 115 default = { 116 us-east-1 = "image-1234" 117 us-west-2 = "image-4567" 118 } 119 } 120 ``` 121 122 ### Lists 123 124 A list can also be useful to store certain variables. For example: 125 126 ```hcl 127 variable "users" { 128 type = "list" 129 default = ["admin", "ubuntu"] 130 } 131 ``` 132 133 The usage of maps, lists, strings, etc. is documented fully in the 134 [interpolation syntax](/docs/configuration/interpolation.html) 135 page. 136 137 ## Syntax 138 139 The full syntax is: 140 141 ```text 142 variable NAME { 143 [type = TYPE] 144 [default = DEFAULT] 145 [description = DESCRIPTION] 146 } 147 ``` 148 149 where `DEFAULT` is: 150 151 ```text 152 VALUE 153 154 [ 155 VALUE, 156 ... 157 ] 158 159 { 160 KEY = VALUE 161 ... 162 } 163 ``` 164 165 ### Booleans 166 167 Although it appears Terraform supports boolean types, they are instead 168 silently converted to string types. The implications of this are subtle and 169 should be completely understood if you plan on using boolean values. 170 171 It is instead recommended you avoid using boolean values for now and use 172 explicit strings. A future version of Terraform will properly support booleans 173 and using the current behavior could result in backwards-incompatibilities in 174 the future. 175 176 For a configuration such as the following: 177 178 ```hcl 179 variable "active" { 180 default = false 181 } 182 ``` 183 184 The false is converted to a string `"0"` when running Terraform. 185 186 Then, depending on where you specify overrides, the behavior can differ: 187 188 - Variables with boolean values in a `tfvars` file will likewise be converted to 189 "0" and "1" values. 190 191 - Variables specified via the `-var` command line flag will be literal strings 192 "true" and "false", so care should be taken to explicitly use "0" or "1". 193 194 - Variables specified with the `TF_VAR_` environment variables will be literal 195 string values, just like `-var`. 196 197 A future version of Terraform will fully support first-class boolean 198 types which will make the behavior of booleans consistent as you would 199 expect. This may break some of the above behavior. 200 201 When passing boolean-like variables as parameters to resource configurations 202 that expect boolean values, they are converted consistently: 203 204 - "1", "true", "t" all become `true` 205 - "0", "false", "f" all become `false` 206 207 The behavior of conversion above will likely not change in future 208 Terraform versions. Therefore, simply using string values rather than 209 booleans for variables is recommended. 210 211 ## Environment Variables 212 213 Environment variables can be used to set the value of a variable. 214 The key of the environment variable must be `TF_VAR_name` and the value 215 is the value of the variable. 216 217 For example, given the configuration below: 218 219 ```hcl 220 variable "image" {} 221 ``` 222 223 The variable can be set via an environment variable: 224 225 ```shell 226 $ TF_VAR_image=foo terraform apply 227 ``` 228 229 Maps and lists can be specified using environment variables as well using 230 [HCL](/docs/configuration/syntax.html#HCL) syntax in the value. 231 232 For a list variable like so: 233 234 ```hcl 235 variable "somelist" { 236 type = "list" 237 } 238 ``` 239 240 The variable could be set like so: 241 242 ```shell 243 $ TF_VAR_somelist='["ami-abc123", "ami-bcd234"]' terraform plan 244 ``` 245 246 Similarly, for a map declared like: 247 248 ```hcl 249 variable "somemap" { 250 type = "map" 251 } 252 ``` 253 254 The value can be set like this: 255 256 ```shell 257 $ TF_VAR_somemap='{foo = "bar", baz = "qux"}' terraform plan 258 ``` 259 260 ## Variable Files 261 262 Variables can be collected in files and passed all at once using the 263 `-var-file=foo.tfvars` flag. 264 265 For all files which match `terraform.tfvars` or `*.auto.tfvars` present in the 266 current directory, Terraform automatically loads them to populate variables. If 267 the file is located somewhere else, you can pass the path to the file using the 268 `-var-file` flag. 269 270 Variables files use HCL or JSON to define variable values. Strings, lists or 271 maps may be set in the same manner as the default value in a `variable` block 272 in Terraform configuration. For example: 273 274 ```hcl 275 foo = "bar" 276 xyz = "abc" 277 278 somelist = [ 279 "one", 280 "two", 281 ] 282 283 somemap = { 284 foo = "bar" 285 bax = "qux" 286 } 287 ``` 288 289 The `-var-file` flag can be used multiple times per command invocation: 290 291 ```shell 292 $ terraform apply -var-file=foo.tfvars -var-file=bar.tfvars 293 ``` 294 295 -> **Note**: Variable files are evaluated in the order in which they are 296 specified on the command line. If a variable is defined in more than one 297 variable file, the last value specified is effective. 298 299 ### Variable Merging 300 301 When variables are conflicting, map values are merged and all other values are 302 overridden. Map values are always merged. 303 304 For example, if you set a variable twice on the command line: 305 306 ```shell 307 $ terraform apply -var foo=bar -var foo=baz 308 ``` 309 310 Then the value of `foo` will be `baz` since it was the last value seen. 311 312 However, for maps, the values are merged: 313 314 ```shell 315 $ terraform apply -var 'foo={quux="bar"}' -var 'foo={bar="baz"}' 316 ``` 317 318 The resulting value of `foo` will be: 319 320 ```shell 321 { 322 quux = "bar" 323 bar = "baz" 324 } 325 ``` 326 327 There is no way currently to unset map values in Terraform. Whenever a map 328 is modified either via variable input or being passed into a module, the 329 values are always merged. 330 331 ### Variable Precedence 332 333 Both these files have the variable `baz` defined: 334 335 _foo.tfvars_ 336 337 ```hcl 338 baz = "foo" 339 ``` 340 341 _bar.tfvars_ 342 343 ```hcl 344 baz = "bar" 345 ``` 346 347 When they are passed in the following order: 348 349 ```shell 350 $ terraform apply -var-file=foo.tfvars -var-file=bar.tfvars 351 ``` 352 353 The result will be that `baz` will contain the value `bar` because `bar.tfvars` 354 has the last definition loaded. 355 356 Definitions passed using the `-var-file` flag will always be evaluated after 357 those in the working directory.