github.com/hugorut/terraform@v1.1.3/website/docs/language/functions/templatefile.mdx (about)

     1  ---
     2  page_title: templatefile - Functions - Configuration Language
     3  description: |-
     4    The templatefile function reads the file at the given path and renders its
     5    content as a template.
     6  ---
     7  
     8  # `templatefile` Function
     9  
    10  `templatefile` reads the file at the given path and renders its content
    11  as a template using a supplied set of template variables.
    12  
    13  ```hcl
    14  templatefile(path, vars)
    15  ```
    16  
    17  The template syntax is the same as for
    18  [string templates](/language/expressions/strings#string-templates)
    19  in the main Terraform language, including interpolation sequences delimited with
    20  `${` ... `}`. This function just allows longer template sequences to be factored
    21  out into a separate file for readability.
    22  
    23  The "vars" argument must be a map. Within the template file, each of the keys
    24  in the map is available as a variable for interpolation. The template may
    25  also use any other function available in the Terraform language, except that
    26  recursive calls to `templatefile` are not permitted. Variable names must
    27  each start with a letter, followed by zero or more letters, digits, or
    28  underscores.
    29  
    30  Strings in the Terraform language are sequences of Unicode characters, so
    31  this function will interpret the file contents as UTF-8 encoded text and
    32  return the resulting Unicode characters. If the file contains invalid UTF-8
    33  sequences then this function will produce an error.
    34  
    35  This function can be used only with files that already exist on disk at the
    36  beginning of a Terraform run. Functions do not participate in the dependency
    37  graph, so this function cannot be used with files that are generated
    38  dynamically during a Terraform operation.
    39  
    40  `*.tftpl` is the recommended naming pattern to use for your template files.
    41  Terraform will not prevent you from using other names, but following this
    42  convention will help your editor understand the content and likely provide
    43  better editing experience as a result.
    44  
    45  ## Examples
    46  
    47  ### Lists
    48  
    49  Given a template file `backends.tftpl` with the following content:
    50  
    51  ```
    52  %{ for addr in ip_addrs ~}
    53  backend ${addr}:${port}
    54  %{ endfor ~}
    55  ```
    56  
    57  The `templatefile` function renders the template:
    58  
    59  ```
    60  > templatefile("${path.module}/backends.tftpl", { port = 8080, ip_addrs = ["10.0.0.1", "10.0.0.2"] })
    61  backend 10.0.0.1:8080
    62  backend 10.0.0.2:8080
    63  
    64  ```
    65  
    66  ### Maps
    67  
    68  Given a template file `config.tftpl` with the following content:
    69  
    70  ```
    71  %{ for config_key, config_value in config }
    72  set ${config_key} = ${config_value}
    73  %{ endfor ~}
    74  ```
    75  
    76  The `templatefile` function renders the template:
    77  
    78  ```
    79  > templatefile(
    80                 "${path.module}/config.tftpl",
    81                 {
    82                   config = {
    83                     "x"   = "y"
    84                     "foo" = "bar"
    85                     "key" = "value"
    86                   }
    87                 }
    88                )
    89  set foo = bar
    90  set key = value
    91  set x = y
    92  ```
    93  
    94  ### Generating JSON or YAML from a template
    95  
    96  If the string you want to generate will be in JSON or YAML syntax, it's
    97  often tricky and tedious to write a template that will generate valid JSON or
    98  YAML that will be interpreted correctly when using lots of individual
    99  interpolation sequences and directives.
   100  
   101  Instead, you can write a template that consists only of a single interpolated
   102  call to either [`jsonencode`](/language/functions/jsonencode) or
   103  [`yamlencode`](/language/functions/yamlencode), specifying the value to encode using
   104  [normal Terraform expression syntax](/language/expressions)
   105  as in the following examples:
   106  
   107  ```
   108  ${jsonencode({
   109    "backends": [for addr in ip_addrs : "${addr}:${port}"],
   110  })}
   111  ```
   112  
   113  ```
   114  ${yamlencode({
   115    "backends": [for addr in ip_addrs : "${addr}:${port}"],
   116  })}
   117  ```
   118  
   119  Given the same input as the `backends.tftpl` example in the previous section,
   120  this will produce a valid JSON or YAML representation of the given data
   121  structure, without the need to manually handle escaping or delimiters.
   122  In the latest examples above, the repetition based on elements of `ip_addrs` is
   123  achieved by using a
   124  [`for` expression](/language/expressions/for)
   125  rather than by using
   126  [template directives](/language/expressions/strings#directives).
   127  
   128  ```json
   129  {"backends":["10.0.0.1:8080","10.0.0.2:8080"]}
   130  ```
   131  
   132  If the resulting template is small, you can choose instead to write
   133  `jsonencode` or `yamlencode` calls inline in your main configuration files, and
   134  avoid creating separate template files at all:
   135  
   136  ```hcl
   137  locals {
   138    backend_config_json = jsonencode({
   139      "backends": [for addr in ip_addrs : "${addr}:${port}"],
   140    })
   141  }
   142  ```
   143  
   144  For more information, see the main documentation for
   145  [`jsonencode`](/language/functions/jsonencode) and [`yamlencode`](/language/functions/yamlencode).
   146  
   147  ## Related Functions
   148  
   149  * [`file`](/language/functions/file) reads a file from disk and returns its literal contents
   150    without any template interpretation.