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.