github.com/mysza/terraform@v0.7.6-0.20161011024539-258005408b33/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 also perform [simple math](#math) in interpolations, allowing 19 you to write expressions such as `${count.index + 1}`. 20 21 You can escape interpolation with double dollar signs: `$${foo}` 22 will be rendered as a literal `${foo}`. 23 24 ## Available Variables 25 26 **To reference user string variables**, use the `var.` prefix followed by the 27 variable name. For example, `${var.foo}` will interpolate the 28 `foo` variable value. 29 30 **To reference user map variables**, the syntax is `var.MAP["KEY"]`. For 31 example, `${var.amis["us-east-1"]}` would get the value of the `us-east-1` 32 key within the `amis` map variable. 33 34 **To reference user list variables**, the syntax is `["${var.LIST}"]`. For 35 example, `["${var.subnets}"]` would get the value of the `subnets` list, as a 36 list. 37 38 **To reference attributes of your own resource**, the syntax is 39 `self.ATTRIBUTE`. For example `${self.private_ip_address}` will 40 interpolate that resource's private IP address. Note that this is 41 only allowed/valid within provisioners. 42 43 **To reference attributes of other resources**, the syntax is 44 `TYPE.NAME.ATTRIBUTE`. For example, `${aws_instance.web.id}` 45 will interpolate the ID attribute from the "aws\_instance" 46 resource named "web". If the resource has a `count` attribute set, 47 you can access individual attributes with a zero-based index, such 48 as `${aws_instance.web.0.id}`. You can also use the splat syntax 49 to get a list of all the attributes: `${aws_instance.web.*.id}`. 50 This is documented in more detail in the 51 [resource configuration page](/docs/configuration/resources.html). 52 53 **To reference outputs from a module**, the syntax is 54 `MODULE.NAME.OUTPUT`. For example `${module.foo.bar}` will 55 interpolate the "bar" output from the "foo" 56 [module](/docs/modules/index.html). 57 58 **To reference count information**, the syntax is `count.FIELD`. 59 For example, `${count.index}` will interpolate the current index 60 in a multi-count resource. For more information on count, see the 61 resource configuration page. 62 63 <a id="path-variables"></a> 64 65 **To reference path information**, the syntax is `path.TYPE`. 66 TYPE can be `cwd`, `module`, or `root`. `cwd` will interpolate the 67 cwd. `module` will interpolate the path to the current module. `root` 68 will interpolate the path of the root module. In general, you probably 69 want the `path.module` variable. 70 71 ## Built-in Functions 72 73 Terraform ships with built-in functions. Functions are called with 74 the syntax `name(arg, arg2, ...)`. For example, 75 to read a file: `${file("path.txt")}`. The built-in functions 76 are documented below. 77 78 The supported built-in functions are: 79 80 * `base64decode(string)` - Given a base64-encoded string, decodes it and 81 returns the original string. 82 83 * `base64encode(string)` - Returns a base64-encoded representation of the 84 given string. 85 86 * `base64sha256(string)` - Returns a base64-encoded representation of raw 87 SHA-256 sum of the given string. 88 **This is not equivalent** of `base64encode(sha256(string))` 89 since `sha256()` returns hexadecimal representation. 90 91 * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation 92 and creates an IP address with the given host number. For example, 93 ``cidrhost("10.0.0.0/8", 2)`` returns ``10.0.0.2``. 94 95 * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation 96 and returns the address-formatted subnet mask format that some 97 systems expect for IPv4 interfaces. For example, 98 ``cidrmask("10.0.0.0/8")`` returns ``255.0.0.0``. Not applicable 99 to IPv6 networks since CIDR notation is the only valid notation for 100 IPv4. 101 102 * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in 103 CIDR notation (like ``10.0.0.0/8``) and extends its prefix to include an 104 additional subnet number. For example, 105 ``cidrsubnet("10.0.0.0/8", 8, 2)`` returns ``10.2.0.0/16``; 106 ``cidrsubnet("2607:f298:6051:516c::/64", 8, 2)`` returns 107 ``2607:f298:6051:516c:200::/72``. 108 109 * `coalesce(string1, string2, ...)` - Returns the first non-empty value from 110 the given arguments. At least two arguments must be provided. 111 112 * `compact(list)` - Removes empty string elements from a list. This can be 113 useful in some cases, for example when passing joined lists as module 114 variables or when parsing module outputs. 115 Example: `compact(module.my_asg.load_balancer_names)` 116 117 * `concat(list1, list2, ...)` - Combines two or more lists into a single list. 118 Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)` 119 120 * `distinct(list)` - Removes duplicate items from a list. Keeps the first 121 occurrence of each element, and removes subsequent occurrences. This 122 function is only valid for flat lists. Example: `distinct(var.usernames)` 123 124 * `element(list, index)` - Returns a single element from a list 125 at the given index. If the index is greater than the number of 126 elements, this function will wrap using a standard mod algorithm. 127 This function only works on flat lists. Examples: 128 * `element(aws_subnet.foo.*.id, count.index)` 129 * `element(var.list_of_strings, 2)` 130 131 * `file(path)` - Reads the contents of a file into the string. Variables 132 in this file are _not_ interpolated. The contents of the file are 133 read as-is. The `path` is interpreted relative to the working directory. 134 [Path variables](#path-variables) can be used to reference paths relative 135 to other base locations. For example, when using `file()` from inside a 136 module, you generally want to make the path relative to the module base, 137 like this: `file("${path.module}/file")`. 138 139 * `format(format, args, ...)` - Formats a string according to the given 140 format. The syntax for the format is standard `sprintf` syntax. 141 Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/). 142 Example to zero-prefix a count, used commonly for naming servers: 143 `format("web-%03d", count.index + 1)`. 144 145 * `formatlist(format, args, ...)` - Formats each element of a list 146 according to the given format, similarly to `format`, and returns a list. 147 Non-list arguments are repeated for each list element. 148 For example, to convert a list of DNS addresses to a list of URLs, you might use: 149 `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. 150 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. 151 Example: 152 `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. 153 Passing lists with different lengths to formatlist results in an error. 154 155 * `index(list, elem)` - Finds the index of a given element in a list. 156 This function only works on flat lists. 157 Example: `index(aws_instance.foo.*.tags.Name, "foo-test")` 158 159 * `join(delim, list)` - Joins the list with the delimiter for a resultant string. 160 This function works only on flat lists. 161 Examples: 162 * `join(",", aws_instance.foo.*.id)` 163 * `join(",", var.ami_list)` 164 165 * `jsonencode(item)` - Returns a JSON-encoded representation of the given 166 item, which may be a string, list of strings, or map from string to string. 167 Note that if the item is a string, the return value includes the double 168 quotes. 169 170 * `keys(map)` - Returns a lexically sorted list of the map keys. 171 172 * `length(list)` - Returns a number of members in a given list or map, or a number of characters in a given string. 173 * `${length(split(",", "a,b,c"))}` = 3 174 * `${length("a,b,c")}` = 5 175 * `${length(map("key", "val"))}` = 1 176 177 * `list(items, ...)` - Returns a list consisting of the arguments to the function. 178 This function provides a way of representing list literals in interpolation. 179 * `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`. 180 * `${list()}` returns an empty list. 181 182 * `lookup(map, key [, default])` - Performs a dynamic lookup into a map 183 variable. The `map` parameter should be another variable, such 184 as `var.amis`. If `key` does not exist in `map`, the interpolation will 185 fail unless you specify a third argument, `default`, which should be a 186 string value to return if no `key` is found in `map`. This function 187 only works on flat maps and will return an error for maps that 188 include nested lists or maps. 189 190 * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case. 191 192 * `map(key, value, ...)` - Returns a map consisting of the key/value pairs 193 specified as arguments. Every odd argument must be a string key, and every 194 even argument must have the same type as the other values specified. 195 Duplicate keys are not allowed. Examples: 196 * `map("hello", "world")` 197 * `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))` 198 199 * `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps 200 are consumed in the order provided, and duplicate keys overwrite previous 201 entries. 202 * `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}` 203 204 * `md5(string)` - Returns a (conventional) hexadecimal representation of the 205 MD5 hash of the given string. 206 207 * `replace(string, search, replace)` - Does a search and replace on the 208 given string. All instances of `search` are replaced with the value 209 of `replace`. If `search` is wrapped in forward slashes, it is treated 210 as a regular expression. If using a regular expression, `replace` 211 can reference subcaptures in the regular expression by using `$n` where 212 `n` is the index or name of the subcapture. If using a regular expression, 213 the syntax conforms to the [re2 regular expression syntax](https://code.google.com/p/re2/wiki/Syntax). 214 215 * `sha1(string)` - Returns a (conventional) hexadecimal representation of the 216 SHA-1 hash of the given string. 217 Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"` 218 219 * `sha256(string)` - Returns a (conventional) hexadecimal representation of the 220 SHA-256 hash of the given string. 221 Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"` 222 223 * `signum(int)` - Returns -1 for negative numbers, 0 for 0 and 1 for positive numbers. 224 This function is useful when you need to set a value for the first resource and 225 a different value for the rest of the resources. 226 Example: `element(split(",", var.r53_failover_policy), signum(count.index))` 227 where the 0th index points to `PRIMARY` and 1st to `FAILOVER` 228 229 * `sort(list)` - Returns a lexographically sorted list of the strings contained in 230 the list passed as an argument. Sort may only be used with lists which contain only 231 strings. 232 Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)` 233 234 * `split(delim, string)` - Splits the string previously created by `join` 235 back into a list. This is useful for pushing lists through module 236 outputs since they currently only support string values. Depending on the 237 use, the string this is being performed within may need to be wrapped 238 in brackets to indicate that the output is actually a list, e.g. 239 `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. 240 Example: `split(",", module.amod.server_ids)` 241 242 * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed. 243 244 * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case. 245 246 * `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. 247 248 * `values(map)` - Returns a list of the map values, in the order of the keys 249 returned by the `keys` function. This function only works on flat maps and 250 will return an error for maps that include nested lists or maps. 251 252 ## Templates 253 254 Long strings can be managed using templates. [Templates](/docs/providers/template/index.html) are [data-sources](/docs/configuration/data-sources.html) defined by a filename and some variables to use during interpolation. They have a computed `rendered` attribute containing the result. 255 256 A template data source looks like: 257 258 ``` 259 data "template_file" "example" { 260 template = "${hello} ${world}!" 261 vars { 262 hello = "goodnight" 263 world = "moon" 264 } 265 } 266 267 output "rendered" { 268 value = "${data.template_file.example.rendered}" 269 } 270 ``` 271 272 Then the rendered value would be `goodnight moon!`. 273 274 You may use any of the built-in functions in your template. 275 276 ### Using Templates with Count 277 278 Here is an example that combines the capabilities of templates with the interpolation 279 from `count` to give us a parameterized template, unique to each resource instance: 280 281 ``` 282 variable "count" { 283 default = 2 284 } 285 286 variable "hostnames" { 287 default = { 288 "0" = "example1.org" 289 "1" = "example2.net" 290 } 291 } 292 293 data "template_file" "web_init" { 294 // here we expand multiple template_files - the same number as we have instances 295 count = "${var.count}" 296 template = "${file("templates/web_init.tpl")}" 297 vars { 298 // that gives us access to use count.index to do the lookup 299 hostname = "${lookup(var.hostnames, count.index)}" 300 } 301 } 302 303 resource "aws_instance" "web" { 304 // ... 305 count = "${var.count}" 306 // here we link each web instance to the proper template_file 307 user_data = "${element(data.template_file.web_init.*.rendered, count.index)}" 308 } 309 ``` 310 311 With this, we will build a list of `template_file.web_init` data sources which we can 312 use in combination with our list of `aws_instance.web` resources. 313 314 ## Math 315 316 <a id="math"></a> 317 318 Simple math can be performed in interpolations: 319 320 ``` 321 variable "count" { 322 default = 2 323 } 324 325 resource "aws_instance" "web" { 326 // ... 327 count = "${var.count}" 328 329 // tag the instance with a counter starting at 1, ie. web-001 330 tags { 331 Name = "${format("web-%03d", count.index + 1)}" 332 } 333 } 334 ``` 335 336 The supported operations are: 337 338 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types 339 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types 340 341 -> **Note:** Since Terraform allows hyphens in resource and variable names, 342 it's best to use spaces between math operators to prevent confusion or unexpected 343 behavior. For example, `${var.instance-count - 1}` will subtract **1** from the 344 `instance-count` variable value, while `${var.instance-count-1}` will interpolate 345 the `instance-count-1` variable value.