template

template#

Модуль ansible.builtin.template обрабатывает шаблон в формате Jinja2 и создает на его основе файл, который размещает на управляемых узлах по указанному пути.

Особенности работы#

Особенности использования модуля ansible.builtin.template:

  • В шаблоне могут быть использованы дополнительные переменные.

    Некоторые настройки могут быть заданы в секции [default] конфигурационного файла ansible.cfg:

    ansible_managed – строка с характеристиками шаблона:

    • template_destpath – путь к шаблону на управляемом узле;

    • template_fullpath – абсолютный путь к шаблону;

    • template_host – название узла, на котором находится файл шаблона;

    • template_path – путь к шаблону на управляющем узле;

    • template_run_date – время обработки шаблона;

    • template_uid – идентификатор пользователя-владельца (UID).

  • Для настройки узлов под управлением ОС Windows предпочтительнее использовать модуль ansible.windows.win_template, в котором параметр newline_sequence имеет значение по умолчанию "\\r\\n".

  • Настройка jinja2_native не имеет эффекта.

    Модуль ansible.builtin.template предназначен для генерации только текстовых файлов. Чтобы использовать не-текстовые типы данных, используйте параметр jinja2_native расширения подстановки ansible.builtin.template.

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

  • По умолчанию настройка Jinja trim_blocks включена (True).

  • Настройки Jinja2 можно переопределить, добавив в начало файла специальным образом оформленный заголовок. Например, следующая директива заменяет последовательности {{ и }}, обрамляющие переменные, на [% и %] (может быть полезным, если в тексте встречается много фигурных скобок), а также запрещает убирать символ переноса строки после первой строки условного выражения:

    #jinja2:variable_start_string:'[%', variable_end_string: '%]', trim_blocks: False

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

  • Маркеры последовательности байтов (Byte Order Marks, BOM) могут быть причиной появления пустых строк в сформированном файле. Для поиска BOM используйте эти команды:

    od -a -t x1 -N 16 <file>

    Format-Hex <file> -Count 16

Параметры#

Модуль принимает следующие параметры:

attributes, attr#

Изменение атрибутов целевого файла после размещения на управляемом узле. Чтобы узнать о поддерживаемых атрибутах, обратитесь к руководству chattr в целевой системе:

man chattr

Значение параметра должно представлять собой строку, содержащую атрибуты в порядке, принятом в выводе lsattr на целевой системе. Строка также может включать один из следующих операторов:

  • = – установить строго указанный набор атрибутов;

  • + – добавить указанные атрибуты к существующим;

  • - – удалить указанные атрибуты из существующих.

Если оператор не указан, используется оператор =. Это значит, что будут сброшены все ранее установленные атрибуты, кроме явно указанных в строке.

Пример

Пусть файл имеет атрибуты rw-r--r--. Эта запись означает следующее:

  • пользователь-владелец имеет права на чтение файла и запись в него;

  • группа-владелец имеет права на чтение файла;

  • прочие пользователи и группы имеют права на чтение файла.

Пусть значение attributes задано следующим образом:

attributes: 'u=rwx,g=r'

Применение этих атрибутов изменит режим доступа на rwxr-----, то есть:

  • пользователь-владелец сможет читать и запускать файл, а также писать в него;

  • группа-владелец сможет только читать файл;

  • прочие пользователи и группы потеряют доступ к файлу.

backup#

Создание резервной копии целевого файла перед заменой.

Возможные значения:

  • false – не создавать резервную копию;

  • true – создавать резервную копию.

Значение по умолчанию: false.

block_end_string#

Строка, обозначающая конец блока Jinja2.

Значение по умолчанию: "%}".

blosk_start_string#

Строка, обозначающая начало блока Jinja2.

Значение по умолчанию: "{%".

comment_end_string#

Строка, обозначающая конец комментария.

comment_start_string#

Строка, обозначающая начало комментария.

dest#

Обязательный параметр.

Абсолютный путь на управляемом узле, куда будет скопирован результат обработки шаблона.

follow#

Порядок обработки символических ссылок на управляемых узлах.

