github.com/recobe182/terraform@v0.8.5-0.20170117231232-49ab22a935b7/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 This is documented in more detail in the [resource configuration 64 page](/docs/configuration/resources.html). 65 66 #### Outputs from a module 67 68 The syntax is `MODULE.NAME.OUTPUT`. For example `${module.foo.bar}` will 69 interpolate the `bar` output from the `foo` 70 [module](/docs/modules/index.html). 71 72 #### Count information 73 74 The syntax is `count.FIELD`. For example, `${count.index}` will 75 interpolate the current index in a multi-count resource. For more 76 information on `count`, see the [resource configuration 77 page](/docs/configuration/resources.html). 78 79 <a id="path-variables"></a> 80 81 #### Path information 82 83 The syntax is `path.TYPE`. TYPE can be `cwd`, `module`, or `root`. 84 `cwd` will interpolate the current working directory. `module` will 85 interpolate the path to the current module. `root` will interpolate the 86 path of the root module. In general, you probably want the 87 `path.module` variable. 88 89 <a id="conditionals"></a> 90 ## Conditionals 91 92 Interpolations may contain conditionals to branch on the final value. 93 94 ``` 95 resource "aws_instance" "web" { 96 subnet = "${var.env == "production" ? var.prod_subnet : var.dev_subnet}" 97 } 98 ``` 99 100 The conditional syntax is the well-known ternary operation: 101 102 CONDITION ? TRUEVAL : FALSEVAL 103 104 The condition can be any valid interpolation syntax, such as variable 105 access, a function call, or even another conditional. The true and false 106 value can also be any valid interpolation syntax. The returned types by 107 the true and false side must be the same. 108 109 The support operators are: 110 111 * Equality: `==` and `!=` 112 * Numerical comparison: `>`, `<`, `>=`, `<=` 113 * Boolean logic: `&&`, `||`, unary `!` 114 115 A common use case for conditionals is to enable/disable a resource by 116 conditionally setting the count: 117 118 ``` 119 resource "aws_instance" "vpn" { 120 count = "${var.something ? 1 : 0}" 121 } 122 ``` 123 124 In the example above, the "vpn" resource will only be included if 125 "var.something" evaluates to true. Otherwise, the VPN resource will 126 not be created at all. 127 128 <a id="functions"></a> 129 ## Built-in Functions 130 131 Terraform ships with built-in functions. Functions are called with the 132 syntax `name(arg, arg2, ...)`. For example, to read a file: 133 `${file("path.txt")}`. 134 135 ### Supported built-in functions 136 137 The supported built-in functions are: 138 139 * `base64decode(string)` - Given a base64-encoded string, decodes it and 140 returns the original string. 141 142 * `base64encode(string)` - Returns a base64-encoded representation of the 143 given string. 144 145 * `base64sha256(string)` - Returns a base64-encoded representation of raw 146 SHA-256 sum of the given string. 147 **This is not equivalent** of `base64encode(sha256(string))` 148 since `sha256()` returns hexadecimal representation. 149 150 * `ceil(float)` - Returns the least integer value greater than or equal 151 to the argument. 152 153 * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation 154 and creates an IP address with the given host number. For example, 155 `cidrhost("10.0.0.0/8", 2)` returns `10.0.0.2`. 156 157 * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation 158 and returns the address-formatted subnet mask format that some 159 systems expect for IPv4 interfaces. For example, 160 `cidrnetmask("10.0.0.0/8")` returns `255.0.0.0`. Not applicable 161 to IPv6 networks since CIDR notation is the only valid notation for 162 IPv6. 163 164 * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in 165 CIDR notation (like `10.0.0.0/8`) and extends its prefix to include an 166 additional subnet number. For example, 167 `cidrsubnet("10.0.0.0/8", 8, 2)` returns `10.2.0.0/16`; 168 `cidrsubnet("2607:f298:6051:516c::/64", 8, 2)` returns 169 `2607:f298:6051:516c:200::/72`. 170 171 * `coalesce(string1, string2, ...)` - Returns the first non-empty value from 172 the given arguments. At least two arguments must be provided. 173 174 * `compact(list)` - Removes empty string elements from a list. This can be 175 useful in some cases, for example when passing joined lists as module 176 variables or when parsing module outputs. 177 Example: `compact(module.my_asg.load_balancer_names)` 178 179 * `concat(list1, list2, ...)` - Combines two or more lists into a single list. 180 Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)` 181 182 * `distinct(list)` - Removes duplicate items from a list. Keeps the first 183 occurrence of each element, and removes subsequent occurrences. This 184 function is only valid for flat lists. Example: `distinct(var.usernames)` 185 186 * `element(list, index)` - Returns a single element from a list 187 at the given index. If the index is greater than the number of 188 elements, this function will wrap using a standard mod algorithm. 189 This function only works on flat lists. Examples: 190 * `element(aws_subnet.foo.*.id, count.index)` 191 * `element(var.list_of_strings, 2)` 192 193 * `file(path)` - Reads the contents of a file into the string. Variables 194 in this file are _not_ interpolated. The contents of the file are 195 read as-is. The `path` is interpreted relative to the working directory. 196 [Path variables](#path-variables) can be used to reference paths relative 197 to other base locations. For example, when using `file()` from inside a 198 module, you generally want to make the path relative to the module base, 199 like this: `file("${path.module}/file")`. 200 201 * `floor(float)` - Returns the greatest integer value less than or equal to 202 the argument. 203 204 * `format(format, args, ...)` - Formats a string according to the given 205 format. The syntax for the format is standard `sprintf` syntax. 206 Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/). 207 Example to zero-prefix a count, used commonly for naming servers: 208 `format("web-%03d", count.index + 1)`. 209 210 * `formatlist(format, args, ...)` - Formats each element of a list 211 according to the given format, similarly to `format`, and returns a list. 212 Non-list arguments are repeated for each list element. 213 For example, to convert a list of DNS addresses to a list of URLs, you might use: 214 `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. 215 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. 216 Example: 217 `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. 218 Passing lists with different lengths to formatlist results in an error. 219 220 * `index(list, elem)` - Finds the index of a given element in a list. 221 This function only works on flat lists. 222 Example: `index(aws_instance.foo.*.tags.Name, "foo-test")` 223 224 * `join(delim, list)` - Joins the list with the delimiter for a resultant string. 225 This function works only on flat lists. 226 Examples: 227 * `join(",", aws_instance.foo.*.id)` 228 * `join(",", var.ami_list)` 229 230 * `jsonencode(item)` - Returns a JSON-encoded representation of the given 231 item, which may be a string, list of strings, or map from string to string. 232 Note that if the item is a string, the return value includes the double 233 quotes. 234 235 * `keys(map)` - Returns a lexically sorted list of the map keys. 236 237 * `length(list)` - Returns the number of members in a given list or map, or the number of characters in a given string. 238 * `${length(split(",", "a,b,c"))}` = 3 239 * `${length("a,b,c")}` = 5 240 * `${length(map("key", "val"))}` = 1 241 242 * `list(items, ...)` - Returns a list consisting of the arguments to the function. 243 This function provides a way of representing list literals in interpolation. 244 * `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`. 245 * `${list()}` returns an empty list. 246 247 * `lookup(map, key, [default])` - Performs a dynamic lookup into a map 248 variable. The `map` parameter should be another variable, such 249 as `var.amis`. If `key` does not exist in `map`, the interpolation will 250 fail unless you specify a third argument, `default`, which should be a 251 string value to return if no `key` is found in `map`. This function 252 only works on flat maps and will return an error for maps that 253 include nested lists or maps. 254 255 * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case. 256 257 * `map(key, value, ...)` - Returns a map consisting of the key/value pairs 258 specified as arguments. Every odd argument must be a string key, and every 259 even argument must have the same type as the other values specified. 260 Duplicate keys are not allowed. Examples: 261 * `map("hello", "world")` 262 * `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))` 263 264 * `max(float1, float2, ...)` - Returns the largest of the floats. 265 266 * `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps 267 are consumed in the order provided, and duplicate keys overwrite previous 268 entries. 269 * `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}` 270 271 * `min(float1, float2, ...)` - Returns the smallest of the floats. 272 273 * `md5(string)` - Returns a (conventional) hexadecimal representation of the 274 MD5 hash of the given string. 275 276 * `replace(string, search, replace)` - Does a search and replace on the 277 given string. All instances of `search` are replaced with the value 278 of `replace`. If `search` is wrapped in forward slashes, it is treated 279 as a regular expression. If using a regular expression, `replace` 280 can reference subcaptures in the regular expression by using `$n` where 281 `n` is the index or name of the subcapture. If using a regular expression, 282 the syntax conforms to the [re2 regular expression syntax](https://code.google.com/p/re2/wiki/Syntax). 283 284 * `sha1(string)` - Returns a (conventional) hexadecimal representation of the 285 SHA-1 hash of the given string. 286 Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"` 287 288 * `sha256(string)` - Returns a (conventional) hexadecimal representation of the 289 SHA-256 hash of the given string. 290 Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"` 291 292 * `signum(int)` - Returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers. 293 This function is useful when you need to set a value for the first resource and 294 a different value for the rest of the resources. 295 Example: `element(split(",", var.r53_failover_policy), signum(count.index))` 296 where the 0th index points to `PRIMARY` and 1st to `FAILOVER` 297 298 * `sort(list)` - Returns a lexicographically sorted list of the strings contained in 299 the list passed as an argument. Sort may only be used with lists which contain only 300 strings. 301 Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)` 302 303 * `split(delim, string)` - Splits the string previously created by `join` 304 back into a list. This is useful for pushing lists through module 305 outputs since they currently only support string values. Depending on the 306 use, the string this is being performed within may need to be wrapped 307 in brackets to indicate that the output is actually a list, e.g. 308 `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. 309 Example: `split(",", module.amod.server_ids)` 310 311 * `timestamp()` - Returns a UTC timestamp string in RFC 3339 format. This string will change with every 312 invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the 313 [`ignore_changes`](/docs/configuration/resources.html#ignore-changes) lifecycle attribute. 314 315 * `title(string)` - Returns a copy of the string with the first characters of all the words capitalized. 316 317 * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed. 318 319 * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case. 320 321 * `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. 322 323 * `values(map)` - Returns a list of the map values, in the order of the keys 324 returned by the `keys` function. This function only works on flat maps and 325 will return an error for maps that include nested lists or maps. 326 327 * `zipmap(list, list)` - Creates a map from a list of keys and a list of 328 values. The keys must all be of type string, and the length of the lists 329 must be the same. 330 For example, to output a mapping of AWS IAM user names to the fingerprint 331 of the key used to encrypt their initial password, you might use: 332 `zipmap(aws_iam_user.users.*.name, aws_iam_user_login_profile.users.*.key_fingerprint)`. 333 334 <a id="templates"></a> 335 ## Templates 336 337 Long strings can be managed using templates. 338 [Templates](/docs/providers/template/index.html) are 339 [data-sources](/docs/configuration/data-sources.html) defined by a 340 filename and some variables to use during interpolation. They have a 341 computed `rendered` attribute containing the result. 342 343 A template data source looks like: 344 345 ``` 346 data "template_file" "example" { 347 template = "$${hello} $${world}!" 348 vars { 349 hello = "goodnight" 350 world = "moon" 351 } 352 } 353 354 output "rendered" { 355 value = "${data.template_file.example.rendered}" 356 } 357 ``` 358 359 Then the rendered value would be `goodnight moon!`. 360 361 You may use any of the built-in functions in your template. For more 362 details on template usage, please see the 363 [template_file documentation](/docs/providers/template/d/file.html). 364 365 ### Using Templates with Count 366 367 Here is an example that combines the capabilities of templates with the interpolation 368 from `count` to give us a parameterized template, unique to each resource instance: 369 370 ``` 371 variable "count" { 372 default = 2 373 } 374 375 variable "hostnames" { 376 default = { 377 "0" = "example1.org" 378 "1" = "example2.net" 379 } 380 } 381 382 data "template_file" "web_init" { 383 // here we expand multiple template_files - the same number as we have instances 384 count = "${var.count}" 385 template = "${file("templates/web_init.tpl")}" 386 vars { 387 // that gives us access to use count.index to do the lookup 388 hostname = "${lookup(var.hostnames, count.index)}" 389 } 390 } 391 392 resource "aws_instance" "web" { 393 // ... 394 count = "${var.count}" 395 // here we link each web instance to the proper template_file 396 user_data = "${element(data.template_file.web_init.*.rendered, count.index)}" 397 } 398 ``` 399 400 With this, we will build a list of `template_file.web_init` data sources which we can 401 use in combination with our list of `aws_instance.web` resources. 402 403 <a id="math"></a> 404 ## Math 405 406 Simple math can be performed in interpolations: 407 408 ``` 409 variable "count" { 410 default = 2 411 } 412 413 resource "aws_instance" "web" { 414 // ... 415 count = "${var.count}" 416 417 // tag the instance with a counter starting at 1, ie. web-001 418 tags { 419 Name = "${format("web-%03d", count.index + 1)}" 420 } 421 } 422 ``` 423 424 The supported operations are: 425 426 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types 427 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types 428 429 Operator precedences is the standard mathematical order of operations: 430 *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) have precedence over 431 *Add* (`+`) and *Subtract* (`-`). Parenthesis can be used to force ordering. 432 433 ``` 434 "${2 * 4 + 3 * 3}" # computes to 17 435 "${3 * 3 + 2 * 4}" # computes to 17 436 "${2 * (4 + 3) * 3}" # computes to 42 437 ``` 438 439 You can use the [terraform console](/docs/commands/console.html) command to 440 try the math operations. 441 442 -> **Note:** Since Terraform allows hyphens in resource and variable names, 443 it's best to use spaces between math operators to prevent confusion or unexpected 444 behavior. For example, `${var.instance-count - 1}` will subtract **1** from the 445 `instance-count` variable value, while `${var.instance-count-1}` will interpolate 446 the `instance-count-1` variable value.