Открыть сервис
Главная → Блог → Ansible Collection Development

Ansible Collection Development

Ansible Collection Development — это процесс создания, упаковки и распространения наборов модулей, плагинов, ролей и других компонентов для системы управления конфигурациями Ansible, объединённых в единую коллекцию. Коллекции (collections) представляют собой стандартный способ распространения контента Ansible, начиная с версии 2.9, и являются основным форматом для публикации пользовательских расширений в Ansible Galaxy и Automation Hub.

История и предпосылки

До появления коллекций весь контент для Ansible (модули, плагины, роли) распространялся либо в составе основного пакета ansible-base (позже ansible-core), либо в виде отдельных ролей на Ansible Galaxy. Это создавало проблемы с версионированием, зависимостями и поддержкой: любое изменение в модуле требовало обновления всего пакета, а сторонние разработчики не имели удобного способа упаковки своих расширений.

В 2019 году с выходом Ansible 2.9 была введена концепция коллекций, а в 2020 году в Ansible 2.10 коллекции стали основным способом распространения контента. Основной пакет ansible был разделён на ansible-core (ядро) и набор коллекций, которые можно устанавливать независимо. Это позволило сообществу и вендорам (например, Cisco, Red Hat, VMware) выпускать собственные коллекции с модулями для своих продуктов, не дожидаясь включения в основной релиз.

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

Коллекция имеет строго определённую файловую структуру, которая обеспечивает автоматическое обнаружение и загрузку компонентов Ansible. Минимальная структура включает:

`` my_namespace/ └── my_collection/ ├── docs/ ├── galaxy.yml ├── meta (организация признана экстремистской, деятельность запрещена в РФ)/ │ └── runtime.yml ├── plugins/ │ ├── modules/ │ ├── inventory/ │ ├── lookup/ │ ├── filter/ │ └── callback/ ├── roles/ ├── playbooks/ ├── tests/ └── README.md ``

Основные компоненты

  • galaxy.yml — мета-файл в формате YAML, содержащий информацию о коллекции: имя, версию, автора, лицензию, зависимости от других коллекций и теги. Этот файл обязателен для публикации.
  • meta/runtime.yml — файл, определяющий требования к версии Ansible, совместимость с платформами и настройки выполнения (например, requires_ansible).
  • plugins/ — директория, содержащая поддиректории для каждого типа плагинов: modules/, inventory/, lookup/, filter/, callback/, connection/, vars/ и другие. Каждый плагин представляет собой файл Python (или другой язык, поддерживаемый Ansible).
  • roles/ — директория для ролей Ansible, которые могут быть включены в коллекцию. Каждая роль имеет собственную структуру (tasks, handlers, vars, defaults, templates, files).
  • playbooks/ — директория для примеров плейбуков, демонстрирующих использование коллекции.
  • tests/ — директория для тестов (обычно с использованием ansible-test).

Процесс разработки

Инициализация

Разработка коллекции начинается с создания скелета. Для этого используется команда ansible-galaxy collection init:

``bash ansible-galaxy collection init my_namespace.my_collection ``

Эта команда создаёт базовую структуру с файлом galaxy.yml и пустыми директориями. После этого разработчик может добавлять модули, плагины и роли.

Разработка модулей

Модули являются основным типом плагинов и пишутся на Python. Каждый модуль должен содержать:

  • Документацию в формате DOCUMENTATION (строка YAML внутри модуля).
  • Примеры использования (EXAMPLES).
  • Возвращаемые значения (RETURN).

Пример минимального модуля my_module.py:

```python

!/usr/bin/python

-- coding: utf-8 --

from ansible.module_utils.basic import AnsibleModule

DOCUMENTATION = r''' --- module: my_module short_description: Пример модуля description: Этот модуль выполняет простую операцию. options: name: description: Имя для вывода. required: true type: str '''

EXAMPLES = r'''

  • name: Пример использования модуля

my_namespace.my_collection.my_module: name: "World" '''

RETURN = r''' message: description: Сообщение с приветствием. returned: always type: str sample: "Hello, World!" '''

def run_module(): module = AnsibleModule( argument_spec=dict( name=dict(type='str', required=True) ) ) result = dict( changed=False, message=f"Hello, {module.params['name']}!" ) module.exit_json(**result)

def main(): run_module()

if __name__ == '__main__': main() ```

Разработка ролей

Роли в коллекции создаются в директории roles/. Каждая роль имеет стандартную структуру:

`` roles/my_role/ ├── tasks/ │ └── main.yml ├── handlers/ │ └── main.yml ├── defaults/ │ └── main.yml ├── vars/ │ └── main.yml ├── templates/ ├── files/ ├── meta/ │ └── main.yml └── README.md ``