Возможные значения:

  • false – замена ссылки на файл;

  • true – переход по ссылке и замена содержимого файла, на который она указывает.

Значение по умолчанию: false.

force#

Необходимость перезаписи файла на управляемых узлах.

Возможные значения:

  • false – скопировать файл только если он отсутствует по указанному пути;

  • true – заменить файл, если его содержимое отличается.

Значение по умолчанию: true.

group#

Название группы, которой будет принадлежать файл на управляемом узле. Параметр работает как утилита chown.

Если параметр не указан, используется основная (primary) группа пользователя, от имени которого выполняется задача. При выполнении задачи с привилегиями root предыдущий владелец будет сохранен, если файл уже существует.

lstrip_blocks#

Способ обработки пробелов и символов табуляции, стоящих в начале строк.

Возможные значения:

  • true – удалить;

  • false – ничего не делать.

Значение по умолчанию: false.

mode#

Режим доступа к целевому файлу.

Значения могут быть следующих типов:

  • Восьмеричное число, например, 0644 или 0755. Обязательно указывать с ведущим нулем или в кавычках:

    • 0644;

    • '644'.

    Если указать значение без кавычек или ведущего нуля, Ansible обработает его как десятичное число, что приведет к непредсказуемому результату.

  • Строковое значение, например, u=rw,g=r,o=r или u+rwx,g+rx,o=r.

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

Поведение по умолчанию:

  • если файл на управляемом узле уже существует, режим доступа сохраняется;

  • если файл создается заново и параметр mode не задан, режим доступа определяется системным значением umask на управляемом узле.

Предупреждение

Рекомендуется всегда явно задавать параметр mode, чтобы избежать назначения небезопасных или непредсказуемых режимов доступа. См. описание уязвимости CVE-2020-1736.

При рекурсивном копировании каталогов для задания прав доступа к ним используйте параметр directory_mode.

newline_sequence#

Последовательность символов, обозначающая переход на новую строку.

Возможные значения:

  • "\\n";

  • "\\r";

  • "\\r\\n".

Значение по умолчанию: "\\n".

output_encoding#

Кодировка, в которой следует сохранить файл с результатом обработки шаблона.

Примечание

Файл шаблона должен иметь кодировку UTF-8.

Возможные значения: любая из кодировок, поддерживаемых Python.

Значение по умолчанию: utf-8.

owner#

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

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

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

selevel#

Уровень копируемого файла в контексте безопасности SELinux.

Представляет собой MLS/MCS-атрибут, также известный как range, который задает уровень доступа к объекту в системе с включенным SELinux.

Если установлено значение _default, будет использован уровень по умолчанию из политики SELinux для данного объекта (если такая политика определена).

serole#

Роль копируемого файла в контексте безопасности SELinux.

Если установлено значение _default, будет использована роль по умолчанию из политики SELinux для данного объекта (если такая политика определена).

setype#

Тип копируемого файла в контексте безопасности SELinux.

Если установлено значение _default, будет использован тип по умолчанию из политики SELinux для данного объекта (если такая политика определен).

seuser#

Пользователь копируемого файла в контексте безопасности SELinux.

Если значение не указано, используется системная политика определения пользователя.

Если установлено значение _default, будет использован пользователь по умолчанию из политики SELinux для данного объекта (если такая политика определена).

src#

Обязательный параметр.

Абсолютный или относительный путь к файлу шаблона Jinja2 на управляющем узле.

trim_blocks#

Порядок обработки перехода на новую строку в блоках.

Возможные значения:

  • false – ничего не делать;

  • true – удалить первый в блоке переход на новую строку.

Значение по умолчанию: false.

unsafe_writes#

Использование атомарной записи для предотвращения повреждения данных или несогласованного чтения целевого файлового объекта.

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

На некоторых системах (например, при работе с томами Docker) атомарные операции могут быть недоступны или вызывать ошибки. В этом случае установка значения true позволяет Ansible выполнить небезопасную (неатомарную) запись напрямую в целевой файл.

Предупреждение

