Роли

• Структура каталога ролей
• Использование ролей
• Дублирование и выполнение ролей
• Переменные по умолчанию для ролей
• Зависимости ролей
• Встраивание модулей и плагинов в роли
• Путь поиска ролей
• Ansible Galaxy

Роли — это способ автоматической загрузки определенных файлов vars_files, задач и обработчиков на основе известной структуры файлов. Группировка контента по ролям также позволяет легко обмениваться ролями с другими пользователями.

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

Пример структуры проекта:

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

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

• tasks — содержит основной список задач, которые должны выполняться ролью.
• handlers — содержит обработчики, которые могут использоваться данной ролью или даже где-либо вне этой роли.
• defaults — переменные по умолчанию для роли (см. Использование переменных для получения дополнительной информации).
• vars — другие переменные для роли (см. Использование переменных для получения дополнительной информации).
• files — содержит файлы, которые могут быть развернуты с помощью этой роли.
• templates — содержит шаблоны, которые могут быть развернуты с помощью этой роли.
• meta — определяет некоторые метаданные для этой роли. Более подробные сведения см. ниже.

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

# roles/example/tasks/main.yml
- name: added in 2.4, previously you used 'include'
  import_tasks: redhat.yml
  when: ansible_facts['os_family']|lower == 'redhat'
- import_tasks: debian.yml
  when: ansible_facts['os_family']|lower == 'debian'

# roles/example/tasks/redhat.yml
- yum:
    name: "httpd"
    state: present

# roles/example/tasks/debian.yml
- apt:
    name: "apache2"
    state: present

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

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

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

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

Это определяет следующее поведение для каждой роли ‘x’:

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

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

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

Начиная с Ansible 2.4, вы можете использовать роли в строке с другими задачами, используя import_role или include_role:

---

- hosts: webservers
  tasks:
  - debug:
      msg: "before we run our role"
  - import_role:
      name: example
  - include_role:
      name: example
  - debug:
      msg: "after we ran our role"

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

Используемое имя роли может быть простым именем (см. Путь поиска ролей ниже), или это может быть полное квалифицированное имя:

---

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

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

---

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

Или, используя новый синтаксис:

---

- hosts: webservers
  tasks:
  - include_role:
       name: foo_app_instance
    vars:
      dir: '/opt/a'
      app_port: 5000
  ...

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

---

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

Наконец, вы можете назначить теги задачам внутри указанных вами ролей. Вы можете сделать так:

---

- hosts: webservers
  roles:
    - role: bar
      tags: ["foo"]
    # using YAML shorthand, this is equivalent to the above
    - { role: foo, tags: ["bar", "baz"] }

Или, ещё раз, используя новый синтаксис:

---

- hosts: webservers
  tasks:
  - import_role:
      name: foo
    tags:
    - bar
    - baz

С другой стороны, вы можете просто пометить импорт самой роли:

- hosts: webservers
  tasks:
  - include_role:
      name: bar
    tags:
     - foo

Дублирование и выполнение ролей

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

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

Учитывая вышесказанное, роль foo будет выполнена только один раз.

Чтобы сделать роли выполняемыми более одного раза, есть два варианта:

1. Передайте разные параметры в каждом определении роли.
2. Добавьте allow_duplicates: true в файл meta/main.yml для роли.

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

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

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

Пример 2 — использование allow_duplicates: true:

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

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

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

Переменные по умолчанию для ролей

Переменные по умолчанию для ролей позволяют устанавливать переменные по умолчанию для включённых или зависимых ролей (см. ниже). Чтобы создать значения по умолчанию, просто добавьте файл defaults/main.yml в свой каталог роли. Эти переменные будут иметь наименьший приоритет из всех доступных переменных и могут быть легко переопределены любой другой переменной, включая переменные инвентаризации.

Зависимости ролей

Зависимости ролей позволяют автоматически подключать другие роли при использовании роли. Зависимости ролей хранятся в файле 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

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

Например, роль под названием 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 для wheel, поскольку каждое определение, заданное car, использует разные значения параметров.

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

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

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

Хороший пример этого – если вы работали в компании AcmeWidgets и написали внутренний модуль, который помогал настроить внутреннее программное обеспечение, и вы хотели, чтобы другие люди в вашей организации легко использовали этот модуль, но не хотели рассказывать всем, как настроить свой путь к библиотеке Ansible.

В дополнение к структуре «задачи» и «обработчики» роли добавьте каталог с именем «библиотека». В этом каталоге «библиотека» разместите непосредственно модуль.

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

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 могут меняться в основных компонентах, и это не всегда гарантирует работоспособность. Тем не менее, это может быть удобным способом применения исправления к основному модулю, если у вас есть веские причины для этого. Естественно, проект предпочитает, чтобы любые внесения вносились обратно в github, по возможности, через запрос на добавление.

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

roles/
   my_custom_filter/
       filter_plugins
          filter1
          filter2

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

Путь поиска ролей

Ansible будет искать роли следующим образом:

• В каталоге roles/, относительно файла книги воспроизведения.
• По умолчанию, в /etc/ansible/roles

В Ansible 1.4 и более поздних версиях можно настроить дополнительный путь roles_path для поиска ролей. Используйте его для размещения всех ваших общих ролей в одном месте и простого обмена ими между несколькими проектами книг воспроизведения. См. Настройка Ansible для получения подробной информации о настройке в ansible.cfg.

Ansible Galaxy

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

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

Прочитайте страницу документации Ansible Galaxy для получения дополнительной информации