github.com/jsoriano/terraform@v0.6.7-0.20151026070445-8b70867fdd95/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 * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation 84 and creates an IP address with the given host number. For example, 85 ``cidrhost("10.0.0.0/8", 2)`` returns ``10.0.0.2``. 86 87 * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation 88 and returns the address-formatted subnet mask format that some 89 systems expect for IPv4 interfaces. For example, 90 ``cidrmask("10.0.0.0/8")`` returns ``255.0.0.0``. Not applicable 91 to IPv6 networks since CIDR notation is the only valid notation for 92 IPv6. 93 94 * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in 95 CIDR notation (like ``10.0.0.0/8``) and extends its prefix to include an 96 additional subnet number. For example, 97 ``cidrsubnet("10.0.0.0/8", 8, 2)`` returns ``10.2.0.0/16``. 98 99 * `compact(list)` - Removes empty string elements from a list. This can be 100 useful in some cases, for example when passing joined lists as module 101 variables or when parsing module outputs. 102 Example: `compact(module.my_asg.load_balancer_names)` 103 104 * `concat(list1, list2)` - Combines two or more lists into a single list. 105 Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)` 106 107 * `element(list, index)` - Returns a single element from a list 108 at the given index. If the index is greater than the number of 109 elements, this function will wrap using a standard mod algorithm. 110 A list is only possible with splat variables from resources with 111 a count greater than one. 112 Example: `element(aws_subnet.foo.*.id, count.index)` 113 114 * `file(path)` - Reads the contents of a file into the string. Variables 115 in this file are _not_ interpolated. The contents of the file are 116 read as-is. 117 118 * `format(format, args...)` - Formats a string according to the given 119 format. The syntax for the format is standard `sprintf` syntax. 120 Good documentation for the syntax can be [found here](http://golang.org/pkg/fmt/). 121 Example to zero-prefix a count, used commonly for naming servers: 122 `format("web-%03d", count.index + 1)`. 123 124 * `formatlist(format, args...)` - Formats each element of a list 125 according to the given format, similarly to `format`, and returns a list. 126 Non-list arguments are repeated for each list element. 127 For example, to convert a list of DNS addresses to a list of URLs, you might use: 128 `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. 129 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. 130 Example: 131 `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. 132 Passing lists with different lengths to formatlist results in an error. 133 134 * `index(list, elem)` - Finds the index of a given element in a list. Example: 135 `index(aws_instance.foo.*.tags.Name, "foo-test")` 136 137 * `join(delim, list)` - Joins the list with the delimiter. A list is 138 only possible with splat variables from resources with a count 139 greater than one. Example: `join(",", aws_instance.foo.*.id)` 140 141 * `length(list)` - Returns a number of members in a given list 142 or a number of characters in a given string. 143 * `${length(split(",", "a,b,c"))}` = 3 144 * `${length("a,b,c")}` = 5 145 146 * `lookup(map, key)` - Performs a dynamic lookup into a mapping 147 variable. The `map` parameter should be another variable, such 148 as `var.amis`. 149 150 * `lower(string)` - returns a copy of the string with all Unicode letters mapped to their lower case. 151 152 * `replace(string, search, replace)` - Does a search and replace on the 153 given string. All instances of `search` are replaced with the value 154 of `replace`. If `search` is wrapped in forward slashes, it is treated 155 as a regular expression. If using a regular expression, `replace` 156 can reference subcaptures in the regular expression by using `$n` where 157 `n` is the index or name of the subcapture. If using a regular expression, 158 the syntax conforms to the [re2 regular expression syntax](https://code.google.com/p/re2/wiki/Syntax). 159 160 * `split(delim, string)` - Splits the string previously created by `join` 161 back into a list. This is useful for pushing lists through module 162 outputs since they currently only support string values. Depending on the 163 use, the string this is being performed within may need to be wrapped 164 in brackets to indicate that the output is actually a list, e.g. 165 `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. 166 Example: `split(",", module.amod.server_ids)` 167 168 * `upper(string)` - returns a copy of the string with all Unicode letters mapped to their upper case. 169 170 ## Templates 171 172 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. 173 174 A template resource looks like: 175 176 ``` 177 resource "template_file" "example" { 178 filename = "template.txt" 179 vars { 180 hello = "goodnight" 181 world = "moon" 182 } 183 } 184 185 output "rendered" { 186 value = "${template_file.example.rendered}" 187 } 188 ``` 189 190 Assuming `template.txt` looks like this: 191 192 ``` 193 ${hello} ${world}! 194 ``` 195 196 Then the rendered value would be `goodnight moon!`. 197 198 You may use any of the built-in functions in your template. 199 200 201 ### Using Templates with Count 202 203 Here is an example that combines the capabilities of templates with the interpolation 204 from `count` to give us a parametized template, unique to each resource instance: 205 206 ``` 207 variable "count" { 208 default = 2 209 } 210 211 variable "hostnames" { 212 default = { 213 "0" = "example1.org" 214 "1" = "example2.net" 215 } 216 } 217 218 resource "template_file" "web_init" { 219 // here we expand multiple template_files - the same number as we have instances 220 count = "${var.count}" 221 filename = "templates/web_init.tpl" 222 vars { 223 // that gives us access to use count.index to do the lookup 224 hostname = "${lookup(var.hostnames, count.index)}" 225 } 226 } 227 228 resource "aws_instance" "web" { 229 // ... 230 count = "${var.count}" 231 // here we link each web instance to the proper template_file 232 user_data = "${element(template_file.web_init.*.rendered, count.index)}" 233 } 234 ``` 235 236 With this, we will build a list of `template_file.web_init` resources which we can 237 use in combination with our list of `aws_instance.web` resources. 238 239 ## Math 240 241 Simple math can be performed in interpolations: 242 243 ``` 244 variable "count" { 245 default = 2 246 } 247 248 resource "aws_instance" "web" { 249 // ... 250 count = "${var.count}" 251 252 // tag the instance with a counter starting at 1, ie. web-001 253 tags { 254 Name = "${format("web-%03d", count.index + 1)}" 255 } 256 } 257 ``` 258 259 The supported operations are: 260 261 - *Add*, *Subtract*, *Multiply*, and *Divide* for **float** types 262 - *Add*, *Subtract*, *Multiply*, *Divide*, and *Modulo* for **integer** types 263 264 -> **Note:** Since Terraform allows hyphens in resource and variable names, 265 it's best to use spaces between math operators to prevent confusion or unexpected 266 behavior. For example, `${var.instance-count - 1}` will subtract **1** from the 267 `instance-count` variable value, while `${var.instance-count-1}` will interpolate 268 the `instance-count-1` variable value.