assemble

assemble#

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

Файлы, из которых собирается целевой файл, называются фрагментами.

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

  • загрузчик GRUB2 загружает настройки из конфигурационного файла /etc/default/grub и файлов в каталоге /etc/default/grub.d/;

  • настройки ядра Linux загружаются из конфигурационного /etc/sysctl.conf и файлов с расширением .conf в каталоге /etc/sysctl.d/.

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

Модуль ansible.builtin.assemble имеет следующие особенности:

  • каталог с фрагментами может быть размещен и на управляющем узле, и на управляемых;

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

Параметры#

attributes, attr#

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

man chattr

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

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

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

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

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

backup#

Создание резервной копии файла, указанного в dest, включая метку времени.

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

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

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

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

decrypt#

Управление автоматической расшифровкой фрагментов с использованием хранилища секретов.

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

  • false – не расшифровывать;

  • true – расшифровывать.

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

delimiter#

Строка-разделитель, позволяющая в собранном файле определить начало и конец использованных фрагментов.

dest#

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

Путь, по которому необходимо разместить собранный файл.

group#

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

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

ignore_hidden#

Обработка фрагментов, названия файлов которых начинаются с . (скрытые файлы).

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

  • false – скрытые фрагменты обрабатываются;

  • true – скрытые фрагменты пропускаются.

mode#

Режим доступа к собранному файлу.

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

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

    • 0644;

    • '644'.

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

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

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

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

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

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

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

owner#

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

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

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

regexp#

Регулярное выражение для фильтрации фрагментов по названиям файлов.

Если значение параметра не задано, включаются все фрагменты.

Все символы обратной черты \ должны быть экранированы (\\) для соблюдения синтаксиса YAML.

Примечание

Указанное значение обрабатывается средствами стандартной библиотеки Python.

remote_src#

Узел, на котором выполняется поиск фрагментов.

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

  • true – на управляемых узлах;

  • false – на управляющем узле.

selevel#

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

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

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

serole#

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

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

setype#

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

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

seuser#

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

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

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

src#

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

Путь к каталогу с фрагментами.

Важно

Каталог должен существовать и не быть пустым.

unsafe_writes#

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

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

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

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

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

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

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

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

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

validate#

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

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

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

Атрибуты#

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

Атрибут

Описание

action

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

async

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

bypass_host_loop

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

check_mode

Модуль не работает в режиме проверки.

diff_mode

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

platform

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

safe_file_operations

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

vault

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

Примеры#

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

Сборка конфигурации PHP#

Следующий пример демонстрирует сборку конфигурационного файла /etc/php/8.1/fpm/php.ini из фрагментов, хранящихся в каталоге php-config/ на управляющем узле:

---
- name: Configure PHP
  hosts: all
  become: true
  tasks:
    - name: Generate php.ini
      ansible.builtin.assemble:
        src: ./php-config/
        dest: /etc/php/8.1/fpm/php.ini

Использование разделителя#

Следующий пример демонстрирует использование строки-разделителя при сборке фрагментов, хранящихся на управляемых узлах:

---
- name: Configure NGINX
  hosts: all
  become: true
  tasks:
    - name: Generate nginx.conf
      ansible.builtin.assemble:
        src: /tmp/nginx-config/
        dest: /etc/nginx/nginx.conf
        delimiter: "# ANSIBLE ASSEMBLE"
        remote_src: true

Проверка конфигурационного файла#

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

---
- name: Update Bind9 config
  hosts: all
  become: true
  tasks:
    - name: Update named.conf
      ansible.builtin.assemble:
        src: ./bind-config/
        dest: /etc/bind/named.conf
        validate: named-checkconf %s