Коллекции Ansible

Коллекции Ansible#

Коллекцией (collection) называется распространяемый как единое целое набор компонентов, расширяющих возможности Ansible.

В состав коллекции могут входить следующие компоненты:

  • расширения (plugins);

  • модули (modules);

  • роли (roles);

  • наборы сценариев (playbooks).

Структура коллекции#

Пример команды для создания структуры каталогов коллекции:

ansible-galaxy collection init my_space.my_collection

Здесь my_space.my_collection – определяет путь к каталогу, в котором будет создана коллекция, в данном случае – my_space/my_collection/.

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

my_space/my_collection
├── docs
├── galaxy.yml
├── meta
│   └── runtime.yml
├── plugins
│   └── README.md
├── README.md
└── roles

В составе коллекции могут быть следующие файлы и каталоги:

  • meta/

    Каталог с файлами, содержащими служебную информацию о коллекции, используемую утилитой ansible-galaxy.

  • plugins/

    Опциональный каталог, содержащий расширения, необходимые для работы коллекции.

  • roles/

    Каталог с подкаталогами ролей. Подробности приведены в описании ролей.

  • tests/

    Каталог с файлами автоматических тестов для коллекции.

  • CHANGELOG.md

    Файл с историей изменений между версиями.

  • LICENSE

    Файл лицензии, устанавливающей правила использования и распространения коллекции.

  • README.md

    Описание коллекции, включающее в себя:

    • предназначение коллекции;

    • требования к окружению;

    • список поддерживаемых операционных систем;

    • порядок описания коллекции в файле зависимостей Ansible и способ установки;

    • список ролей;

    • порядок запуска автоматических тестов;

    • тип лицензии, под которой распространяется код коллекции;

    • информация об авторских правах.

  • galaxy.yml

    Сведения о коллекции, используемые утилитой ansible-galaxy, включая номер ее актуальной версии.

    Пример заполнения galaxy.yml#
    ---
    namespace: astra
    name: ald_pro
    version: 1.0.0
    description: Collection for ALD Pro deployment
    readme: README.md
    authors:
      - LLC "RusBITech-Astra"
    dependencies:
      "freeipa.ansible_freeipa": "1.10.0"
      "ansible.utils": "3.0.0"
    tags:
      - astra
      - ald_pro
    repository: https://hub.astra-automation.ru/aa-gca/ARFA/ald_pro
    documentation: https://hub.astra-automation.ru/aa-gca/ARFA/ald_pro/-/blob/master/README.md
    

    Здесь:

    • astra – название пространства имен.

    • ald_pro – название коллекции.

    • version – номер версии коллекции.

    • description – краткое описание коллекции.

    • readme – путь к файлу README, содержащему подробное описание коллекции.

    • authors – список авторов коллекции.

    • dependencies – зависимости, необходимые для использования коллекции.

    • tags – список тегов, по которым можно найти коллекцию среди множества других.

    • repository – ссылка на репозиторий с исходным кодом коллекции.

    • documentation – ссылка на документацию коллекции.

  • requirements_ansible.yml

    Зависимости Ansible, необходимые для использования коллекции.

Особенности коллекций, доступных на портале Automation Hub, приведены в описании Automation Hub.

Роль#

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

Пример создания структуры каталогов для роли:

ansible-galaxy init httpd

Здесь httpd – название каталога, в котором будет создана структура роли.

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

httpd/
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── README.md
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
   └── main.yml

В составе роли могут быть следующие файлы и каталоги:

  • defaults/

    Каталог с файлами, содержащими значения по умолчанию для переменных роли.

  • files/

    Каталог с вспомогательными файлами, используемыми ролью, например, шаблоны HTML-страниц, изображения и так далее. При выполнении роли файлы из этого каталога копируются на управляемые узлы.

  • handlers/

    Каталог с файлами обработчиков, выполняемых при использовании роли.

  • meta/

    Каталог с файлами, содержащими служебную информацию о роли, используемую утилитой ansible-galaxy.

  • tasks/

    Каталог с файлами, выполняющимися при использовании роли.

  • templates/

    Каталог с шаблонами формата Jinja 2.

  • vars/

    Каталог с файлами, содержащими список переменных роли. Каждая роль содержит список переменных, позволяющих управлять настройками соответствующего ПО.

  • LICENSE

    Файл лицензии, под которой распространяется код роли.

  • README.md

    Описание роли, включающее в себя:

    • Предназначение роли.

    • Требования к окружению.

    • Список переменных роли.

      Переменные роли делятся на обязательные и опциональные. Для опциональных переменных, значения которых не заданы, будут использованы значения по умолчанию.

      Предупреждение

      Значения обязательных переменных должны быть явно заданы в playbook или используемом им файле с переменными.

    • Примеры использования.

    • Порядок запуска автоматических тестов.

    • Тип лицензии, под которой распространяется код роли.

    • Информация об авторских правах.

    • Список поддерживаемых операционных систем.

Файлы playbook содержат список подключаемых ролей как в следующем примере:

- hosts: server.example.com
   become: true
   gather_facts: true
   roles:
     - astra.postgresql.postgresql
     - astra.rubackup.rubackup_server