Роли

• Структура каталога ролей
• Использование ролей
• Дублирование и выполнение ролей
• Переменные по умолчанию для ролей
• Зависимости ролей
• Встраивание модулей и плагинов в роли
• Путь поиска ролей
• 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 и выше).
• Любые задачи копирования, скриптов, шаблонов или включения (в роли) могут ссылаться на файлы в 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: foo
      tags:
        - bar
        - baz
    # 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

Зависимости ролей всегда выполняются перед ролью, которая их включает, и могут быть рекурсивными. Зависимости также следуют правилам дублирования, указанным выше. Если другая роль также указывает её как зависимость, она не будет запущена повторно, основываясь на тех же правилах, что указаны выше. См. Зависимости ролей 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 для wheel, поскольку каждое определение, заданное car , использует разные значения параметров.

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

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

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

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

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

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

roles/
   my_custom_filter/
       filter_plugins
          filter1
          filter2

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

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

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

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

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

Ansible Galaxy

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

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

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