Коллекции

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 или используемом им файле с переменными.

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

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

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

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

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