templatefile Функция

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

templatefile(path, vars)

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

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

Строки в языке OpenTofu представляют собой последовательности символов Юникода, поэтому эта функция интерпретирует содержимое файла как текст в кодировке UTF-8 и возвращает соответствующие символы Юникода. Если файл содержит недопустимые последовательности 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 принимает строку и отображает ее как шаблон, используя предоставленный набор переменных шаблона.