Роли

• Структура каталога ролей
• Использование ролей
• Дублирование и выполнение ролей
• Переменные по умолчанию для ролей
• Зависимости ролей
• Встраивание модулей и плагинов в роли
• Путь поиска ролей
• 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_os_platform|lower == 'redhat'
- import_tasks: debian.yml
  when: ansible_os_platform|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 и более поздние версии).
• Любые задачи копирования, сценариев, шаблонов или включения (в роли) могут ссылаться на файлы в 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, dir: '/opt/a', app_port: 5000 }
    - { role: foo_app_instance, dir: '/opt/b', app_port: 5001 }

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

---

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

Вы можете условно выполнить роль. Это не рекомендуется в общем случае с классическим синтаксисом, но часто используется при использовании import_role или include_role:

---

- hosts: webservers
  tasks:
  - include_role:
      name: some_role
    when: "ansible_os_family == 'RedHat'"

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

---

- hosts: webservers
  roles:
    - { role: foo, tags: ["bar", "baz"] }

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

---

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

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

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

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

Исходя из вышеизложенного, роль foo будет выполнена только один раз.

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

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

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

---
- hosts: webservers
  roles:
  - { role: foo, message: "first" }
  - { role: foo, 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, some_parameter: 3 }
  - { role: apache, apache_port: 80 }
  - { role: postgres, dbname: blarg, other_parameter: 12 }

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

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

---
dependencies:
- { role: wheel, n: 1 }
- { role: wheel, n: 2 }
- { role: wheel, n: 3 }
- { role: wheel, 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.

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

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

roles/
   my_custom_filter/
       filter_plugins
          filter1
          filter2

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

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

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

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

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

Ansible Galaxy

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

Вы можете зарегистрироваться с помощью социальной аутентификации, а клиент для загрузки «ansible-galaxy» включен в Ansible 1.4.2 и более поздних версиях.

Дополнительную информацию см. на странице «О» на сайте Galaxy.