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 принимает строку и отображает её как шаблон, используя предоставленный набор переменных шаблона.