Коллекции Ansible#

Использование коллекций позволяет значительно упростить создание playbook для решения самых разных задач по развертыванию и настройке ПО с помощью Ansible.

Назначение#

Коллекции Ansible, доступные в реестре Astra Automation Hub, предназначены для развертывания и настройки продуктов ПАО Группа Астра и вспомогательного стороннего ПО.

От коллекций, имеющихся в свободном доступе, они отличаются следующим:

Все роли распространяются в виде коллекций Ansible, в которые включаются также модули, специфичные для продуктов ПАО Группа Астра.
При разработке коллекций учитываются особенности продуктов ПАО Группа Астра.
Длительный срок поддержки.
Доработка функциональности исходя из потребностей клиентов ПАО Группа Астра.
Оперативное исправление всех найденных ошибок.
Многократная проверка кода, в том числе в реальных условиях.
Единая логика и стандартизированные подходы при написании кода, повышающие качество продукта.
Названия всех коллекций используют пространство имен astra.
Версии коллекций формируются с использованием семантического версионирования (semantic versioning).
Каждая коллекция хранится в отдельном репозитории Git.

Структура рабочего окружения#

При использовании коллекций из реестра Astra Automation Hub схема работы Ansible имеет вид:

../../../_images/ansible-astra-automation-hub-schema-light.svg

../../../_images/ansible-astra-automation-hub-schema-dark.svg

Перед выполнением playbook следует установить на управляющий узел все необходимые коллекции. Инструкции по установке коллекций приведены ниже в секции Применение.

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

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

meta/

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

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

Каталог с подкаталогами ролей. Подробности см. в секции Структура роли.
tests/

Каталог с файлами автоматических тестов для коллекции. Файлы этого каталога могут быть полезны при изучении особенностей использования коллекции и подготовке окружения для работы с ней.
CHANGELOG.md

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

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

Описание коллекции, включающее в себя:
- Предназначение коллекции.
- Требования к окружению.
- Список поддерживаемых операционных систем.
- Порядок описания коллекции в файле зависимостей Ansible и способ установки.
- Список ролей.
- Порядок запуска автоматических тестов.
- Тип лицензии, под которой распространяется код коллекции.
- Информация об авторских правах.
galaxy.yml

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

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

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

Все роли, размещенные в реестре Astra Automation Hub, распространяются только в составе коллекций. Каждая роль используется для установки и настройки только определенной функциональности. Например, роль astra.ald_pro.client используется только для настройки клиентов домена ALD Pro. Для настройки контроллера или его реплики следует использовать роли astra.ald_pro.controller и astra.ald_pro.replica соответственно.

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

defaults/

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

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

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

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

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

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

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

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

Описание роли, включающее в себя:
- Предназначение роли.
- Требования к окружению.
- Список переменных роли.
  
  Переменные роли делятся на обязательные и опциональные. Для опциональных переменных, значения которых не заданы, будут использованы значения по умолчанию.
  
  Предупреждение
  
  Значения обязательных переменных должны быть явно заданы в playbook или используемом им файле с переменными.
- Примеры использования.
- Порядок запуска автоматических тестов.
- Тип лицензии, под которой распространяется код роли.
- Информация об авторских правах.
- Список поддерживаемых операционных систем.

Настройки Ansible#

Во время работы Ansible использует настройки, переданные в аргументах командной строки или указанные в конфигурационном файле ansible.cfg. Поиск файла настроек ansible.cfg выполняется в следующем порядке:

Каталог, указанный в значении переменной окружения ANSIBLE_CONFIG.
Текущий каталог.
Домашний каталог активного пользователя.
Каталог /etc/ansible/.

Поиск прекращается как только файл ansible.cfg будет найден в любом из указанных расположений.

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

При использовании для работы с Ansible среды исполнения файл ansible.cfg следует размещать в каталоге проекта.

Подробности о файле настроек см. в документации Ansible.

Применение#

Использование коллекций Ansible из реестра Astra Automation Hub имеет следующие особенности:

Необходим доступ к реестру Astra Automation Hub по SSH, настроенный согласно инструкций из секции Доступ к реестрам Astra Automation Hub.
Для описания зависимостей создайте в каталоге проекта файл requirements.yml с записями следующего вида:
```
---
collections:
  - name: astra.<collection_name>
    type: git
    source: ssh://git@hub.astra-automation.ru:2222/aa-gca/ARFA/<collection_name>.git
# ...
```
где <collection_name> – название коллекции. Например, для коллекции astra.ceph указанная запись должна иметь вид:
```
---
collections:
  - name: astra.ceph
    type: git
    source: ssh://git@hub.astra-automation.ru:2222/aa-gca/ARFA/ceph.git
```
Примечание

Для всех коллекций из реестра Astra Automation Hub в поле type следует указывать значение git, а в поле source – ссылку на соответствующий репозиторий.

При использовании роли в playbook указывайте FQCN, например:

---
- name: Set up ALD Pro domain controller
  hosts: dc01
  # ...
  roles:
    - role: astra.ald_pro.controller
      vars:
        aldpro_domain: aldpro.example.com
        aldpro_pdc_ip: 192.168.56.11
        aldpro_pdc_name: dc01
        aldpro_admin_password: p@ssW0rD!

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

Установка зависимостей:

docker run \
   --rm \
   --interactive \
   --tty \
   --volume ~/.ssh/hub.astra-automation.ru:/root/.ssh/id_rsa \
   --volume "$(pwd):/app" \
   registry.astralinux.ru/aa/aa-base-ee \
   bash -c 'ansible-galaxy install -r requirements.yml'

Запуск playbook:

docker run \
   --rm \
   --tty \
   --volume "$(pwd):/app/" \
   registry.astralinux.ru/aa/aa-base-ee \
   bash -c 'ansible-playbook playbook.yml'

Подробности об использовании EE см. в документе Среда исполнения.

Коллекции Ansible

Содержание

Коллекции Ansible#

Назначение#

Структура рабочего окружения#

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

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

Настройки Ansible#

Применение#