Роли

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

• Структура каталога ролей
• Хранение и поиск ролей

• Использование ролей

  • Использование ролей на уровне прогона
  • Включение ролей: динамическое повторное использование
  • Импортирование ролей: статическое повторное использование

• Запуск роли несколько раз в одном плейбуке

  • Передача различных параметров
  • Использование allow_duplicates: true

• Использование зависимостей ролей

  • Запуск зависимостей ролей несколько раз в одном плейбуке
• Встраивание модулей и плагинов в роли
• Обмен ролями: Ansible Galaxy

Структура каталога ролей

Роль Ansible имеет определённую структуру каталогов с семью основными стандартными каталогами. Вы должны включить хотя бы один из этих каталогов в каждую роль. Вы можете опустить любые каталоги, которые роль не использует. Например:

# playbooks
site.yml
webservers.yml
fooservers.yml
roles/
    common/
        tasks/
        handlers/
        library/
        files/
        templates/
        vars/
        defaults/
        meta/
    webservers/
        tasks/
        defaults/
        meta/

По умолчанию Ansible будет искать в каждом каталоге роли файл main.yml для соответствующего контента (также main.yaml и main).

• tasks/main.yml - основной список задач, которые выполняет роль.
• handlers/main.yml - обработчики, которые могут использоваться внутри или вне этой роли.
• library/my_module.py - модули, которые могут использоваться внутри этой роли (см. Встраивание модулей и плагинов в роли для получения дополнительной информации).
• defaults/main.yml - переменные по умолчанию для роли (см. Использование переменных для получения дополнительной информации). Эти переменные имеют самый низкий приоритет из всех доступных переменных и могут быть легко переопределены любой другой переменной, включая переменные инвентаризации.
• vars/main.yml - другие переменные для роли (см. Использование переменных для получения дополнительной информации).
• files/main.yml - файлы, которые разворачивает роль.
• templates/main.yml - шаблоны, которые разворачивает роль.
• meta/main.yml - метаданные для роли, включая зависимости ролей.

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

# roles/example/tasks/main.yml
- name: Install the correct web server for RHEL
  import_tasks: redhat.yml
  when: ansible_facts['os_family']|lower == 'redhat'

- name: Install the correct web server for Debian
  import_tasks: debian.yml
  when: ansible_facts['os_family']|lower == 'debian'

# roles/example/tasks/redhat.yml
- name: Install web server
  ansible.builtin.yum:
    name: "httpd"
    state: present

# roles/example/tasks/debian.yml
- name: Install web server
  ansible.builtin.apt:
    name: "apache2"
    state: present

Роли также могут включать модули и другие типы плагинов в каталоге library. Дополнительную информацию см. в разделе Встраивание модулей и плагинов в роли ниже.

Хранение и поиск ролей

По умолчанию Ansible ищет роли в двух местах:

• в каталоге roles/, относительно файла плейбука
• в /etc/ansible/roles

Если вы храните роли в другом месте, установите параметр конфигурации roles_path, чтобы Ansible мог найти ваши роли. Размещение общих ролей в одном месте упрощает их использование в нескольких плейбуках. Подробности управления настройками в ansible.cfg см. в разделе Настройка Ansible.

В качестве альтернативы, вы можете вызвать роль с полным путём:

---
- hosts: webservers
  roles:
    - role: '/path/to/my/roles/common'

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

Вы можете использовать роли тремя способами:

• на уровне прогона с помощью параметра roles: это классический способ использования ролей в прогоне.
• на уровне задач с помощью include_role: вы можете динамически повторно использовать роли в любом месте раздела tasks прогона, используя include_role.
• на уровне задач с помощью import_role: вы можете статически повторно использовать роли в любом месте раздела tasks прогона, используя import_role.

Использование ролей на уровне прогона

Классический (первоначальный) способ использования ролей — с помощью параметра roles для заданного прогона:

---
- hosts: webservers
  roles:
    - common
    - webservers

При использовании параметра roles на уровне прогона, для каждой роли «x»:

• Если существует roles/x/tasks/main.yml, Ansible добавляет задачи из этого файла в прогон.
• Если существует roles/x/handlers/main.yml, Ansible добавляет обработчики из этого файла в прогон.
• Если существует roles/x/vars/main.yml, Ansible добавляет переменные из этого файла в прогон.
• Если существует roles/x/defaults/main.yml, Ansible добавляет переменные из этого файла в прогон.
• Если существует roles/x/meta/main.yml, Ansible добавляет зависимости роли в список ролей.
• Любые задачи копирования, скриптов, шаблонов или включения (в роли) могут ссылаться на файлы в roles/x/{files,templates,tasks}/ (каталог зависит от задачи) без необходимости указывать пути относительно или абсолютно.

