github.com/recobe182/terraform@v0.8.5-0.20170117231232-49ab22a935b7/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 perform [simple math](#math) in interpolations, allowing
    19  you to write expressions such as `${count.index + 1}`. And you can
    20  also use [conditionals](#conditionals) to determine a value based
    21  on some logic.
    22  
    23  You can escape interpolation with double dollar signs: `$${foo}`
    24  will be rendered as a literal `${foo}`.
    25  
    26  ## Available Variables
    27  
    28  There are a variety of available variable references you can use.
    29  
    30  #### User string variables
    31  
    32  Use the `var.` prefix followed by the variable name. For example,
    33  `${var.foo}` will interpolate the `foo` variable value.
    34  
    35  #### User map variables
    36  
    37  The syntax is `var.MAP["KEY"]`. For example, `${var.amis["us-east-1"]}`
    38  would get the value of the `us-east-1` key within the `amis` map
    39  variable.
    40  
    41  #### User list variables
    42  
    43  The syntax is `["${var.LIST}"]`. For example, `["${var.subnets}"]`
    44  would get the value of the `subnets` list, as a list. You can also
    45  return list elements by index: `${var.subnets[idx]}`.
    46  
    47  #### Attributes of your own resource
    48  
    49  The syntax is `self.ATTRIBUTE`. For example `${self.private_ip_address}`
    50  will interpolate that resource's private IP address.
    51  
    52  -> **Note**: The `self.ATTRIBUTE` syntax is only allowed and valid within
    53  provisioners.
    54  
    55  #### Attributes of other resources
    56  
    57  The syntax is `TYPE.NAME.ATTRIBUTE`. For example,
    58  `${aws_instance.web.id}` will interpolate the ID attribute from the
    59  `aws_instance` resource named `web`. If the resource has a `count`
    60  attribute set, you can access individual attributes with a zero-based
    61  index, such as `${aws_instance.web.0.id}`. You can also use the splat
    62  syntax to get a list of all the attributes: `${aws_instance.web.*.id}`.
    63  This is documented in more detail in the [resource configuration
    64  page](/docs/configuration/resources.html).
    65  
    66  #### Outputs from a module
    67  
    68  The syntax is `MODULE.NAME.OUTPUT`. For example `${module.foo.bar}` will
    69  interpolate the `bar` output from the `foo`
    70  [module](/docs/modules/index.html).
    71  
    72  #### Count information
    73  
    74  The syntax is `count.FIELD`. For example, `${count.index}` will
    75  interpolate the current index in a multi-count resource. For more
    76  information on `count`, see the [resource configuration
    77  page](/docs/configuration/resources.html).
    78  
    79  <a id="path-variables"></a>
    80  
    81  #### Path information
    82  
    83  The syntax is `path.TYPE`. TYPE can be `cwd`, `module`, or `root`.
    84  `cwd` will interpolate the current working directory. `module` will
    85  interpolate the path to the current module. `root` will interpolate the
    86  path of the root module.  In general, you probably want the
    87  `path.module` variable.
    88  
    89  <a id="conditionals"></a>
    90  ## Conditionals
    91  
    92  Interpolations may contain conditionals to branch on the final value.
    93  
    94  ```
    95  resource "aws_instance" "web" {
    96    subnet = "${var.env == "production" ? var.prod_subnet : var.dev_subnet}"
    97  }
    98  ```
    99  
   100  The conditional syntax is the well-known ternary operation:
   101  
   102      CONDITION ? TRUEVAL : FALSEVAL
   103  
   104  The condition can be any valid interpolation syntax, such as variable
   105  access, a function call, or even another conditional. The true and false
   106  value can also be any valid interpolation syntax. The returned types by
   107  the true and false side must be the same.
   108  
   109  The support operators are:
   110  
   111    * Equality: `==` and `!=`
   112    * Numerical comparison: `>`, `<`, `>=`, `<=`
   113    * Boolean logic: `&&`, `||`, unary `!`
   114  
   115  A common use case for conditionals is to enable/disable a resource by
   116  conditionally setting the count:
   117  
   118  ```
   119  resource "aws_instance" "vpn" {
   120    count = "${var.something ? 1 : 0}"
   121  }
   122  ```
   123  
   124  In the example above, the "vpn" resource will only be included if
   125  "var.something" evaluates to true. Otherwise, the VPN resource will
   126  not be created at all.
   127  
   128  <a id="functions"></a>
   129  ## Built-in Functions
   130  
   131  Terraform ships with built-in functions. Functions are called with the
   132  syntax `name(arg, arg2, ...)`. For example, to read a file:
   133  `${file("path.txt")}`.
   134  
   135  ### Supported built-in functions
   136  
   137  The supported built-in functions are:
   138  
   139    * `base64decode(string)` - Given a base64-encoded string, decodes it and
   140      returns the original string.
   141  
   142    * `base64encode(string)` - Returns a base64-encoded representation of the
   143      given string.
   144  
   145    * `base64sha256(string)` - Returns a base64-encoded representation of raw
   146      SHA-256 sum of the given string.
   147      **This is not equivalent** of `base64encode(sha256(string))`
   148      since `sha256()` returns hexadecimal representation.
   149  
   150    * `ceil(float)` - Returns the least integer value greater than or equal
   151        to the argument.
   152  
   153    * `cidrhost(iprange, hostnum)` - Takes an IP address range in CIDR notation
   154      and creates an IP address with the given host number. For example,
   155      `cidrhost("10.0.0.0/8", 2)` returns `10.0.0.2`.
   156  
   157    * `cidrnetmask(iprange)` - Takes an IP address range in CIDR notation
   158      and returns the address-formatted subnet mask format that some
   159      systems expect for IPv4 interfaces. For example,
   160      `cidrnetmask("10.0.0.0/8")` returns `255.0.0.0`. Not applicable
   161      to IPv6 networks since CIDR notation is the only valid notation for
   162      IPv6.
   163  
   164    * `cidrsubnet(iprange, newbits, netnum)` - Takes an IP address range in
   165      CIDR notation (like `10.0.0.0/8`) and extends its prefix to include an
   166      additional subnet number. For example,
   167      `cidrsubnet("10.0.0.0/8", 8, 2)` returns `10.2.0.0/16`;
   168      `cidrsubnet("2607:f298:6051:516c::/64", 8, 2)` returns
   169      `2607:f298:6051:516c:200::/72`.
   170  
   171    * `coalesce(string1, string2, ...)` - Returns the first non-empty value from
   172      the given arguments. At least two arguments must be provided.
   173  
   174    * `compact(list)` - Removes empty string elements from a list. This can be
   175       useful in some cases, for example when passing joined lists as module
   176       variables or when parsing module outputs.
   177       Example: `compact(module.my_asg.load_balancer_names)`
   178  
   179    * `concat(list1, list2, ...)` - Combines two or more lists into a single list.
   180       Example: `concat(aws_instance.db.*.tags.Name, aws_instance.web.*.tags.Name)`
   181  
   182    * `distinct(list)` - Removes duplicate items from a list. Keeps the first
   183       occurrence of each element, and removes subsequent occurrences. This
   184       function is only valid for flat lists. Example: `distinct(var.usernames)`
   185  
   186    * `element(list, index)` - Returns a single element from a list
   187        at the given index. If the index is greater than the number of
   188        elements, this function will wrap using a standard mod algorithm.
   189        This function only works on flat lists. Examples:
   190        * `element(aws_subnet.foo.*.id, count.index)`
   191        * `element(var.list_of_strings, 2)`
   192  
   193    * `file(path)` - Reads the contents of a file into the string. Variables
   194        in this file are _not_ interpolated. The contents of the file are
   195        read as-is. The `path` is interpreted relative to the working directory.
   196        [Path variables](#path-variables) can be used to reference paths relative
   197        to other base locations. For example, when using `file()` from inside a
   198        module, you generally want to make the path relative to the module base,
   199        like this: `file("${path.module}/file")`.
   200  
   201    * `floor(float)` - Returns the greatest integer value less than or equal to
   202        the argument.
   203  
   204    * `format(format, args, ...)` - Formats a string according to the given
   205        format. The syntax for the format is standard `sprintf` syntax.
   206        Good documentation for the syntax can be [found here](https://golang.org/pkg/fmt/).
   207        Example to zero-prefix a count, used commonly for naming servers:
   208        `format("web-%03d", count.index + 1)`.
   209  
   210    * `formatlist(format, args, ...)` - Formats each element of a list
   211        according to the given format, similarly to `format`, and returns a list.
   212        Non-list arguments are repeated for each list element.
   213        For example, to convert a list of DNS addresses to a list of URLs, you might use:
   214        `formatlist("https://%s:%s/", aws_instance.foo.*.public_dns, var.port)`.
   215        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.
   216        Example:
   217        `formatlist("instance %v has private ip %v", aws_instance.foo.*.id, aws_instance.foo.*.private_ip)`.
   218        Passing lists with different lengths to formatlist results in an error.
   219  
   220    * `index(list, elem)` - Finds the index of a given element in a list.
   221        This function only works on flat lists.
   222        Example: `index(aws_instance.foo.*.tags.Name, "foo-test")`
   223  
   224    * `join(delim, list)` - Joins the list with the delimiter for a resultant string.
   225        This function works only on flat lists.
   226        Examples:
   227        * `join(",", aws_instance.foo.*.id)`
   228        * `join(",", var.ami_list)`
   229  
   230    * `jsonencode(item)` - Returns a JSON-encoded representation of the given
   231      item, which may be a string, list of strings, or map from string to string.
   232      Note that if the item is a string, the return value includes the double
   233      quotes.
   234  
   235    * `keys(map)` - Returns a lexically sorted list of the map keys.
   236  
   237    * `length(list)` - Returns the number of members in a given list or map, or the number of characters in a given string.
   238        * `${length(split(",", "a,b,c"))}` = 3
   239        * `${length("a,b,c")}` = 5
   240        * `${length(map("key", "val"))}` = 1
   241  
   242    * `list(items, ...)` - Returns a list consisting of the arguments to the function.
   243        This function provides a way of representing list literals in interpolation.
   244        * `${list("a", "b", "c")}` returns a list of `"a", "b", "c"`.
   245        * `${list()}` returns an empty list.
   246  
   247    * `lookup(map, key, [default])` - Performs a dynamic lookup into a map
   248        variable. The `map` parameter should be another variable, such
   249        as `var.amis`. If `key` does not exist in `map`, the interpolation will
   250        fail unless you specify a third argument, `default`, which should be a
   251        string value to return if no `key` is found in `map`. This function
   252        only works on flat maps and will return an error for maps that
   253        include nested lists or maps.
   254  
   255    * `lower(string)` - Returns a copy of the string with all Unicode letters mapped to their lower case.
   256  
   257    * `map(key, value, ...)` - Returns a map consisting of the key/value pairs
   258      specified as arguments. Every odd argument must be a string key, and every
   259      even argument must have the same type as the other values specified.
   260      Duplicate keys are not allowed. Examples:
   261      * `map("hello", "world")`
   262      * `map("us-east", list("a", "b", "c"), "us-west", list("b", "c", "d"))`
   263  
   264    * `max(float1, float2, ...)` - Returns the largest of the floats.
   265  
   266    * `merge(map1, map2, ...)` - Returns the union of 2 or more maps. The maps
   267  	are consumed in the order provided, and duplicate keys overwrite previous
   268  	entries.
   269  	* `${merge(map("a", "b"), map("c", "d"))}` returns `{"a": "b", "c": "d"}`
   270  
   271    * `min(float1, float2, ...)` - Returns the smallest of the floats.
   272  
   273    * `md5(string)` - Returns a (conventional) hexadecimal representation of the
   274      MD5 hash of the given string.
   275  
   276    * `replace(string, search, replace)` - Does a search and replace on the
   277        given string. All instances of `search` are replaced with the value
   278        of `replace`. If `search` is wrapped in forward slashes, it is treated
   279        as a regular expression. If using a regular expression, `replace`
   280        can reference subcaptures in the regular expression by using `$n` where
   281        `n` is the index or name of the subcapture. If using a regular expression,
   282        the syntax conforms to the [re2 regular expression syntax](https://code.google.com/p/re2/wiki/Syntax).
   283  
   284    * `sha1(string)` - Returns a (conventional) hexadecimal representation of the
   285      SHA-1 hash of the given string.
   286      Example: `"${sha1("${aws_vpc.default.tags.customer}-s3-bucket")}"`
   287  
   288    * `sha256(string)` - Returns a (conventional) hexadecimal representation of the
   289      SHA-256 hash of the given string.
   290      Example: `"${sha256("${aws_vpc.default.tags.customer}-s3-bucket")}"`
   291  
   292    * `signum(int)` - Returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers.
   293        This function is useful when you need to set a value for the first resource and
   294        a different value for the rest of the resources.
   295        Example: `element(split(",", var.r53_failover_policy), signum(count.index))`
   296        where the 0th index points to `PRIMARY` and 1st to `FAILOVER`
   297  
   298    * `sort(list)` - Returns a lexicographically sorted list of the strings contained in
   299        the list passed as an argument. Sort may only be used with lists which contain only
   300        strings.
   301        Examples: `sort(aws_instance.foo.*.id)`, `sort(var.list_of_strings)`
   302  
   303    * `split(delim, string)` - Splits the string previously created by `join`
   304        back into a list. This is useful for pushing lists through module
   305        outputs since they currently only support string values. Depending on the
   306        use, the string this is being performed within may need to be wrapped
   307        in brackets to indicate that the output is actually a list, e.g.
   308        `a_resource_param = ["${split(",", var.CSV_STRING)}"]`.
   309        Example: `split(",", module.amod.server_ids)`
   310  
   311    * `timestamp()` - Returns a UTC timestamp string in RFC 3339 format. This string will change with every
   312     invocation of the function, so in order to prevent diffs on every plan & apply, it must be used with the
   313     [`ignore_changes`](/docs/configuration/resources.html#ignore-changes) lifecycle attribute.
   314  
   315    * `title(string)` - Returns a copy of the string with the first characters of all the words capitalized.
   316  
   317    * `trimspace(string)` - Returns a copy of the string with all leading and trailing white spaces removed.
   318  
   319    * `upper(string)` - Returns a copy of the string with all Unicode letters mapped to their upper case.
   320  
   321    * `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.
   322  
   323    * `values(map)` - Returns a list of the map values, in the order of the keys
   324      returned by the `keys` function. This function only works on flat maps and
   325      will return an error for maps that include nested lists or maps.
   326  
   327    * `zipmap(list, list)` - Creates a map from a list of keys and a list of
   328        values. The keys must all be of type string, and the length of the lists
   329        must be the same.
   330        For example, to output a mapping of AWS IAM user names to the fingerprint
   331        of the key used to encrypt their initial password, you might use:
   332        `zipmap(aws_iam_user.users.*.name, aws_iam_user_login_profile.users.*.key_fingerprint)`.
   333  
   334  <a id="templates"></a>
   335  ## Templates
   336  
   337  Long strings can be managed using templates.
   338  [Templates](/docs/providers/template/index.html) are
   339  [data-sources](/docs/configuration/data-sources.html) defined by a
   340  filename and some variables to use during interpolation. They have a
   341  computed `rendered` attribute containing the result.
   342  
   343  A template data source looks like:
   344  
   345  ```
   346  data "template_file" "example" {
   347    template = "$${hello} $${world}!"
   348    vars {
   349      hello = "goodnight"
   350      world = "moon"
   351    }
   352  }
   353  
   354  output "rendered" {
   355    value = "${data.template_file.example.rendered}"
   356  }
   357  ```
   358  
   359  Then the rendered value would be `goodnight moon!`.
   360  
   361  You may use any of the built-in functions in your template. For more
   362  details on template usage, please see the
   363  [template_file documentation](/docs/providers/template/d/file.html).
   364  
   365  ### Using Templates with Count
   366  
   367  Here is an example that combines the capabilities of templates with the interpolation
   368  from `count` to give us a parameterized template, unique to each resource instance:
   369  
   370  ```
   371  variable "count" {
   372    default = 2
   373  }
   374  
   375  variable "hostnames" {
   376    default = {
   377      "0" = "example1.org"
   378      "1" = "example2.net"
   379    }
   380  }
   381  
   382  data "template_file" "web_init" {
   383    // here we expand multiple template_files - the same number as we have instances
   384    count    = "${var.count}"
   385    template = "${file("templates/web_init.tpl")}"
   386    vars {
   387      // that gives us access to use count.index to do the lookup
   388      hostname = "${lookup(var.hostnames, count.index)}"
   389    }
   390  }
   391  
   392  resource "aws_instance" "web" {
   393    // ...
   394    count = "${var.count}"
   395    // here we link each web instance to the proper template_file
   396    user_data = "${element(data.template_file.web_init.*.rendered, count.index)}"
   397  }
   398  ```
   399  
   400  With this, we will build a list of `template_file.web_init` data sources which we can
   401  use in combination with our list of `aws_instance.web` resources.
   402  
   403  <a id="math"></a>
   404  ## Math
   405  
   406  Simple math can be performed in interpolations:
   407  
   408  ```
   409  variable "count" {
   410    default = 2
   411  }
   412  
   413  resource "aws_instance" "web" {
   414    // ...
   415    count = "${var.count}"
   416  
   417    // tag the instance with a counter starting at 1, ie. web-001
   418    tags {
   419      Name = "${format("web-%03d", count.index + 1)}"
   420    }
   421  }
   422  ```
   423  
   424  The supported operations are:
   425  
   426  - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), and *Divide* (`/`) for **float** types
   427  - *Add* (`+`), *Subtract* (`-`), *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) for **integer** types
   428  
   429  Operator precedences is the standard mathematical order of operations:
   430  *Multiply* (`*`), *Divide* (`/`), and *Modulo* (`%`) have precedence over
   431  *Add* (`+`) and *Subtract* (`-`). Parenthesis can be used to force ordering.
   432  
   433  ```
   434  "${2 * 4 + 3 * 3}" # computes to 17
   435  "${3 * 3 + 2 * 4}" # computes to 17
   436  "${2 * (4 + 3) * 3}" # computes to 42
   437  ```
   438  
   439  You can use the [terraform console](/docs/commands/console.html) command to
   440  try the math operations.
   441  
   442  -> **Note:** Since Terraform allows hyphens in resource and variable names,
   443  it's best to use spaces between math operators to prevent confusion or unexpected
   444  behavior. For example, `${var.instance-count - 1}` will subtract **1** from the
   445  `instance-count` variable value, while `${var.instance-count-1}` will interpolate
   446  the `instance-count-1` variable value.