Роль может быть вызвана из плейбука с указанием полного имени коллекции:

```yaml

  • name: Применить роль

hosts: all roles:

  • my_namespace.my_collection.my_role

```

Тестирование

Для тестирования коллекций используется утилита ansible-test, входящая в состав ansible-core. Она позволяет запускать:

  • Синтаксические проверки (sanity tests).
  • Модульные тесты (unit tests) на базе pytest.
  • Интеграционные тесты (integration tests), которые выполняются на реальных или виртуальных машинах.

Тесты размещаются в директории tests/:

`` tests/ ├── sanity/ │ └── ignore.txt ├── unit/ │ └── plugins/ │ └── modules/ │ └── test_my_module.py └── integration/ └── targets/ └── my_module/ ├── tasks/ │ └── main.yml └── vars/ └── main.yml ``

Версионирование

Коллекции следуют семантическому версионированию (SemVer) в формате MAJOR.MINOR.PATCH. Версия указывается в galaxy.yml. При публикации новой версии необходимо:

  • Увеличить номер версии.
  • Создать Git-тег.
  • Запустить сборку командой ansible-galaxy collection build.
  • Опубликовать архив на Ansible Galaxy или Automation Hub.

Публикация и распространение

Ansible Galaxy

Ansible Galaxy — публичный репозиторий коллекций, поддерживаемый Red Hat. Публикация выполняется командой:

``bash ansible-galaxy collection publish ./my_namespace-my_collection-1.0.0.tar.gz ``

Для публикации требуется API-ключ, который можно получить в настройках учётной записи на galaxy.ansible.com.

Automation Hub

Automation Hub — корпоративный репозиторий, входящий в состав Red Hat Ansible Automation Platform. Публикация в него обычно выполняется через веб-интерфейс или CI/CD-пайплайны с использованием токенов аутентификации.

Установка коллекции

Пользователи устанавливают коллекции командой:

``bash ansible-galaxy collection install my_namespace.my_collection ``

Коллекция может быть установлена из Galaxy, Automation Hub, локального архива или Git-репозитория.

Зависимости и требования

Коллекции могут зависеть от других коллекций. Зависимости указываются в galaxy.yml:

``yaml dependencies: "community.general": ">=5.0.0" "ansible.netcommon": "*" ``

При установке коллекции Ansible автоматически загружает все указанные зависимости.

Инструменты и лучшие практики

Инструменты разработки

  • ansible-lint — статический анализатор кода, проверяющий плейбуки, роли и коллекции на соответствие лучшим практикам.
  • molecule — фреймворк для тестирования ролей, поддерживающий различные провайдеры (Docker, Vagrant, OpenStack).
  • pre-commit — хуки для автоматической проверки перед коммитом (например, проверка синтаксиса YAML, форматирование Python).

Лучшие практики

  • Использовать неймспейсы, отражающие организацию или проект (например, cisco.ios, redhat.satellite).
  • Документировать каждый модуль и роль в формате DOCUMENTATION.
  • Писать тесты для всех модулей и ролей.
  • Следовать семантическому версионированию.
  • Указывать минимальную версию ansible-core в meta/runtime.yml.
  • Использовать CI/CD (например, GitHub Actions) для автоматической сборки, тестирования и публикации.

Ограничения и особенности

  • Коллекции не могут переопределять встроенные модули Ansible (например, ansible.builtin.copy).
  • Для использования коллекции на управляемых узлах не требуется установка дополнительного ПО — модули выполняются на control node.
  • Коллекции могут содержать плагины на Python, PowerShell (для Windows) и других языках, поддерживаемых Ansible.
  • Размер коллекции ограничен (рекомендуется не более 50 МБ для публикации на Galaxy).

Примеры известных коллекций

  • community.general — обширная коллекция от сообщества, включающая модули для различных систем.
  • cisco.ios — коллекция для управления устройствами Cisco IOS.
  • redhat.satellite — коллекция для Red Hat Satellite.
  • kubernetes.core — коллекция для управления Kubernetes.
  • amazon.aws — коллекция для Amazon Web Services.

Источники

  • Ansible Documentation. «Developing Collections» (docs.ansible.com).
  • Red Hat. «Ansible Collection Structure and Development» (access.redhat.com).
  • Ansible Galaxy User Guide (galaxy.ansible.com).
  • «Ansible for DevOps» by Jeff Geerling (2022).
  • Ansible Community. «Collection Requirements and Best Practices» (github.com/ansible-collections).

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →

Похожие материалы