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