ansible.builtin.template – Шаблон файла на целевом узле

Примечание

Этот модуль является частью ansible-base и включён во все установки Ansible. В большинстве случаев можно использовать короткое имя модуля template, даже не указывая ключевое слово collections:. Несмотря на это, мы рекомендуем использовать полное имя класса (FQCN) для лёгкой ссылки на документацию модуля и для избежания конфликтов с другими коллекциями, которые могут иметь такое же имя модуля.

Описание
Параметры
Примечания
См. также
Примеры

Описание

Шаблоны обрабатываются с помощью языка шаблонов Jinja2.
Документацию по форматированию шаблонов можно найти в Документации по шаблонам.
Дополнительные переменные, перечисленные ниже, могут использоваться в шаблонах.
ansible_managed (настраивается через раздел defaults в ansible.cfg) содержит строку, которая может быть использована для описания имени шаблона, узла, времени последнего изменения файла шаблона и идентификатора владельца.
template_host содержит имя узла машины, для которой создаётся шаблон.
template_uid — числовой идентификатор пользователя-владельца.
template_path — путь к шаблону.
template_fullpath — абсолютный путь к шаблону.
template_destpath — путь к шаблону на удалённой системе (добавлено в версии 2.8).
template_run_date — дата, когда шаблон был сгенерирован.

Примечание

У этого модуля есть соответствующий плагин действий.

Параметры

Параметр	Варианты/Значения по умолчанию	Комментарии
attributes строка добавлено в 2.3 ansible.builtin		Атрибуты, которые должны быть у полученного файла или директории. Чтобы узнать поддерживаемые флаги, обратитесь к странице справки для chattr на целевой системе. Эта строка должна содержать атрибуты в том же порядке, что и в выводе lsattr. Оператор `=` используется по умолчанию, в противном случае необходимо включить операторы `+` или `-` в строку. псевдонимы: attr
backup логическое значение	Варианты: нет ← да	Создать резервную копию файла, включая информацию о времени, чтобы вы могли восстановить исходный файл, если вы неправильно его перезаписали.
block_end_string строка добавлено в 2.4 ansible.builtin	Значение по умолчанию: "%}"	Строка, обозначающая конец блока.
block_start_string строка добавлено в 2.4 ansible.builtin	Значение по умолчанию: "{%"	Строка, обозначающая начало блока.
dest путь / обязательно		Место для рендеринга шаблона на удалённой машине.
follow логическое значение добавлено в 2.4 ansible.builtin	Варианты: нет ← да	Определить, следует ли следовать символическим ссылкам. При установке в `yes` символические ссылки будут следовать, если они существуют. При установке в `no` символические ссылки не будут следовать. До Ansible 2.4 это было жёстко задано как `yes`.
force логическое значение	Варианты: нет да ←	Определить, когда файл передаётся, если файл назначения уже существует. При установке в `yes`, замените удалённый файл, если содержимое отличается от исходного. При установке в `no`, файл будет передан только в том случае, если файл назначения не существует.
group строка		Имя группы, которая должна владеть файлом/директорией, как это подаётся в chown.
lstrip_blocks логическое значение добавлено в 2.6 ansible.builtin	Варианты: нет ← да	Определить, когда нужно удалять ведущие пробелы и табуляции. При установке в `yes` ведущие пробелы и табуляции удаляются из начала строки блока. Эта функциональность требует Jinja 2.7 или новее.
mode сырой		Разрешения, которые должны быть у полученного файла или директории. Для тех, кто знаком с /usr/bin/chmod, помните, что режимы фактически являются восьмеричными числами. Вы должны либо добавить ведущую ноль, чтобы парсер YAML Ansible знал, что это восьмеричное число (например, `0644` или `01777`) или заключить его в кавычки (например, `'644'` или `'1777'`) так, чтобы Ansible получил строку и смог выполнить собственное преобразование из строки в число. Передача Ansible числа без соблюдения одного из этих правил приведёт к десятичному числу, что приведёт к непредвиденным результатам. Начиная с Ansible 1.8, режим может быть указан как символический режим (например, `u+rwx` или `u=rw,g=r,o=r`). Если `mode` не указано и целевой файл не существует, будет использоваться значение по умолчанию `umask` на системе при установке режима для вновь созданного файла. Если `mode` не указано и целевой файл существует, будет использован режим существующего файла. Указание `mode` — лучший способ обеспечить правильные разрешения файлов. Смотрите CVE-2020-1736 для получения дополнительной информации.
newline_sequence строка добавлено в 2.4 ansible.builtin	Варианты: \n ← \r \r\n	Указать последовательность символов новой строки для использования при шаблонизации файлов.
output_encoding строка добавлено в 2.7 ansible.builtin	Значение по умолчанию: "utf-8"	Переопределяет кодировку, используемую для записи файла шаблона, определённого `dest`. По умолчанию используется `utf-8`, но можно использовать любую кодировку, поддерживаемую python. Исходный файл шаблона должен всегда быть закодирован в `utf-8`, для однородности.
owner строка		Имя пользователя, который должен владеть файлом/директорией, как это подаётся в chown.
selevel строка		Часть уровня SELinux контекста файла. Это атрибут MLS/MCS, иногда известный как `range`. При установке в `_default`, будет использоваться часть политики `level`, если она доступна.
serole строка		Часть роли SELinux контекста файла. При установке в `_default`, будет использоваться часть политики `role`, если она доступна.
setype строка		Часть типа SELinux контекста файла. При установке в `_default`, будет использоваться часть политики `type`, если она доступна.
seuser строка		Часть пользователя SELinux контекста файла. По умолчанию используется политика `system`, где это применимо. При установке в `_default`, будет использоваться часть политики `user`, если она доступна.
src путь / обязательно		Путь к файлу шаблона Jinja2 на контроллере Ansible. Это может быть относительный или абсолютный путь. Файл должен быть закодирован в `utf-8`, но output_encoding может использоваться для управления кодировкой выходного шаблона.
trim_blocks логическое значение добавлено в 2.4 ansible.builtin	Варианты: нет да ←	Определить, когда нужно удалять символы новой строки из блоков. При установке в `yes` первая новая строка после блока удаляется (блок, а не тег переменной!).
unsafe_writes логическое значение добавлено в 2.2 ansible.builtin	Варианты: нет ← да	Влияет на использование атомарной операции для предотвращения повреждения данных или несогласованного чтения из целевого файла. По умолчанию этот модуль использует атомарные операции для предотвращения повреждения данных или несогласованного чтения из целевых файлов, но иногда системы настроены или просто неисправны таким образом, что это предотвращает это. Одним из примеров являются файлы, смонтированные в Docker, которые не могут обновляться атомарно изнутри контейнера и могут быть записаны только небезопасным способом. Этот параметр позволяет Ansible переключаться на небезопасные методы обновления файлов при сбое атомарных операций (тем не менее, он не заставляет Ansible выполнять небезопасные записи). ВАЖНО! Небезопасные записи подвержены гонкам и могут привести к повреждению данных.
validate строка		Команда валидации, которая должна быть выполнена перед копированием на место. Путь к файлу для валидации передаётся через '%s', который должен быть присутствовать, как в примерах ниже. Команда передаётся безопасно, так что такие функции оболочки, как расширение и конвейеры, не будут работать.
variable_end_string строка добавлено в 2.4 ansible.builtin	Значение по умолчанию: "}}"	Строка, обозначающая конец оператора вывода.
variable_start_string строка добавлено в 2.4 ansible.builtin	Значение по умолчанию: "{{"	Строка, обозначающая начало оператора вывода.

