github.com/erriapo/terraform@v0.6.12-0.20160203182612-0340ea72354f/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. 133 134 * `format(format, args...)` - Formats a string according to the given 135 format. The syntax for the format is standard `sprintf` syntax. 136 Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/). 137 Example to zero-prefix a count, used commonly for naming servers: 138 `format("web-%03d", count.index + 1)`. 139 140 * `formatlist(format, args...)` - Formats each element of a list 141 according to the given format, similarly to `format`, and returns a list. 142 Non-list arguments are repeated for each list element. 143 For example, to convert a list of DNS addresses to a list of URLs, you might use: 144 `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`. 145 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. 146 Example: 147 `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`. 148 Passing lists with different lengths to formatlist results in an error. 149 150 * `index(list, elem)` - Finds the index of a given element in a list. Example: 151 `index(aws_instance.foo.*.tags.Name, "foo-test")` 152 153 * `join(delim, list)` - Joins the list with the delimiter. A list is 154 only possible with splat variables from resources with a count 155 greater than one. Example: `join(",", aws_instance.foo.*.id)` 156 157 * `length(list)` - Returns a number of members in a given list 158 or a number of characters in a given string. 159 * `${length(split(",", "a,b,c"))}` = 3 160 * `${length("a,b,c")}` = 5 161 162 * `lookup(map, key)` - Performs a dynamic lookup into a mapping 163 variable. The `map` parameter should be another variable, such 164 as `var.amis`. 165 166 * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case. 167 168 * `replace(string, search, replace)` - Does a search and replace on the 169 given string. All instances of `search` are replaced with the value 170 of `replace`. If `search` is wrapped in forward slashes, it is treated 171 as a regular expression. If using a regular expression, `replace` 172 can reference subcaptures in the regular expression by using `$n` where 173 `n` is the index or name of the subcapture. If using a regular expression, 174 the syntax conforms to the [re2 regular expression syntax](https://code.google.com/p/re2/wiki/Syntax). 175 176 * `split(delim, string)` - Splits the string previously created by `join` 177 back into a list. This is useful for pushing lists through module 178 outputs since they currently only support string values. Depending on the 179 use, the string this is being performed within may need to be wrapped 180 in brackets to indicate that the output is actually a list, e.g. 181 `a_resource_param = ["${split(",", var.CSV_STRING)}"]`. 182 Example: `split(",", module.amod.server_ids)` 183 184 * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed. 185 186 * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case. 187 188 ## Templates 189 190 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. 191 192 A template resource looks like: 193 194 ``` 195 resource "template_file" "example" { 196 template = "${hello} ${world}!" 197 vars { 198 hello = "goodnight" 199 world = "moon" 200 } 201 } 202 203 output "rendered" { 204 value = "${template_file.example.rendered}" 205 } 206 ``` 207 208 Then the rendered value would be `goodnight moon!`. 209 210 You may use any of the built-in functions in your template. 211 212 ### Using Templates with Count 213 214 Here is an example that combines the capabilities of templates with the interpolation 215 from `count` to give us a parametized template, unique to each resource instance: 216 217 ``` 218 variable "count" { 219 default = 2 220 } 221 222 variable "hostnames" { 223 default = { 224 "0" = "example1.org" 225 "1" = "example2.net" 226 } 227 } 228 229 resource "template_file" "web_init" { 230 // here we expand multiple template_files - the same number as we have instances 231 count = "${var.count}" 232 template = "${file("templates/web_init.tpl")}" 233 vars { 234 // that gives us access to use count.index to do the lookup 235 hostname = "${lookup(var.hostnames, count.index)}" 236 } 237 } 238 239 resource "aws_instance" "web" { 240 // ... 241 count = "${var.count}" 242 // here we link each web instance to the proper template_file 243 user_data = "${element(template_file.web_init.*.rendered, count.index)}" 244 } 245 ``` 246 247 With this, we will build a list of `template_file.web_init` resources which we can 248 use in combination with our list of `aws_instance.web` resources. 249 250 ## Math 251 252 Simple math can be performed in interpolations: 253 254 ``` 255 variable "count" { 256 default = 2 257 } 258 259 resource "aws_instance" "web" { 260 // ... 261 count = "${var.count}" 262 263 // tag the instance with a counter starting at 1, ie. web-001 264 tags { 265 Name = "${format("web-%03d", count.index + 1)}" 266 } 267 } 268 ``` 269 270 The supported operations are: 271 272 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types 273 - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types 274 275 -> **Note:** Since Terraform allows hyphens in resource and variable names, 276 it's best to use spaces between math operators to prevent confusion or unexpected 277 behavior. For example, `${var.instance-count - 1}` will subtract **1** from the 278 `instance-count` variable value, while `${var.instance-count-1}` will interpolate 279 the `instance-count-1` variable value.