github.com/loicalbertin/terraform@v0.6.15-0.20170626182346-8e2583055467/website/docs/configuration/interpolation.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Interpolation Syntax" 4 sidebar_current: "docs-config-interpolation" 5 description: |- 6 Embedded within strings in Terraform, whether you're using the Terraform syntax or JSON syntax, you can interpolate other values into strings. These interpolations are wrapped in `${}`, such as `${var.foo}`. 7 --- 8 9 # Interpolation Syntax 10 11 Embedded within strings in Terraform, whether you're using the 12 Terraform syntax or JSON syntax, you can interpolate other values. These 13 interpolations are wrapped in `${}`, such as `${var.foo}`. 14 15 The interpolation syntax is powerful and allows you to reference 16 variables, attributes of resources, call functions, etc. 17 18 You can perform [simple math](#math) in interpolations, allowing 19 you to write expressions such as `${count.index + 1}`. And you can 20 also use [conditionals](#conditionals) to determine a value based 21 on some logic. 22 23 You can escape interpolation with double dollar signs: `$${foo}` 24 will be rendered as a literal `${foo}`. 25 26 ## Available Variables 27 28 There are a variety of available variable references you can use. 29 30 #### User string variables 31 32 Use the `var.` prefix followed by the variable name. For example, 33 `${var.foo}` will interpolate the `foo` variable value. 34 35 #### User map variables 36 37 The syntax is `var.MAP["KEY"]`. For example, `${var.amis["us-east-1"]}` 38 would get the value of the `us-east-1` key within the `amis` map 39 variable. 40 41 #### User list variables 42 43 The syntax is `"${var.LIST}"`. For example, `"${var.subnets}"` 44 would get the value of the `subnets` list, as a list. You can also 45 return list elements by index: `${var.subnets[idx]}`. 46 47 #### Attributes of your own resource 48 49 The syntax is `self.ATTRIBUTE`. For example `${self.private_ip_address}` 50 will interpolate that resource's private IP address. 51 52 -> **Note**: The `self.ATTRIBUTE` syntax is only allowed and valid within 53 provisioners. 54 55 #### Attributes of other resources 56 57 The syntax is `TYPE.NAME.ATTRIBUTE`. For example, 58 `${aws_instance.web.id}` will interpolate the ID attribute from the 59 `aws_instance` resource named `web`. If the resource has a `count` 60 attribute set, you can access individual attributes with a zero-based 61 index, such as `${aws_instance.web.0.id}`. You can also use the splat 62 syntax to get a list of all the attributes: `${aws_instance.web.*.id}`. 63 64 #### Attributes of a data source 65 66 The syntax is `data.TYPE.NAME.ATTRIBUTE`. For example. `${data.aws_ami.ubuntu.id}` will interpolate the `id` attribute from the `aws_ami` [data source](/docs/configuration/data-sources.html) named `ubuntu`. If the data source has a `count` 67 attribute set, you can access individual attributes with a zero-based 68 index, such as `${data.aws_subnet.example.0.cidr_block}`. You can also use the splat 69 syntax to get a list of all the attributes: `${data.aws_subnet.example.*.cidr_block}`. 70 71 #### Outputs from a module 72 73 The syntax is `MODULE.NAME.OUTPUT`. For example `${module.foo.bar}` will 74 interpolate the `bar` output from the `foo` 75 [module](/docs/modules/index.html). 76 77 #### Count information 78 79 The syntax is `count.FIELD`. For example, `${count.index}` will 80 interpolate the current index in a multi-count resource. For more 81 information on `count`, see the [resource configuration 82 page](/docs/configuration/resources.html). 83 84 #### Path information 85 86 The syntax is `path.TYPE`. TYPE can be `cwd`, `module`, or `root`. 87 `cwd` will interpolate the current working directory. `module` will 88 interpolate the path to the current module. `root` will interpolate the 89 path of the root module. In general, you probably want the 90 `path.module` variable. 91 92 #### Terraform meta information 93 94 The syntax is `terraform.FIELD`. This variable type contains metadata about 95 the currently executing Terraform run. FIELD can currently only be `env` to 96 reference the currently active [state environment](/docs/state/environments.html). 97 98 ## Conditionals 99 100 Interpolations may contain conditionals to branch on the final value. 101 102 ```hcl 103 resource "aws_instance" "web" { 104 subnet = "${var.env == "production" ? var.prod_subnet : var.dev_subnet}" 105 } 106 ``` 107 108 The conditional syntax is the well-known ternary operation: 109 110 ```text 111 CONDITION ? TRUEVAL : FALSEVAL 112 ``` 113 114 The condition can be any valid interpolation syntax, such as variable 115 access, a function call, or even another conditional. The true and false 116 value can also be any valid interpolation syntax. The returned types by 117 the true and false side must be the same. 118 119 The support operators are: 120 121 * Equality: `==` and `!=` 122 * Numerical comparison: `>`, `<`, `>=`, `<=` 123 * Boolean logic: `&&`, `||`, unary `!` 124 125 A common use case for conditionals is to enable/disable a resource by 126 conditionally setting the count: 127 128 ```hcl 129 resource "aws_instance" "vpn" { 130 count = "${var.something ? 1 : 0}" 131 } 132 ``` 133 134 In the example above, the "vpn" resource will only be included if 135 "var.something" evaluates to true. Otherwise, the VPN resource will 136 not be created at all. 137 138 ## Built-in Functions 139 140 Terraform ships with built-in functions. Functions are called with the 141 syntax `name(arg, arg2, ...)`. For example, to read a file: 142 `${file("path.txt")}`. 143 144 ### Supported built-in functions 145 146 The supported built-in functions are: 147 148 * `basename(path)` - Returns the last element of a path. 149 150 * `base64decode(string)` - Given a base64-encoded string, decodes it and 151 returns the original string. 152 153 * `base64encode(string)` - Returns a base64-encoded representation of the 154 given string. 155 156 * `base64sha256(string)` - Returns a base64-encoded representation of raw 157 SHA-256 sum of the given string. 158 **This is not equivalent** of `base64encode(sha256(string))` 159 since `sha256()` returns hexadecimal representation. 160 161 * `base64sha512(string)` - Returns a base64-encoded representation of raw 162 SHA-512 sum of the given string. 163 **This is not equivalent** of `base64encode(sha512(string))` 164 since `sha512()` returns hexadecimal representation. 165 166 * `bcrypt(password, cost)` - Returns the Blowfish encrypted hash of the string 167 at the given cost. A default `cost` of 10 will be used if not provided. 168 169 * `ceil(float)` - Returns the least integer value greater than or equal 170 to the argument. 171 172 * `chomp(string)` - Removes trailing newlines from the given string. 173 174 * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation 175 and creates an IP address with the given host number. If given host 176 number is negative, the count starts from the end of the range. 177 For example, `cidrhost("10.0.0.0/8", 2)` returns `10.0.0.2` and 178 `cidrhost("10.0.0.0/8", -2)` returns `10.255.255.254`. 179 180 * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation 181 and returns the address-formatted subnet mask format that some 182 systems expect for IPv4 interfaces. For example, 183 `cidrnetmask("10.0.0.0/8")` returns `255.0.0.0`. Not applicable 184 to IPv6 networks since CIDR notation is the only valid notation for 185 IPv6. 186 187 * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in 188 CIDR notation (like `10.0.0.0/8`) and extends its prefix to include an 189 additional subnet number. For example, 190 `cidrsubnet("10.0.0.0/8", 8, 2)` returns `10.2.0.0/16`; 191 `cidrsubnet("2607:f298:6051:516c::/64", 8, 2)` returns 192 `2607:f298:6051:516c:200::/72`. 193 194 * `coalesce(string1, string2, ...)` - Returns the first non-empty value from 195 the given arguments. At least two arguments must be provided. 196 197 * `coalescelist(list1, list2, ...)` - Returns the first non-empty list from 198 the given arguments. At least two arguments must be provided. 199 200 * `compact(list)` - Removes empty string elements from a list. This can be 201 useful in some cases, for example when passing joined lists as module 202 variables or when parsing module outputs. 203 Example: `compact(module.my_asg.load_balancer_names)` 204 205 * `concat(list1, list2, ...)` - Combines two or more lists into a single list. 206 Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)` 207 208 * `contains(list, element)` - Returns *true* if a list contains the given element 209 and returns *false* otherwise. Examples: `element(var.list_of_strings, "an_element")` 210 211 * `dirname(path)` - Returns all but the last element of path, typically the path's directory. 212 213 * `distinct(list)` - Removes duplicate items from a list. Keeps the first 214 occurrence of each element, and removes subsequent occurrences. This 215 function is only valid for flat lists. Example: `distinct(var.usernames)` 216 217 * `element(list, index)` - Returns a single element from a list 218 at the given index. If the index is greater than the number of 219 elements, this function will wrap using a standard mod algorithm. 220 This function only works on flat lists. Examples: 221 * `element(aws_subnet.foo.*.id, count.index)` 222 * `element(var.list_of_strings, 2)` 223 224 * `file(path)` - Reads the contents of a file into the string. Variables 225 in this file are _not_ interpolated. The contents of the file are 226 read as-is. The `path` is interpreted relative to the working directory. 227 [Path variables](#path-variables) can be used to reference paths relative 228 to other base locations. For example, when using `file()` from inside a 229 module, you generally want to make the path relative to the module base, 230 like this: `file("${path.module}/file")`. 231 232 * `floor(float)` - Returns the greatest integer value less than or equal to 233 the argument. 234 235 * `format(format, args, ...)` - Formats a string according to the given 236 format. The syntax for the format is standard `sprintf` syntax. 237 Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/). 238 Example to zero-prefix a count, used commonly for naming servers: 239 `format("web-%03d", count.index + 1)`. 240 241 * `formatlist(format, args, ...)` - Formats each element of a list 242 according to the given format, similarly to `format`, and returns a list. 243 Non-list arguments are repeated for each list element. 244 For example, to convert a list of DNS addresses to a list of URLs, you might use: 245 `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. 246 If multiple args are lists, and they have the same number of elements, then the formatting is applied to the elements of the lists in parallel. 247 Example: 248 `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. 249 Passing lists with different lengths to formatlist results in an error. 250 251 * `index(list, elem)` - Finds the index of a given element in a list. 252 This function only works on flat lists. 253 Example: `index(aws_instance.foo.*.tags.Name, "foo-test")` 254 255 * `join(delim, list)` - Joins the list with the delimiter for a resultant string. 256 This function works only on flat lists. 257 Examples: 258 * `join(",", aws_instance.foo.*.id)` 259 * `join(",", var.ami_list)` 260 261 * `jsonencode(item)` - Returns a JSON-encoded representation of the given 262 item, which may be a string, list of strings, or map from string to string. 263 Note that if the item is a string, the return value includes the double 264 quotes. 265 266 * `keys(map)` - Returns a lexically sorted list of the map keys. 267 268 * `length(list)` - Returns the number of members in a given list or map, or the number of characters in a given string. 269 * `${length(split(",", "a,b,c"))}` = 3 270 * `${length("a,b,c")}` = 5 271 * `${length(map("key", "val"))}` = 1 272 273 * `list(items, ...)` - Returns a list consisting of the arguments to the function. 274 This function provides a way of representing list literals in interpolation. 275 * `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`. 276 * `${list()}` returns an empty list. 277 278 * `log(x, base)` - Returns the logarithm of `x`. 279 280 * `lookup(map, key, [default])` - Performs a dynamic lookup into a map 281 variable. The `map` parameter should be another variable, such 282 as `var.amis`. If `key` does not exist in `map`, the interpolation will 283 fail unless you specify a third argument, `default`, which should be a 284 string value to return if no `key` is found in `map`. This function 285 only works on flat maps and will return an error for maps that 286 include nested lists or maps. 287 288 * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case. 289 290 * `map(key, value, ...)` - Returns a map consisting of the key/value pairs 291 specified as arguments. Every odd argument must be a string key, and every 292 even argument must have the same type as the other values specified. 293 Duplicate keys are not allowed. Examples: 294 * `map("hello", "world")` 295 * `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))` 296 297 * `matchkeys(values, keys, searchset)` - For two lists `values` and `keys` of 298 equal length, returns all elements from `values` where the corresponding 299 element from `keys` exists in the `searchset` list. E.g. 300 `matchkeys(aws_instance.example.*.id, 301 aws_instance.example.*.availability_zone, list("us-west-2a"))` will return a 302 list of the instance IDs of the `aws_instance.example` instances in 303 `"us-west-2a"`. No match will result in empty list. Items of `keys` are 304 processed sequentially, so the order of returned `values` is preserved. 305 306 * `max(float1, float2, ...)` - Returns the largest of the floats. 307 308 * `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps 309 are consumed in the order provided, and duplicate keys overwrite previous 310 entries. 311 * `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}` 312 313 * `min(float1, float2, ...)` - Returns the smallest of the floats. 314 315 * `md5(string)` - Returns a (conventional) hexadecimal representation of the 316 MD5 hash of the given string. 317 318 * `pathexpand(string)` - Returns a filepath string with `~` expanded to the home directory. Note: 319 This will create a plan diff between two different hosts, unless the filepaths are the same. 320 321 * `pow(x, y)` - Returns the base `x` of exponential `y` as a float. 322 323 Example: 324 * `${pow(3,2)}` = 9 325 * `${pow(4,0)}` = 1 326 327 * `replace(string, search, replace)` - Does a search and replace on the 328 given string. All instances of `search` are replaced with the value 329 of `replace`. If `search` is wrapped in forward slashes, it is treated 330 as a regular expression. If using a regular expression, `replace` 331 can reference subcaptures in the regular expression by using `$n` where 332 `n` is the index or name of the subcapture. If using a regular expression, 333 the syntax conforms to the [re2 regular expression syntax](https://github.com/google/re2/wiki/Syntax). 334 335 * `sha1(string)` - Returns a (conventional) hexadecimal representation of the 336 SHA-1 hash of the given string. 337 Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"` 338 339 * `sha256(string)` - Returns a (conventional) hexadecimal representation of the 340 SHA-256 hash of the given string. 341 Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"` 342 343 * `sha512(string)` - Returns a (conventional) hexadecimal representation of the 344 SHA-512 hash of the given string. 345 Example: `"${sha512("${aws_vpc.default.tags.customer}-s3-bucket")}"` 346 347 * `signum(int)` - Returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. 348 This function is useful when you need to set a value for the first resource and 349 a different value for the rest of the resources. 350 Example: `element(split(",", var.r53_failover_policy), signum(count.index))` 351 where the 0th index points to `PRIMARY` and 1st to `FAILOVER` 352 353 * `slice(list, from, to)` - Returns the portion of `list` between `from` (inclusive) and `to` (exclusive). 354 Example: `slice(var.list_of_strings, 0, length(var.list_of_strings) - 1)` 355 356 * `sort(list)` - Returns a lexographically sorted list of the strings contained in 357 the list passed as an argument. Sort may only be used with lists which contain only 358 strings. 359 Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)` 360 361 * `split(delim, string)` - Splits the string previously created by `join` 362 back into a list. This is useful for pushing lists through module 363 outputs since they currently only support string values. Depending on the 364 use, the string this is being performed within may need to be wrapped 365 in brackets to indicate that the output is actually a list, e.g. 366 `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. 367 Example: `split(",", module.amod.server_ids)` 368 369 * `substr(string, offset, length)` - Extracts a substring from the input string. A negative offset is interpreted as being equivalent to a positive offset measured backwards from the end of the string. A length of `-1` is interpreted as meaning "until the end of the string". 370 371 * `timestamp()` - Returns a UTC timestamp string in RFC 3339 format. This string will change with every 372 invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the 373 [`ignore_changes`](/docs/configuration/resources.html#ignore-changes) lifecycle attribute. 374 375 * `title(string)` - Returns a copy of the string with the first characters of all the words capitalized. 376 377 * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed. 378 379 * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case. 380 381 * `uuid()` - Returns a UUID string in RFC 4122 v4 format. This string will change with every invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the [`ignore_changes`](/docs/configuration/resources.html#ignore-changes) lifecycle attribute. 382 383 * `values(map)` - Returns a list of the map values, in the order of the keys 384 returned by the `keys` function. This function only works on flat maps and 385 will return an error for maps that include nested lists or maps. 386 387 * `zipmap(list, list)` - Creates a map from a list of keys and a list of 388 values. The keys must all be of type string, and the length of the lists 389 must be the same. 390 For example, to output a mapping of AWS IAM user names to the fingerprint 391 of the key used to encrypt their initial password, you might use: 392 `zipmap(aws_iam_user.users.*.name, aws_iam_user_login_profile.users.*.key_fingerprint)`. 393 394 ## Templates 395 396 Long strings can be managed using templates. 397 [Templates](/docs/providers/template/index.html) are 398 [data-sources](/docs/configuration/data-sources.html) defined by a 399 filename and some variables to use during interpolation. They have a 400 computed `rendered` attribute containing the result. 401 402 A template data source looks like: 403 404 ```hcl 405 data "template_file" "example" { 406 template = "$${hello} $${world}!" 407 vars { 408 hello = "goodnight" 409 world = "moon" 410 } 411 } 412 413 output "rendered" { 414 value = "${data.template_file.example.rendered}" 415 } 416 ``` 417 418 Then the rendered value would be `goodnight moon!`. 419 420 You may use any of the built-in functions in your template. For more 421 details on template usage, please see the 422 [template_file documentation](/docs/providers/template/d/file.html). 423 424 ### Using Templates with Count 425 426 Here is an example that combines the capabilities of templates with the interpolation 427 from `count` to give us a parameterized template, unique to each resource instance: 428 429 ```hcl 430 variable "count" { 431 default = 2 432 } 433 434 variable "hostnames" { 435 default = { 436 "0" = "example1.org" 437 "1" = "example2.net" 438 } 439 } 440 441 data "template_file" "web_init" { 442 # Render the template once for each instance 443 count = "${length(var.hostnames)}" 444 template = "${file("templates/web_init.tpl")}" 445 vars { 446 # count.index tells us the index of the instance we are rendering 447 hostname = "${var.hostnames[count.index]}" 448 } 449 } 450 451 resource "aws_instance" "web" { 452 # Create one instance for each hostname 453 count = "${length(var.hostnames)}" 454 455 # Pass each instance its corresponding template_file 456 user_data = "${data.template_file.web_init.*.rendered[count.index]}" 457 } 458 ``` 459 460 With this, we will build a list of `template_file.web_init` data resources 461 which we can use in combination with our list of `aws_instance.web` resources. 462 463 ## Math 464 465 Simple math can be performed in interpolations: 466 467 ```hcl 468 variable "count" { 469 default = 2 470 } 471 472 resource "aws_instance" "web" { 473 # ... 474 475 count = "${var.count}" 476 477 # Tag the instance with a counter starting at 1, ie. web-001 478 tags { 479 Name = "${format("web-%03d", count.index + 1)}" 480 } 481 } 482 ``` 483 484 The supported operations are: 485 486 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types 487 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types 488 489 Operator precedences is the standard mathematical order of operations: 490 *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) have precedence over 491 *Add* (`+`) and *Subtract* (`-`). Parenthesis can be used to force ordering. 492 493 ```text 494 "${2 * 4 + 3 * 3}" # computes to 17 495 "${3 * 3 + 2 * 4}" # computes to 17 496 "${2 * (4 + 3) * 3}" # computes to 42 497 ``` 498 499 You can use the [terraform console](/docs/commands/console.html) command to 500 try the math operations. 501 502 -> **Note:** Since Terraform allows hyphens in resource and variable names, 503 it's best to use spaces between math operators to prevent confusion or unexpected 504 behavior. For example, `${var.instance-count - 1}` will subtract **1** from the 505 `instance-count` variable value, while `${var.instance-count-1}` will interpolate 506 the `instance-count-1` variable value.