templatefile Функция

templatefile считывает файл по указанному пути и отображает его содержимое как шаблон, используя заданный набор переменных шаблона.

templatefile(path, vars)

Синтаксис шаблонов такой же, как у строковых шаблонов в основном языке OpenTofu, включая последовательности интерполяции, ограниченные ${ ... }. Эта функция лишь позволяет выносить длинные последовательности шаблонов в отдельный файл для удобства чтения.

Аргумент "vars" должен быть объектом. В файле шаблона каждый ключ карты доступен как переменная для интерполяции. Шаблон также может использовать любую другую функцию, доступную в языке OpenTofu. Имена переменных должны начинаться с буквы, за которой может следовать ноль или более букв, цифр или символов подчёркивания.

Строки в языке OpenTofu представляют собой последовательности символов Unicode, поэтому эта функция интерпретирует содержимое файла как текст в кодировке UTF-8 и возвращает соответствующие символы Unicode. Если файл содержит недопустимые последовательности UTF-8, эта функция выдаст ошибку.

Эту функцию можно использовать только с файлами, которые уже существуют на диске в начале выполнения OpenTofu. Функции не участвуют в графе зависимостей, поэтому эту функцию нельзя использовать с файлами, которые создаются динамически во время выполнения операции OpenTofu.

*.tftpl — рекомендуемый шаблон именования файлов шаблонов. OpenTofu не запрещает использовать другие имена, но соблюдение этого соглашения поможет редактору распознать содержимое и, вероятно, обеспечит более удобное редактирование.

Рекурсия​

При использовании рекурсии с templatefile следует учитывать несколько ограничений.

Глубина рекурсивных вызовов templatefile ограничена (по умолчанию — 1024). Это позволяет предотвратить сбои из-за непреднамеренных бесконечных рекурсивных вызовов и снизить вероятность сбоев из-за нехватки памяти.

Поскольку хвостовая рекурсия не поддерживается, все документы в стеке вызовов должны быть загружены в память до того, как начнётся раскрутка стека. На большинстве современных систем и конфигураций это, вероятно, не станет проблемой, но об этом стоит помнить.

Если во время выполнения будет достигнута максимальная глубина рекурсии, появится краткое сообщение об ошибке с описанием первых нескольких шагов стека вызовов, которое поможет диагностировать проблему. Если вам нужен полный стек вызовов, задайте TF_LOG=debug, чтобы вывести в консоль весь стек вызовов templatefile.

Если конфигурации требуется большая максимальная глубина рекурсии, можно переопределить значение по умолчанию с помощью переменной окружения TF_TEMPLATE_RECURSION_DEPTH. Это не рекомендуется и предусмотрено только как крайняя мера. Кроме того, если задать значение меньше 1024, это может вызвать проблемы с модулями, использующими функцию templatefile.

Примеры​

Списки​

Пусть файл шаблона backends.tftpl содержит следующее:

%{ for addr in ip_addrs ~}
backend ${addr}:${port}
%{ endfor ~}

Функция templatefile отображает шаблон:

> templatefile("${path.module}/backends.tftpl", { port = 8080, ip_addrs = ["10.0.0.1", "10.0.0.2"] })
backend 10.0.0.1:8080
backend 10.0.0.2:8080

Карты​

Пусть файл шаблона config.tftpl содержит следующее:

%{ for config_key, config_value in config }
set ${config_key} = ${config_value}
%{ endfor ~}

Функция templatefile отображает шаблон:

> templatefile(
               "${path.module}/config.tftpl",
               {
                 config = {
                   "x"   = "y"
                   "foo" = "bar"
                   "key" = "value"
                 }
               }
              )
set foo = bar
set key = value
set x = y

Создание JSON или YAML из шаблона​

Если строка, которую вы хотите создать, должна быть в формате JSON или YAML, часто бывает сложно и утомительно написать шаблон, который создаёт корректный JSON или YAML, правильно интерпретируемый при использовании множества отдельных последовательностей интерполяции и директив.

Вместо этого можно написать шаблон, состоящий только из одного вызова интерполяции — либо jsonencode, либо yamlencode, указав кодируемое значение с помощью обычного синтаксиса выражений OpenTofu, как в следующих примерах:

${jsonencode({
  "backends": [for addr in ip_addrs : "${addr}:${port}"],
})}

${yamlencode({
  "backends": [for addr in ip_addrs : "${addr}:${port}"],
})}

При тех же входных данных, что и в примере backends.tftpl из предыдущего раздела, будет создано корректное представление заданной структуры данных в формате JSON или YAML без необходимости вручную обрабатывать экранирование или разделители. В последних примерах выше повторение на основе элементов ip_addrs реализовано с помощью выражения for, а не директив шаблонов.

{"backends":["10.0.0.1:8080","10.0.0.2:8080"]}

Если получившийся шаблон небольшой, вместо этого можно использовать вызовы jsonencode или yamlencode непосредственно в основных файлах конфигурации и вовсе не создавать отдельные файлы шаблонов:

locals {
  backend_config_json = jsonencode({
    "backends": [for addr in ip_addrs : "${addr}:${port}"],
  })
}

Дополнительные сведения см. в основной документации по функциям jsonencode и yamlencode.

Связанные функции​

• file считывает файл с диска и возвращает его буквальное содержимое без обработки шаблонов.
• templatestring принимает строку и отображает её как шаблон, используя заданный набор переменных шаблона.