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.