При использовании параметра roles на уровне прогона, Ansible обрабатывает роли как статические импорты и обрабатывает их во время разбора плейбука. Ansible выполняет ваш плейбук в таком порядке:

• Любые pre_tasks , определённые в прогоне.
• Любые обработчики, вызванные pre_tasks.
• Каждая роль, перечисленная в roles:, в указанном порядке. Любые зависимости ролей, определённые в meta/main.yml роли, выполняются первыми, с учётом фильтрации по тегам и условных операторов. См. Использование зависимостей ролей для получения более подробной информации.
• Любые tasks , определённые в прогоне.
• Любые обработчики, вызванные ролями или задачами.
• Любые post_tasks , определённые в прогоне.
• Любые обработчики, вызванные post_tasks.

Вы можете передать другие ключевые слова параметру roles:

---
- hosts: webservers
  roles:
    - common
    - role: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
      tags: typeA
    - role: foo_app_instance
      vars:
        dir: '/opt/b'
        app_port: 5001
      tags: typeB

Когда вы добавляете тег к параметру role , Ansible применяет тег к ВСЕМ задачам в рамках роли.

При использовании vars: в разделе roles: плейбука, переменные добавляются к переменным прогона, делая их доступными для всех задач в рамках прогона до и после роли. Это поведение можно изменить с помощью DEFAULT_PRIVATE_ROLE_VARS.

Включение ролей: динамическое повторное использование

Вы можете динамически повторно использовать роли в любом месте раздела tasks прогона, используя include_role. Хотя роли, добавленные в раздел roles , выполняются до любых других задач в плейбуке, включённые роли выполняются в порядке их определения. Если перед задачей include_role есть другие задачи, эти задачи будут выполнены первыми.

Для включения роли:

---
- hosts: webservers
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: "this task runs before the example role"

    - name: Include the example role
      include_role:
        name: example

    - name: Print a message
      ansible.builtin.debug:
        msg: "this task runs after the example role"

Вы можете передать другие ключевые слова, включая переменные и теги, при включении ролей:

---
- hosts: webservers
  tasks:
    - name: Include the foo_app_instance role
      include_role:
        name: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
      tags: typeA
  ...

При добавлении тега к задаче include_role , Ansible применяет тег only к самому включению. Это означает, что вы можете передать --tags для выполнения только выбранных задач из роли, если у самих этих задач есть тот же тег, что и у инструкции включения. См. Выборочное выполнение задач с тегами в переиспользуемых файлах для получения подробностей.

Вы можете условно включить роль:

---
- hosts: webservers
  tasks:
    - name: Include the some_role role
      include_role:
        name: some_role
      when: "ansible_facts['os_family'] == 'RedHat'"

Импортирование ролей: статическое повторное использование

Вы можете статически повторно использовать роли в любом месте раздела tasks прогона, используя import_role. Поведение такое же, как при использовании ключевого слова roles . Например:

---
- hosts: webservers
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: "before we run our role"

    - name: Import the example role
      import_role:
        name: example

    - name: Print a message
      ansible.builtin.debug:
        msg: "after we ran our role"

Вы можете передать другие ключевые слова, включая переменные и теги, при импортировании ролей:

---
- hosts: webservers
  tasks:
    - name: Import the foo_app_instance role
      import_role:
        name: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
  ...

Когда вы добавляете тег к инструкции import_role , Ansible применяет тег к all задачам в рамках роли. См. Наследование тегов: добавление тегов к нескольким задачам для получения подробностей.

Запуск роли несколько раз в одном плейбуке

Ansible выполняет каждую роль только один раз, даже если вы её определяете несколько раз, если параметры, заданные для роли, не отличаются для каждого определения. Например, Ansible выполняет роль foo только один раз в прогоне таком как этот:

---
- hosts: webservers
  roles:
    - foo
    - bar
    - foo

У вас есть два варианта, чтобы заставить Ansible выполнить роль более чем один раз.

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

Вы можете передавать различные параметры в каждом определении роли, как:

---
- hosts: webservers
  roles:
    - { role: foo, vars: { message: "first" } }
    - { role: foo, vars: { message: "second" } }

или

---
- hosts: webservers
  roles:
    - role: foo
      vars:
        message: "first"
    - role: foo
      vars:
        message: "second"

В этом примере, поскольку каждое определение роли имеет разные параметры, Ansible выполняет foo дважды.

Использование allow_duplicates: true

Добавьте allow_duplicates: true в файл meta/main.yml для роли:

