github.com/nathanielks/terraform@v0.6.1-0.20170509030759-13e1a62319dc/website/source/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 * `ceil(float)` - Returns the least integer value greater than or equal 167 to the argument. 168 169 * `chomp(string)` - Removes trailing newlines from the given string. 170 171 * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation 172 and creates an IP address with the given host number. If given host 173 number is negative, the count starts from the end of the range. 174 For example, `cidrhost("10.0.0.0/8", 2)` returns `10.0.0.2` and 175 `cidrhost("10.0.0.0/8", -2)` returns `10.255.255.254`. 176 177 * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation 178 and returns the address-formatted subnet mask format that some 179 systems expect for IPv4 interfaces. For example, 180 `cidrnetmask("10.0.0.0/8")` returns `255.0.0.0`. Not applicable 181 to IPv6 networks since CIDR notation is the only valid notation for 182 IPv6. 183 184 * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in 185 CIDR notation (like `10.0.0.0/8`) and extends its prefix to include an 186 additional subnet number. For example, 187 `cidrsubnet("10.0.0.0/8", 8, 2)` returns `10.2.0.0/16`; 188 `cidrsubnet("2607:f298:6051:516c::/64", 8, 2)` returns 189 `2607:f298:6051:516c:200::/72`. 190 191 * `coalesce(string1, string2, ...)` - Returns the first non-empty value from 192 the given arguments. At least two arguments must be provided. 193 194 * `coalescelist(list1, list2, ...)` - Returns the first non-empty list from 195 the given arguments. At least two arguments must be provided. 196 197 * `compact(list)` - Removes empty string elements from a list. This can be 198 useful in some cases, for example when passing joined lists as module 199 variables or when parsing module outputs. 200 Example: `compact(module.my_asg.load_balancer_names)` 201 202 * `concat(list1, list2, ...)` - Combines two or more lists into a single list. 203 Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)` 204 205 * `dirname(path)` - Returns all but the last element of path, typically the path's directory. 206 207 * `distinct(list)` - Removes duplicate items from a list. Keeps the first 208 occurrence of each element, and removes subsequent occurrences. This 209 function is only valid for flat lists. Example: `distinct(var.usernames)` 210 211 * `element(list, index)` - Returns a single element from a list 212 at the given index. If the index is greater than the number of 213 elements, this function will wrap using a standard mod algorithm. 214 This function only works on flat lists. Examples: 215 * `element(aws_subnet.foo.*.id, count.index)` 216 * `element(var.list_of_strings, 2)` 217 218 * `file(path)` - Reads the contents of a file into the string. Variables 219 in this file are _not_ interpolated. The contents of the file are 220 read as-is. The `path` is interpreted relative to the working directory. 221 [Path variables](#path-variables) can be used to reference paths relative 222 to other base locations. For example, when using `file()` from inside a 223 module, you generally want to make the path relative to the module base, 224 like this: `file("${path.module}/file")`. 225 226 * `floor(float)` - Returns the greatest integer value less than or equal to 227 the argument. 228 229 * `format(format, args, ...)` - Formats a string according to the given 230 format. The syntax for the format is standard `sprintf` syntax. 231 Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/). 232 Example to zero-prefix a count, used commonly for naming servers: 233 `format("web-%03d", count.index + 1)`. 234 235 * `formatlist(format, args, ...)` - Formats each element of a list 236 according to the given format, similarly to `format`, and returns a list. 237 Non-list arguments are repeated for each list element. 238 For example, to convert a list of DNS addresses to a list of URLs, you might use: 239 `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. 240 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. 241 Example: 242 `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. 243 Passing lists with different lengths to formatlist results in an error. 244 245 * `index(list, elem)` - Finds the index of a given element in a list. 246 This function only works on flat lists. 247 Example: `index(aws_instance.foo.*.tags.Name, "foo-test")` 248 249 * `join(delim, list)` - Joins the list with the delimiter for a resultant string. 250 This function works only on flat lists. 251 Examples: 252 * `join(",", aws_instance.foo.*.id)` 253 * `join(",", var.ami_list)` 254 255 * `jsonencode(item)` - Returns a JSON-encoded representation of the given 256 item, which may be a string, list of strings, or map from string to string. 257 Note that if the item is a string, the return value includes the double 258 quotes. 259 260 * `keys(map)` - Returns a lexically sorted list of the map keys. 261 262 * `length(list)` - Returns the number of members in a given list or map, or the number of characters in a given string. 263 * `${length(split(",", "a,b,c"))}` = 3 264 * `${length("a,b,c")}` = 5 265 * `${length(map("key", "val"))}` = 1 266 267 * `list(items, ...)` - Returns a list consisting of the arguments to the function. 268 This function provides a way of representing list literals in interpolation. 269 * `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`. 270 * `${list()}` returns an empty list. 271 272 * `log(x, base)` - Returns the logarithm of `x`. 273 274 * `lookup(map, key, [default])` - Performs a dynamic lookup into a map 275 variable. The `map` parameter should be another variable, such 276 as `var.amis`. If `key` does not exist in `map`, the interpolation will 277 fail unless you specify a third argument, `default`, which should be a 278 string value to return if no `key` is found in `map`. This function 279 only works on flat maps and will return an error for maps that 280 include nested lists or maps. 281 282 * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case. 283 284 * `map(key, value, ...)` - Returns a map consisting of the key/value pairs 285 specified as arguments. Every odd argument must be a string key, and every 286 even argument must have the same type as the other values specified. 287 Duplicate keys are not allowed. Examples: 288 * `map("hello", "world")` 289 * `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))` 290 291 * `matchkeys(values, keys, searchset)` - For two lists `values` and `keys` of 292 equal length, returns all elements from `values` where the corresponding 293 element from `keys` exists in the `searchset` list. E.g. 294 `matchkeys(aws_instance.example.*.id, 295 aws_instance.example.*.availability_zone, list("us-west-2a"))` will return a 296 list of the instance IDs of the `aws_instance.example` instances in 297 `"us-west-2a"`. No match will result in empty list. Items of `keys` are 298 processed sequentially, so the order of returned `values` is preserved. 299 300 * `max(float1, float2, ...)` - Returns the largest of the floats. 301 302 * `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps 303 are consumed in the order provided, and duplicate keys overwrite previous 304 entries. 305 * `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}` 306 307 * `min(float1, float2, ...)` - Returns the smallest of the floats. 308 309 * `md5(string)` - Returns a (conventional) hexadecimal representation of the 310 MD5 hash of the given string. 311 312 * `pathexpand(string)` - Returns a filepath string with `~` expanded to the home directory. Note: 313 This will create a plan diff between two different hosts, unless the filepaths are the same. 314 315 * `replace(string, search, replace)` - Does a search and replace on the 316 given string. All instances of `search` are replaced with the value 317 of `replace`. If `search` is wrapped in forward slashes, it is treated 318 as a regular expression. If using a regular expression, `replace` 319 can reference subcaptures in the regular expression by using `$n` where 320 `n` is the index or name of the subcapture. If using a regular expression, 321 the syntax conforms to the [re2 regular expression syntax](https://github.com/google/re2/wiki/Syntax). 322 323 * `sha1(string)` - Returns a (conventional) hexadecimal representation of the 324 SHA-1 hash of the given string. 325 Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"` 326 327 * `sha256(string)` - Returns a (conventional) hexadecimal representation of the 328 SHA-256 hash of the given string. 329 Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"` 330 331 * `sha512(string)` - Returns a (conventional) hexadecimal representation of the 332 SHA-512 hash of the given string. 333 Example: `"${sha512("${aws_vpc.default.tags.customer}-s3-bucket")}"` 334 335 * `signum(int)` - Returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. 336 This function is useful when you need to set a value for the first resource and 337 a different value for the rest of the resources. 338 Example: `element(split(",", var.r53_failover_policy), signum(count.index))` 339 where the 0th index points to `PRIMARY` and 1st to `FAILOVER` 340 341 * `slice(list, from, to)` - Returns the portion of `list` between `from` (inclusive) and `to` (exclusive). 342 Example: `slice(var.list_of_strings, 0, length(var.list_of_strings) - 1)` 343 344 * `sort(list)` - Returns a lexographically sorted list of the strings contained in 345 the list passed as an argument. Sort may only be used with lists which contain only 346 strings. 347 Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)` 348 349 * `split(delim, string)` - Splits the string previously created by `join` 350 back into a list. This is useful for pushing lists through module 351 outputs since they currently only support string values. Depending on the 352 use, the string this is being performed within may need to be wrapped 353 in brackets to indicate that the output is actually a list, e.g. 354 `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. 355 Example: `split(",", module.amod.server_ids)` 356 357 * `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". 358 359 * `timestamp()` - Returns a UTC timestamp string in RFC 3339 format. This string will change with every 360 invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the 361 [`ignore_changes`](/docs/configuration/resources.html#ignore-changes) lifecycle attribute. 362 363 * `title(string)` - Returns a copy of the string with the first characters of all the words capitalized. 364 365 * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed. 366 367 * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case. 368 369 * `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. 370 371 * `values(map)` - Returns a list of the map values, in the order of the keys 372 returned by the `keys` function. This function only works on flat maps and 373 will return an error for maps that include nested lists or maps. 374 375 * `zipmap(list, list)` - Creates a map from a list of keys and a list of 376 values. The keys must all be of type string, and the length of the lists 377 must be the same. 378 For example, to output a mapping of AWS IAM user names to the fingerprint 379 of the key used to encrypt their initial password, you might use: 380 `zipmap(aws_iam_user.users.*.name, aws_iam_user_login_profile.users.*.key_fingerprint)`. 381 382 ## Templates 383 384 Long strings can be managed using templates. 385 [Templates](/docs/providers/template/index.html) are 386 [data-sources](/docs/configuration/data-sources.html) defined by a 387 filename and some variables to use during interpolation. They have a 388 computed `rendered` attribute containing the result. 389 390 A template data source looks like: 391 392 ```hcl 393 data "template_file" "example" { 394 template = "$${hello} $${world}!" 395 vars { 396 hello = "goodnight" 397 world = "moon" 398 } 399 } 400 401 output "rendered" { 402 value = "${data.template_file.example.rendered}" 403 } 404 ``` 405 406 Then the rendered value would be `goodnight moon!`. 407 408 You may use any of the built-in functions in your template. For more 409 details on template usage, please see the 410 [template_file documentation](/docs/providers/template/d/file.html). 411 412 ### Using Templates with Count 413 414 Here is an example that combines the capabilities of templates with the interpolation 415 from `count` to give us a parameterized template, unique to each resource instance: 416 417 ```hcl 418 variable "count" { 419 default = 2 420 } 421 422 variable "hostnames" { 423 default = { 424 "0" = "example1.org" 425 "1" = "example2.net" 426 } 427 } 428 429 data "template_file" "web_init" { 430 # Expand multiple template files - the same number as we have instances 431 count = "${var.count}" 432 template = "${file("templates/web_init.tpl")}" 433 vars { 434 # that gives us access to use count.index to do the lookup 435 hostname = "${lookup(var.hostnames, count.index)}" 436 } 437 } 438 439 resource "aws_instance" "web" { 440 # ... 441 count = "${var.count}" 442 443 # Link each web instance to the proper template_file 444 user_data = "${element(data.template_file.web_init.*.rendered, count.index)}" 445 } 446 ``` 447 448 With this, we will build a list of `template_file.web_init` data sources which 449 we can use in combination with our list of `aws_instance.web` resources. 450 451 ## Math 452 453 Simple math can be performed in interpolations: 454 455 ```hcl 456 variable "count" { 457 default = 2 458 } 459 460 resource "aws_instance" "web" { 461 # ... 462 463 count = "${var.count}" 464 465 # Tag the instance with a counter starting at 1, ie. web-001 466 tags { 467 Name = "${format("web-%03d", count.index + 1)}" 468 } 469 } 470 ``` 471 472 The supported operations are: 473 474 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types 475 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types 476 477 Operator precedences is the standard mathematical order of operations: 478 *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) have precedence over 479 *Add* (`+`) and *Subtract* (`-`). Parenthesis can be used to force ordering. 480 481 ```text 482 "${2 * 4 + 3 * 3}" # computes to 17 483 "${3 * 3 + 2 * 4}" # computes to 17 484 "${2 * (4 + 3) * 3}" # computes to 42 485 ``` 486 487 You can use the [terraform console](/docs/commands/console.html) command to 488 try the math operations. 489 490 -> **Note:** Since Terraform allows hyphens in resource and variable names, 491 it's best to use spaces between math operators to prevent confusion or unexpected 492 behavior. For example, `${var.instance-count - 1}` will subtract **1** from the 493 `instance-count` variable value, while `${var.instance-count-1}` will interpolate 494 the `instance-count-1` variable value.