github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/configuration/functions/templatefile.html.md (about)

     1  ---
     2  layout: "functions"
     3  page_title: "templatefile - Functions - Configuration Language"
     4  sidebar_current: "docs-funcs-file-templatefile"
     5  description: |-
     6    The templatefile function reads the file at the given path and renders its
     7    content as a template.
     8  ---
     9  
    10  # `templatefile` Function
    11  
    12  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    13  earlier, see
    14  [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
    15  
    16  `templatefile` reads the file at the given path and renders its content
    17  as a template using a supplied set of template variables.
    18  
    19  ```hcl
    20  templatefile(path, vars)
    21  ```
    22  
    23  The template syntax is the same as for
    24  [string templates](../expressions.html#string-templates) in the main Terraform
    25  language, including interpolation sequences delimited with `${` ... `}`.
    26  This function just allows longer template sequences to be factored out
    27  into a separate file for readability.
    28  
    29  The "vars" argument must be a map. Within the template file, each of the keys
    30  in the map is available as a variable for interpolation. The template may
    31  also use any other function available in the Terraform language, except that
    32  recursive calls to `templatefile` are not permitted.
    33  
    34  Strings in the Terraform language are sequences of Unicode characters, so
    35  this function will interpret the file contents as UTF-8 encoded text and
    36  return the resulting Unicode characters. If the file contains invalid UTF-8
    37  sequences then this function will produce an error.
    38  
    39  This function can be used only with files that already exist on disk at the
    40  beginning of a Terraform run. Functions do not participate in the dependency
    41  graph, so this function cannot be used with files that are generated
    42  dynamically during a Terraform operation. We do not recommend using dynamic
    43  templates in Terraform configurations, but in rare situations where this is
    44  necessary you can use
    45  [the `template_file` data source](/docs/providers/template/d/file.html)
    46  to render templates while respecting resource dependencies.
    47  
    48  ## Examples
    49  
    50  Given a template file `backends.tmpl` with the following content:
    51  
    52  ```
    53  %{ for addr in ip_addrs ~}
    54  backend ${addr}:${port}
    55  %{ endfor ~}
    56  ```
    57  
    58  The `templatefile` function renders the template:
    59  
    60  ```
    61  > templatefile("${path.module}/backends.tmpl", { port = 8080, ip_addrs = ["10.0.0.1", "10.0.0.2"] })
    62  backend 10.0.0.1:8080
    63  backend 10.0.0.2:8080
    64  
    65  ```
    66  
    67  ### Generating JSON or YAML from a template
    68  
    69  If the string you want to generate will be in JSON or YAML syntax, it's
    70  often tricky and tedious to write a template that will generate valid JSON or
    71  YAML that will be interpreted correctly when using lots of individual
    72  interpolation sequences and directives.
    73  
    74  Instead, you can write a template that consists only of a single interpolated
    75  call to either [`jsonencode`](./jsonencode.html) or
    76  [`yamlencode`](./yamlencode.html), specifying the value to encode using
    77  [normal Terraform expression syntax](/docs/configuration/expressions.html)
    78  as in the following examples:
    79  
    80  ```
    81  ${jsonencode({
    82    "backends": [for addr in ip_addrs : "${addr}:${port}"],
    83  })}
    84  ```
    85  
    86  ```
    87  ${yamlencode({
    88    "backends": [for addr in ip_addrs : "${addr}:${port}"],
    89  })}
    90  ```
    91  
    92  Given the same input as the `backends.tmpl` example in the previous section,
    93  this will produce a valid JSON or YAML representation of the given data
    94  structure, without the need to manually handle escaping or delimiters.
    95  In the latest examples above, the repetition based on elements of `ip_addrs` is
    96  achieved by using a
    97  [`for` expression](/docs/configuration/expressions.html#for-expressions)
    98  rather than by using
    99  [template directives](/docs/configuration/expressions.html#directives).
   100  
   101  ```json
   102  {"backends":["10.0.0.1:8080","10.0.0.2:8080"]}
   103  ```
   104  
   105  If the resulting template is small, you can choose instead to write
   106  `jsonencode` or `yamlencode` calls inline in your main configuration files, and
   107  avoid creating separate template files at all:
   108  
   109  ```hcl
   110  locals {
   111    backend_config_json = jsonencode({
   112      "backends": [for addr in ip_addrs : "${addr}:${port}"],
   113    })
   114  }
   115  ```
   116  
   117  For more information, see the main documentation for
   118  [`jsonencode`](./jsonencode.html) and [`yamlencode`](./yamlencode.html).
   119  
   120  ## Related Functions
   121  
   122  * [`file`](./file.html) reads a file from disk and returns its literal contents
   123    without any template interpretation.