Примечания

Примечание

Для Windows можно использовать ansible.windows.win_template, который по умолчанию использует ‘\r\n’ как newline_sequence.
Включение строки с датой в шаблоне приведёт к тому, что шаблон будет помечен как «изменённый» каждый раз.
Начиная с Ansible 0.9, шаблоны загружаются с trim_blocks=True.
Также можно переопределить параметры Jinja2, добавив специальный заголовок в файл шаблона, например #jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False, что изменяет маркеры интерполяции переменных на [% var %] вместо {{ var }}. Это лучший способ предотвратить оценку того, что выглядит как Jinja2, но им не должно быть.
Использование raw/endraw в Jinja2 не будет работать так, как ожидается, потому что шаблоны в Ansible рекурсивно оцениваются.
Чтобы найти символы слева направо в файлах, используйте Format-Hex <file> -Count 16 в Windows и od -a -t x1 -N 16 <file> в Linux.

См. также

ansible.builtin.copy: Официальная документация модуля ansible.builtin.copy.
ansible.windows.win_copy: Официальная документация модуля ansible.windows.win_copy.
ansible.windows.win_template: Официальная документация модуля ansible.windows.win_template.

Примеры

- name: Template a file to /etc/file.conf
  ansible.builtin.template:
    src: /mytemplates/foo.j2
    dest: /etc/file.conf
    owner: bin
    group: wheel
    mode: '0644'

- name: Template a file, using symbolic modes (equivalent to 0644)
  ansible.builtin.template:
    src: /mytemplates/foo.j2
    dest: /etc/file.conf
    owner: bin
    group: wheel
    mode: u=rw,g=r,o=r

- name: Copy a version of named.conf that is dependent on the OS. setype obtained by doing ls -Z /etc/named.conf on original file
  ansible.builtin.template:
    src: named.conf_{{ ansible_os_family }}.j2
    dest: /etc/named.conf
    group: named
    setype: named_conf_t
    mode: 0640

- name: Create a DOS-style text file from a template
  ansible.builtin.template:
    src: config.ini.j2
    dest: /share/windows/config.ini
    newline_sequence: '\r\n'

- name: Copy a new sudoers file into place, after passing validation with visudo
  ansible.builtin.template:
    src: /mine/sudoers
    dest: /etc/sudoers
    validate: /usr/sbin/visudo -cf %s

- name: Update sshd configuration safely, avoid locking yourself out
  ansible.builtin.template:
    src: etc/ssh/sshd_config.j2
    dest: /etc/ssh/sshd_config
    owner: root
    group: root
    mode: '0600'
    validate: /usr/sbin/sshd -t -f %s
    backup: yes

Авторы

Команда Ansible Core
Майкл ДеХан

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/builtin/template_module.html