Модуль ansible.builtin.include_role — загрузка и выполнение роли

Примечание

Этот модуль входит в состав ansible-core и включен во все установки Ansible. В большинстве случаев можно использовать краткое имя модуля include_role, не указывая ключевое слово collections. Тем не менее мы рекомендуем использовать полное имя коллекции (FQCN) ansible.builtin.include_role, чтобы упростить переход к документации модуля и избежать конфликтов с другими коллекциями, в которых может быть модуль с таким же именем.

Краткое описание
Параметры
Атрибуты
Примечания
См. также
Примеры

Краткое описание

Динамически загружает и выполняет указанную роль как задачу.
Можно использовать только там, где разрешены задачи Ansible: внутри объектов play pre_tasks, tasks или post_tasks либо в качестве задачи внутри роли.
Ключевые слова уровня задачи, циклы и условия применяются только к самому оператору include_role.
Чтобы применить ключевые слова к задачам внутри роли, передайте их с помощью параметра apply или вместо этого используйте ansible.builtin.import_role.
Игнорирует некоторые ключевые слова, например until и retries.
Этот модуль также поддерживается для целевых систем Windows.
Не работает в обработчиках.

Параметры

Параметр	Комментарии
allow_duplicates логический	Переопределяет настройку метаданных роли, разрешая использовать роль несколько раз с одинаковыми параметрами. Варианты: `false` `true` ← (по умолчанию)
apply строка добавлено в Ansible 2.7	Принимает хеш ключевых слов задачи (например, `tags`, `become`), которые будут применены ко всем задачам включенной роли.
defaults_from строка	Файл для загрузки из каталога `defaults/` роли. По умолчанию: `"main"`
handlers_from строка добавлено в Ansible 2.8	Файл для загрузки из каталога `handlers/` роли. По умолчанию: `"main"`
name строка / обязательный	Имя роли, которую необходимо выполнить.
public логический добавлено в Ansible 2.7	Этот параметр определяет, будут ли `vars` и `defaults` роли доступны в play. Если задано значение `true`, переменные будут доступны задачам, следующим за задачей `include_role`. Это отличается от стандартного предоставления переменных для ролей, перечисленных в заголовке `roles`, или для ansible.builtin.import_role: в этих случаях переменные доступны в play во время разбора плейбука, а также более ранним ролям и задачам. Варианты: `false` ← (по умолчанию) `true`
rescuable логический добавлено в ansible-core 2.21	Этот переключатель позволяет определить, будут ли ошибки самого включения приводить к сбою задачи, который можно обработать блоком rescue, или к фатальным синтаксическим ошибкам. Варианты: `false` `true` ← (по умолчанию)
rolespec_validate логический добавлено в ansible-core 2.11	Выполнять проверку спецификации аргументов роли, если она определена. Варианты: `false` `true` ← (по умолчанию)
tasks_from строка	Файл для загрузки из каталога `tasks/` роли. По умолчанию: `"main"`
vars_from строка	Файл для загрузки из каталога `vars/` роли. По умолчанию: `"main"`

Атрибуты

Атрибут	Поддержка	Описание
action	Поддержка: нет Хотя это действие выполняется локально на контроллере, оно не управляется плагином действия	Указывает, что этому действию соответствует плагин действия, поэтому некоторые части параметров можно выполнять на контроллере
async	Поддержка: нет	Поддерживает использование с ключевым словом `async`
become	Поддержка: нет	Можно использовать вместе с ключевыми словами become
bypass_host_loop	Поддержка: нет	Принудительно выполняет «глобальную» задачу, не запускаемую отдельно для каждого узла. Это отключает шаблонизацию для каждого узла и учитывание параметров serial, throttle и других аспектов циклов Условия будут работать так, как если бы использовалось `run_once`; будут задействованы переменные первого доступного узла Это действие не будет нормально работать вне стратегий с пошаговой синхронизацией
bypass_task_loop	Поддержка: нет	Эти задачи игнорируют ключевые слова `loop` и `with_`
check_mode	Поддержка: полная	Может работать в режиме check_mode и возвращать прогноз статуса изменений без изменения целевой системы; если режим не поддерживается, действие будет пропущено.
connection	Поддержка: нет	Использует настроенные сведения о подключении к целевой системе для выполнения на ней кода
core	Поддержка: полная	Это функция «ядра» и она реализована не так, как большинство действий задач, поэтому ее невозможно переопределить с помощью системы плагинов.
delegation	Поддержка: нет Поскольку подключения и факты отсутствуют, делегировать включения бессмысленно	Можно использовать вместе с delegate_to и связанными ключевыми словами
diff_mode	Поддержка: нет	В режиме diff возвращает сведения об изменениях (или о возможных изменениях в check_mode)
ignore_conditional	Поддержка: нет	Действие не зависит от условного выполнения, поэтому игнорирует ключевое слово `when:`
platform	Платформы: все	Целевые ОС и их семейства, с которыми можно работать
tags	Поддержка: полная Это действие обрабатывает теги, но они автоматически не наследуются включенными задачами. См. `apply`	Позволяет использовать ключевое слово «tags» для выбора действий, которые будут выполнены
until	Поддержка: нет	Указывает, подчиняется ли это действие ключевым словам until/retry/poll

Примечания

Примечание

Начиная с ansible 2.21, типы ошибок, возникающих непосредственно при включении, нормализованы. С помощью параметра rescuable можно указать, будет ли это сбой задачи или синтаксическая ошибка.
Обработчики и доступны во всем play.
Начиная с Ansible 2.4, для статического поведения можно использовать ansible.builtin.import_role, а для динамического — это действие.

См. также

ansible.builtin.import_playbook: Импортировать плейбук.
ansible.builtin.import_role: Импортировать роль в play.
ansible.builtin.import_tasks: Импортировать список задач.
ansible.builtin.include_tasks: Динамически включить список задач.
Повторное использование артефактов Ansible: Дополнительные сведения о включении и импорте плейбуков, ролей и задач.

Примеры

- ansible.builtin.include_role:
    name: myrole

- name: Run tasks/other.yaml instead of 'main'
  ansible.builtin.include_role:
    name: myrole
    tasks_from: other

- name: Pass variables to role
  ansible.builtin.include_role:
    name: myrole
  vars:
    rolevar1: value from task

- name: Use role in loop
  ansible.builtin.include_role:
    name: '{{ roleinputvar }}'
  loop:
    - '{{ roleinput1 }}'
    - '{{ roleinput2 }}'
  loop_control:
    loop_var: roleinputvar

- name: Conditional role
  ansible.builtin.include_role:
    name: myrole
  when: not idontwanttorun

- name: Apply tags to tasks within included file
  ansible.builtin.include_role:
    name: install
    apply:
      tags:
        - install
  tags:
    - always

Авторы

Команда Ansible Core (@ansible)

Ссылки на коллекцию

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