2014-07-28 19:43:00 +02:00
---
layout: "docs"
page_title: "Interpolation Syntax"
sidebar_current: "docs-config-interpolation"
2014-10-22 05:21:56 +02:00
description: |-
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}` .
2014-07-28 19:43:00 +02:00
---
# Interpolation Syntax
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}` .
The interpolation syntax is powerful and allows you to reference
variables, attributes of resources, call functions, etc.
2015-04-03 16:51:12 +02:00
You can also perform simple math in interpolations, allowing
2015-08-04 20:09:43 +02:00
you to write expressions such as `${count.index + 1}` .
2015-04-03 16:51:12 +02:00
2015-05-14 05:22:14 +02:00
You can escape interpolation with double dollar signs: `$${foo}`
will be rendered as a literal `${foo}` .
2014-10-03 07:11:53 +02:00
## Available Variables
**To reference user variables**, use the `var.` prefix followed by the
2014-07-28 19:43:00 +02:00
variable name. For example, `${var.foo}` will interpolate the
`foo` variable value. If the variable is a mapping, then you
can reference static keys in the map with the syntax
`var.MAP.KEY` . For example, `${var.amis.us-east-1}` would
get the value of the `us-east-1` key within the `amis` variable
that is a mapping.
2015-02-24 00:04:18 +01:00
**To reference attributes of your own resource**, the syntax is
`self.ATTRIBUTE` . For example `${self.private_ip_address}` will
interpolate that resource's private IP address. Note that this is
only allowed/valid within provisioners.
2014-10-03 07:11:53 +02:00
**To reference attributes of other resources**, the syntax is
2014-07-28 19:43:00 +02:00
`TYPE.NAME.ATTRIBUTE` . For example, `${aws_instance.web.id}`
will interpolate the ID attribute from the "aws\_instance"
2014-10-10 06:25:59 +02:00
resource named "web". If the resource has a `count` attribute set,
you can access individual attributes with a zero-based index, such
as `${aws_instance.web.0.id}` . You can also use the splat syntax
2015-01-14 18:28:25 +01:00
to get a list of all the attributes: `${aws_instance.web.*.id}` .
2014-10-10 06:25:59 +02:00
This is documented in more detail in the
[resource configuration page ](/docs/configuration/resources.html ).
2014-07-28 19:43:00 +02:00
2014-10-03 07:11:53 +02:00
**To reference outputs from a module**, the syntax is
`MODULE.NAME.OUTPUT` . For example `${module.foo.bar}` will
interpolate the "bar" output from the "foo"
[module ](/docs/modules/index.html ).
**To reference count information**, the syntax is `count.FIELD` .
For example, `${count.index}` will interpolate the current index
in a multi-count resource. For more information on count, see the
resource configuration page.
2014-07-28 19:43:00 +02:00
2015-07-31 18:44:07 +02:00
< a id = "path-variables" > < / a >
2014-10-08 05:15:08 +02:00
**To reference path information**, the syntax is `path.TYPE` .
TYPE can be `cwd` , `module` , or `root` . `cwd` will interpolate the
cwd. `module` will interpolate the path to the current module. `root`
will interpolate the path of the root module. In general, you probably
want the `path.module` variable.
2014-07-28 19:43:00 +02:00
## Built-in Functions
2014-10-03 07:11:53 +02:00
Terraform ships with built-in functions. Functions are called with
the syntax `name(arg, arg2, ...)` . For example,
to read a file: `${file("path.txt")}` . The built-in functions
are documented below.
2014-07-28 19:43:00 +02:00
The supported built-in functions are:
2015-10-03 23:49:50 +02:00
* `base64dec(string)` - Given a base64-encoded string, decodes it and
returns the original string.
* `base64enc(string)` - Returns a base64-encoded representation of the
given string.
2015-05-03 16:53:33 +02:00
* `concat(list1, list2)` - Combines two or more lists into a single list.
2015-07-10 01:04:36 +02:00
Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)`
2014-08-19 22:16:29 +02:00
2015-03-02 18:40:24 +01:00
* `element(list, index)` - Returns a single element from a list
at the given index. If the index is greater than the number of
elements, this function will wrap using a standard mod algorithm.
A list is only possible with splat variables from resources with
a count greater than one.
Example: `element(aws_subnet.foo.*.id, count.index)`
2014-08-19 22:16:29 +02:00
* `file(path)` - Reads the contents of a file into the string. Variables
in this file are _not_ interpolated. The contents of the file are
read as-is.
2014-07-28 19:43:00 +02:00
2015-03-02 19:27:58 +01:00
* `format(format, args...)` - Formats a string according to the given
format. The syntax for the format is standard `sprintf` syntax.
Good documentation for the syntax can be [found here ](http://golang.org/pkg/fmt/ ).
Example to zero-prefix a count, used commonly for naming servers:
2015-08-04 20:09:43 +02:00
`format("web-%03d", count.index + 1)` .
2015-03-02 19:27:58 +01:00
2015-05-06 05:34:40 +02:00
* `formatlist(format, args...)` - Formats each element of a list
according to the given format, similarly to `format` , and returns a list.
Non-list arguments are repeated for each list element.
For example, to convert a list of DNS addresses to a list of URLs, you might use:
`formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)` .
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.
Example:
`formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)` .
Passing lists with different lengths to formatlist results in an error.
2015-07-12 21:55:19 +02:00
* `index(list, elem)` - Finds the index of a given element in a list. Example:
`index(aws_instance.foo.*.tags.Name, "foo-test")`
2015-01-14 18:28:25 +01:00
* `join(delim, list)` - Joins the list with the delimiter. A list is
2014-10-10 06:23:49 +02:00
only possible with splat variables from resources with a count
greater than one. Example: `join(",", aws_instance.foo.*.id)`
2015-04-15 19:55:49 +02:00
* `length(list)` - Returns a number of members in a given list
or a number of characters in a given string.
* `${length(split(",", "a,b,c"))}` = 3
* `${length("a,b,c")}` = 5
2014-07-28 19:43:00 +02:00
* `lookup(map, key)` - Performs a dynamic lookup into a mapping
2015-02-20 19:04:53 +01:00
variable. The `map` parameter should be another variable, such
as `var.amis` .
2014-11-07 19:23:02 +01:00
2015-03-02 18:40:24 +01:00
* `replace(string, search, replace)` - Does a search and replace on the
given string. All instances of `search` are replaced with the value
of `replace` . If `search` is wrapped in forward slashes, it is treated
as a regular expression. If using a regular expression, `replace`
can reference subcaptures in the regular expression by using `$n` where
`n` is the index or name of the subcapture. If using a regular expression,
the syntax conforms to the [re2 regular expression syntax ](https://code.google.com/p/re2/wiki/Syntax ).
* `split(delim, string)` - Splits the string previously created by `join`
back into a list. This is useful for pushing lists through module
2015-05-08 23:49:29 +02:00
outputs since they currently only support string values. Depending on the
2015-05-14 05:22:14 +02:00
use, the string this is being performed within may need to be wrapped
2015-05-08 23:49:29 +02:00
in brackets to indicate that the output is actually a list, e.g.
`a_resource_param = ["${split(",", var.CSV_STRING)}"]` .
2015-03-02 18:40:24 +01:00
Example: `split(",", module.amod.server_ids)`
2015-05-04 20:41:18 +02:00
## Templates
2015-05-27 12:22:52 +02:00
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.
2015-05-04 20:41:18 +02:00
A template resource looks like:
```
resource "template_file" "example" {
filename = "template.txt"
vars {
hello = "goodnight"
world = "moon"
}
}
output "rendered" {
value = "${template_file.example.rendered}"
}
```
Assuming `template.txt` looks like this:
```
${hello} ${world}!
```
Then the rendered value would be `goodnight moon!` .
You may use any of the built-in functions in your template.
2015-05-29 19:19:52 +02:00
### Using Templates with Count
Here is an example that combines the capabilities of templates with the interpolation
from `count` to give us a parametized template, unique to each resource instance:
```
variable "count" {
default = 2
}
variable "hostnames" {
default = {
"0" = "example1.org"
"1" = "example2.net"
}
}
resource "template_file" "web_init" {
// here we expand multiple template_files - the same number as we have instances
count = "${var.count}"
filename = "templates/web_init.tpl"
vars {
// that gives us access to use count.index to do the lookup
hostname = "${lookup(var.hostnames, count.index)}"
}
}
resource "aws_instance" "web" {
// ...
count = "${var.count}"
// here we link each web instance to the proper template_file
user_data = "${element(template_file.web_init.*.rendered, count.index)}"
}
```
With this, we will build a list of `template_file.web_init` resources which we can
use in combination with our list of `aws_instance.web` resources.
2015-08-04 20:09:43 +02:00
## Math
Simple math can be performed in interpolations:
```
variable "count" {
default = 2
}
resource "aws_instance" "web" {
// ...
count = "${var.count}"
// tag the instance with a counter starting at 1, ie. web-001
tags {
Name = "${format("web-%03d", count.index + 1)}"
}
}
```
The supported operations are:
- *Add*, *Subtract* , *Multiply* , and *Divide* for **float** types
- *Add*, *Subtract* , *Multiply* , *Divide* , and *Modulo* for **integer** types
-> **Note:** Since Terraform allows hyphens in resource and variable names,
it's best to use spaces between math operators to prevent confusion or unexpected
behavior. For example, `${var.instance-count - 1}` will subtract **1** from the
`instance-count` variable value, while `${var.instance-count-1}` will interpolate
the `instance-count-1` variable value.