Небезопасная запись может привести к состоянию гонки и повреждению данных.

Возможные значения:

  • false – атомарные операции обязательны. При их невозможности задача завершится с ошибкой.

  • true – если атомарная запись невозможна, будет использован небезопасный способ записи.

Значение по умолчанию: false.

validate#

Шаблон команды для проверки корректности файла.

Путь к временному файлу, используемому для проверки, подставляется автоматически вместо последовательности символов %s, которая должна присутствовать в шаблоне. Если проверка проходит без ошибок, временный файл заменяет собой файл, указанный в dest. В противном случае задача завершается с ошибкой.

Команда проверки запускается безопасно, поэтому расширения оболочки и конвейеры (pipes) не будут работать.

variable_end_string#

Последовательность символов, обозначающая конец выражения вывода значения.

Значение по умолчанию: "}}".

variable_start_string#

Последовательность символов, обозначающая начало выражения вывода значения.

Значение по умолчанию: "{{".

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут

Описание

action

Модуль имеет соответствующее расширение действий (action plugin). Это означает, что часть работы (подготовка содержимого файла с помощью Jinja) выполняется на управляющем узле.

async

Модуль не поддерживает асинхронное выполнение.

bypass_host_loop

Модуль не поддерживает глобальное выполнение задачи.

check_mode

Модуль работает в режиме проверки (check_mode) в полном объеме. Режим проверки позволяет узнать, что произойдет при выполнении указанных действий с шаблоном и целевым файлом.

diff_mode

Модуль поддерживает режим сравнения (diff_mode) в полном объеме и возвращает подробную информацию о сделанных изменениях.

platfom

Модуль поддерживает только POSIX-совместимые ОС.

safe_file_operations

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

vault

Модуль поддерживает автоматическую расшифровку исходных файлов с использованием хранилища секретов.

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.template.

  • checksum – контрольная сумма SHA1 файла, сформированного на основе шаблона.

    Условия: всегда.

  • dest – путь к целевому файлу, соответствует значению, указанному в значении параметра dest.

    Условия: успешное выполнение задачи.

  • gid – идентификатор группы-владельца (GID) файла на управляемом узле.

    Условия: успешное выполнение задачи.

  • group – название группы-владельца файла на управляемом узле.

    Условия: успешное выполнение задачи.

  • md5sum – контрольная сумма файла, сформированного на основе шаблона.

    Условия: изменение файла на управляемом узле.

  • mode – режим доступа к файлу в восьмеричной системе счисления.

    Условия: успешное выполнение задачи.

  • owner – название учетной записи пользователя-владельца файла на управляемом узле.

    Условия: успешное выполнение задачи.

  • size – размер файла или каталога в байтах.

    Условия: успешное выполнение задачи.

  • src – путь к временному файлу, сформированному на основе шаблона.

    Условия: изменение файла на управляемом узле.

  • uid – идентификатор пользователя-владельца (UID) файла на управляемом узле.

    Условия: успешное выполнение задачи.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Простая обработка шаблона#

Следующий пример описывает создание конфигурационного файла /etc/nginx/nginx.conf на основе шаблона templates/nginx.conf.j2:

---
- name: Set NGINX settings
  ansible.builtin.template:
    src: ./templates/nginx.conf.js
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'

Проверка файла перед заменой#

Следующий пример описывает проверку конфигурационного файла DNS-сервера Bind9 с помощью утилиты named-checkconf. Если проверка не будет успешной, содержимое файла /etc/bind/named.conf на управляемых узлах не изменится.

---
- name: Create named.conf
  ansible.builtin.template:
    src: ./templates/named.conf.j2
    dest: /etc/bind/named.conf
    validate: "named-checkconf %s"

Создание резервной копии#

Следующий пример описывает создание резервной копии целевого файла перед заменой:

---
- name: Safe update site config
  ansible.builtin.template:
    src: ./site.j2
    dest: /etc/nginx/sites-enabled/site.conf
    owner: root
    group: root
    mode: '0644'
    validate: "nginx -t -c %s"
    backup: yes