Ctrl+K
Ctrl+K
Ctrl+K

Коллекции

Коллекции#

Private Automation Hub предъявляет к коллекциям следующие требования:

  • Название:

    • длина не менее двух знаков;

    • может содержать буквы латинского алфавита, цифры и символ _;

    • не может начинаться с символа _.

  • Коллекция должна иметь определенную структуру файлов и каталогов (см. ниже).

  • Семантическое версионирование.

К коду коллекций, хранящихся в репозиториях Git, предъявляются следующие требования:

  • Номера версий должны указываться в тегах.

  • Тег должен содержать номер версии, например, 1.0.1.

  • Тег может содержать префикс v, например, v1.0.1.

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

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

  • 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, необходимые для использования коллекции.

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

Для использования в Private Automation Hub роли Ansible должны быть включены в состав коллекции.

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

  • defaults/

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

  • files/

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

  • handlers/

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

  • meta/

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

  • tasks/

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

  • templates/

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

  • vars/

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

  • LICENSE

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

  • README.md

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

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

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

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

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

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

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

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

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

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

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

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

Содержание