include_role

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

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

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

• Модуль ansible.builtin.include_role позволяет включать задачи из роли динамически, то есть в момент выполнения сценария, а не статически при подготовке (parsing) сценария, как это делается при использовании директивы roles.

• Модуль может быть использован только там, где разрешено использование задач Ansible: внутри объектов pre_tasks, tasks или post_tasks в сценариях, а также как задача внутри роли.

• Директивы when, loop и with_ применяются к подключающей роль задаче, а не к задачам подключаемой роли. Чтобы применить условие или цикл к задачам роли, используйте параметр apply или модуль ansible.builtin.import_role.

• Модуль игнорирует некоторые директивы, такие как until и retries.

• Модуль не выполняется внутри обработчиков (handlers).

• Обработчики (handlers) роли, определенные в подключаемой роли, становятся доступными всему сценарию.

• Для статического подключения ролей рекомендуется использовать модуль ansible.builtin.import_role.

Параметры

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

allow_duplicates

Определяет, можно ли вызывать одну и ту же роль несколько раз с одинаковыми параметрами (одинаковыми значениями переменных).

Этот параметр переопределяет настройку allow_duplicates из метаданных роли (файл meta/main.yml).

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

• false – использовать роль повторно нельзя;

• true – использовать роль повторно можно.

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

apply

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

defaults_from

Файл, который необходимо загрузить из каталога роли defaults/.

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

handlers_from

Файл, который необходимо загрузить из каталога роли handlers/.

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

name

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

Название роли, которую необходимо выполнить.

public

Определяет, будут ли переменные vars и defaults из роли доступны для последующих задач сценария.

Это отличается от поведения при использовании директивы roles или модуля ansible.builtin.import_role, где переменные доступны уже на этапе обработки сценария и могут использоваться предыдущими задачами и ролями.

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

• false – переменные роли недоступны для последующих задач;

• true – переменные роли доступны для последующих задач.

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

rolespec_validate

Проверка спецификации аргументов, если она определена.

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

• false – отключить проверку;

• true – включить проверку.

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

tasks_from

Файл, который необходимо загрузить из каталога роли tasks/.

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

vars_from

Файл, который необходимо загрузить из каталога роли vars/.

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

Атрибуты

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

Атрибут	Описание
action	Модуль не имеет соответствующего расширения действия (action plugin), которое выполняет работу на управляющем узле.
async	Модуль не поддерживает асинхронное выполнение.
become	Модуль не поддерживает повышение привилегий.
bypass_host_loop	Модуль не поддерживает глобальное выполнение задачи.
bypass_task_loop	Модуль поддерживает директивы loop и with_.
check_mode	Модуль работает в режиме проверки (check_mode) в полном объеме.
connection	Модуль не использует информацию о настройках подключения к целевому узлу при выполнении заданий на нем.
core	Функциональность модуля не может быть изменена с помощью расширений.
delegation	Модуль не поддерживает delegate_to, то есть не может выполняться на другом узле.
diff_mode	Модуль не поддерживает режим сравнения.
ignore_conditional	Модуль поддерживает директиву when.
platform	Модуль поддерживает все платформы, с которыми может работать Ansible.
tags	Модуль поддерживает директиву tags.
until	Модуль не поддерживает механизм повторных попыток.

Примеры

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

Простое выполнение роли

Следующий пример демонстрирует выполнение роли astra.nginx.nginx:

---
# ...
  tasks:
    - name: Using astra.nginx.nginx
      ansible.builtin.include_role:
        name: astra.nginx.nginx

Выполнение роли с указанием файла задач

Следующий пример демонстрирует выполнение роли astra.ald_pro.controller с использованием задач не из основного файла main.yml, а из файла other.yml в каталоге tasks/ роли:

---
# ...
  tasks:
    - name: Run tasks/other.yaml instead of 'main'
      ansible.builtin.include_role:
        name: astra.ald_pro.controller
        tasks_from: other

Передача переменных роли при выполнении

Следующий пример демонстрирует выполнение роли с передачей ее параметров с помощью директивы vars:

---
# ...
  tasks:
    - name: Pass variables to role
      ansible.builtin.include_role:
        name: astra.nginx.nginx
      vars:
        use_ssl: true
        nginx_package_version: 1.22.1-9

Использование роли в цикле

Следующий пример демонстрирует выполнение нескольких ролей из коллекции astra.hardening в цикле:

---
# ...
  tasks:
    - name: Use roles in loop
      ansible.builtin.include_role:
        name: "{{ item }}"
      loop:
        - astra.hardening.devsec
        - astra.hardening.fstec