# playbook.yml
---
- hosts: webservers
  roles:
    - foo
    - foo

# roles/foo/meta/main.yml
---
allow_duplicates: true

В этом примере Ansible выполняет foo дважды, так как мы явным образом разрешили это сделать.

Использование зависимостей ролей

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

Зависимости ролей хранятся в файле meta/main.yml в каталоге роли. Этот файл должен содержать список ролей и параметров для вставки перед указанной ролью. Например:

# roles/myapp/meta/main.yml
---
dependencies:
  - role: common
    vars:
      some_parameter: 3
  - role: apache
    vars:
      apache_port: 80
  - role: postgres
    vars:
      dbname: blarg
      other_parameter: 12

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

Выполнение зависимостей ролей несколько раз в одном плейбуке

Ansible обрабатывает дублирующие зависимости ролей как дублирующие роли, указанные в roles:: Ansible выполняет зависимости ролей только один раз, даже если они определены несколько раз, если параметры, теги или условие «when» для роли не отличаются для каждого определения. Если две роли в плейбуке оба указывают третью роль в качестве зависимости, Ansible выполнит эту зависимость только один раз, если вы не передадите разные параметры, теги, условие «when» или не используете allow_duplicates: true в зависимой (третьей) роли. Подробнее см. Зависимости ролей Galaxy.

Например, роль с именем car зависит от роли с именем wheel следующим образом:

---
dependencies:
  - role: wheel
    vars:
      n: 1
  - role: wheel
    vars:
      n: 2
  - role: wheel
    vars:
      n: 3
  - role: wheel
    vars:
      n: 4

И роль wheel зависит от двух ролей: tire и brake. Файл meta/main.yml для wheel будет содержать следующее:

---
dependencies:
  - role: tire
  - role: brake

И файл meta/main.yml для tire и brake будет содержать следующее:

---
allow_duplicates: true

Результирующий порядок выполнения будет следующим:

tire(n=1)
brake(n=1)
wheel(n=1)
tire(n=2)
brake(n=2)
wheel(n=2)
...
car

Чтобы использовать allow_duplicates: true с зависимостями ролей, вы должны указать его для зависимой роли, а не для родительской роли. В приведенном выше примере allow_duplicates: true появляется в файле meta/main.yml ролей tire и brake . Роль wheel не требует allow_duplicates: true, потому что каждый экземпляр, определенный с помощью car, использует разные значения параметров.

Встраивание модулей и плагинов в роли

Если вы пишете пользовательский модуль (см. Нужно ли разрабатывать модуль?) или плагин (см. Разработка плагинов), вы можете распространить его как часть роли. Например, если вы пишете модуль, который помогает настроить внутреннее программное обеспечение вашей компании, и вы хотите, чтобы другие люди в вашей организации использовали этот модуль, но не хотите рассказывать всем, как настроить путь к библиотеке Ansible, вы можете включить модуль в роль internal_config.

Чтобы добавить модуль или плагин в роль: наряду со структурой «tasks» и «handlers» роли добавьте каталог с именем «library», а затем включите модуль непосредственно в каталог «library».

Предположим, у вас было это:

roles/
    my_custom_modules/
        library/
            module1
            module2

Модуль будет доступен в самой роли, а также во всех ролях, которые вызываются после этой роли, как показано ниже:

---
- hosts: webservers
  roles:
    - my_custom_modules
    - some_other_role_using_my_custom_modules
    - yet_another_role_using_my_custom_modules

При необходимости вы также можете встроить модуль в роль для изменения модуля в основной дистрибуции Ansible. Например, вы можете использовать разработочную версию определенного модуля до его выпуска в производственных выпусках, скопировав модуль и встроив копию в роль. Используйте этот подход с осторожностью, так как подписи API могут изменяться в основных компонентах, и этот обходной путь не гарантирует работоспособности.

Тот же механизм можно использовать для встраивания и распространения плагинов в роли, используя ту же схему. Например, для плагина фильтра:

roles/
    my_custom_filter/
        filter_plugins
            filter1
            filter2

Эти фильтры можно затем использовать в шаблоне Jinja в любой роли, вызываемой после «my_custom_filter».

Обмен ролями: Ansible Galaxy

Ansible Galaxy — это бесплатный сайт для поиска, скачивания, оценки и обзора всех видов ролей Ansible, разработанных сообществом, и может стать отличным стартом для ваших проектов автоматизации.

Клиент ansible-galaxy включен в Ansible. Клиент Galaxy позволяет загружать роли из Ansible Galaxy и также предоставляет отличную стандартную структуру для создания собственных ролей.

Дополнительную информацию см. на странице документации Ansible Galaxy