Molecule — тестирование Ansible-ролей

Molecule — это фреймворк для разработки и тестирования Ansible-ролей. Он поднимает временное окружение (контейнер или виртуальную машину), прогоняет на нём роль и проверяет результат. Так ошибки ловятся локально, до попадания в продакшн.

1. Что такое Molecule

Molecule автоматизирует стандартный цикл разработки роли:

1. создать каркас роли с тестами;
2. поднять тестовое окружение (Docker, Vagrant, podman);
3. применить роль (converge);
4. проверить результат (verify);
5. проверить идемпотентность — повторный запуск не должен менять систему;
6. удалить окружение (destroy).

2. Установка

Molecule — это Python-пакет. Устанавливается вместе с драйвером Docker:

python3 -m venv .venv
source .venv/bin/activate
pip install molecule molecule-docker ansible-core ansible-lint yamllint

Проверка установки

molecule --version

3. Создание роли и сценария

molecule init role myapp --driver docker

Команда создаёт стандартную структуру:

myapp/
├── tasks/
│   └── main.yml
├── handlers/
├── templates/
├── vars/
├── defaults/
│   └── main.yml
├── meta/
└── molecule/
    └── default/
        ├── molecule.yml
        ├── converge.yml
        └── verify.yml

4. Сценарий и molecule.yml

Каждый сценарий (scenario) описывает окружение и шаги тестирования. Основной файл — molecule.yml:

---
dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    pre_build_image: true
provisioner:
  name: ansible
verifier:
  name: ansible

Поля

5. Команды сценария

molecule converge   # применить роль к окружению
molecule verify     # запустить проверки
molecule idempotence # прогнать и убедиться, что ничего не меняется
molecule test       # полный цикл: dependency -> create -> converge -> verify -> destroy
molecule destroy    # удалить окружение
molecule list       # показать текущие инстансы

6. Проверки на Testinfra

Для тестов удобно использовать testinfra — Python-библиотеку, которая проверяет состояние машины:

# molecule/default/tests/test_default.py
import testinfra.utils.ansible_runner as ansible_runner

testinfra_hosts = ansible_runner.AnsibleRunner(
    ansible_inventory_path='inventory'
).get_hosts('all')

def test_service(host):
    service = host.service('nginx')
    assert service.is_enabled
    assert service.is_running

def test_port(host):
    assert host.socket('tcp://0.0.0.0:80').is_listening

В molecule.yml переключи проверку на testinfra:

verifier:
  name: testinfra
  pip:
    - pytest

7. Проверка идемпотентности и линтинг

molecule idempotence прогоняет роль дважды. Если второй запуск вносит изменения — команда падает. Это сигнал, что роль написана не идемпотентно: она не описывает желаемое состояние (например, через state=present), а каждый раз вносит изменения.

Линтеры следят за качеством кода:

ansible-lint tasks/main.yml   # проверка стиля и ошибок
yamllint molecule/default/molecule.yml  # проверка YAML
molecule lint # линт внутри сценария

8. Конфигурация снаружи

Variable-интерполяцию и environment можно задать в блоке env:

scenario:
  name: default
driver:
  name: docker
env:
  ANSIBLE_ROLES_PATH: ../../..

Для разных окружений создаются отдельные сценарии:

molecule init scenario --scenario-name ubuntu22
molecule test --scenario-name ubuntu22

9. Molecule в CI

Сценарий легко встроить в пайплайн GitLab CI:

test-role:
  stage: test
  image: python:3.11
  services:
    - docker:dind
  before_script:
    - pip install molecule molecule-docker ansible-core
  script:
    - molecule test

10. Драйверы и платформы

Molecule работает поверх разных драйверов: docker (по умолчанию), podman, vagrant (полные виртуальные машины), delegated и облачные платформы. Выбор описывается в molecule.yml:

driver:
  name: docker
platforms:
  - name: ubuntu-22.04
    image: ubuntu:22.04
    pre_build_image: true
  - name: debian-12
    image: debian:12
    pre_build_image: true

• vagrant — ближе к реальному железу, но медленнее запуска.
• delegated — управление уже существующими хостами.
• ec2/gcp — проверка ролей непосредственно в облаке.

11. Переменные, группы и факты

Реальные роли зависят от инвентаря: группами хостов и host_vars управляет раздел inventory в конфигурации:

platforms:
  - name: app-1
    image: ubuntu:22.04
    groups:
      - app_servers
provisioner:
  name: ansible
  inventory:
    host_vars:
      app-1:
        app_port: 8080

Так тестируется поведение роли, которое зависит от групповых переменных: например, разные версии пакета для серверов приложений и баз данных.

Дополнительные факты передаются ключом ansible.extra_vars, а зависимости роли подтягиваются через dependencies в сценарии.

12. Сценарий как инструмент

Команды сценария дают точечный контроль без уничтожения окружения:

molecule create      # поднять платформы
molecule converge    # применить роль
molecule verify      # прогнать тесты
molecule destroy     # удалить окружения

molecule converge полезен для отладки: можно повторно применить роль, посмотреть вывод и исправить роль без пересоздания контейнеров.

• Идемпотентность проверяй двойным запуском курса: второй converge не должен менять систему.
• Свои сценарии добавляются в каталог scenarios/ — например, отдельный под ОС или с особым драйвером.

13. Molecule в зрелом пайплайне

Проверка роли не ограничивается одним прогоном — производственный подход состоит из нескольких слоёв:

Храни сценарии под разные дистрибутивы и собирай матрицу в CI, а сами шаги раскатывай параллельно — так регрессии ловятся до мержа роли.

14. Docker-окружение: сети и тома

Роль редко живёт в изоляции: ей нужны базы, кэши и внешние сервисы в той же сети. Molecule отдаёт управление окружением Docker — сети, тома и лимиты настраиваются в molecule.yml:

platforms:
  - name: app
    image: debian:12
    networks:
      - name: molecule-net
    volumes:
      - ./shared:/shared

• Несколько контейнеров с общим networks видят друг друга по имени — как в реальной архитектуре.
• Тома монтируют код и данные, не пересобирая образ на каждый прогон.
• Ресурсы ограничиваются секцией cgroups/memory — прод-натяжка сразу видна в тесте.

15. Интеграция с реальными зависимостями

Роли часто требуют внешние ресурсы: базу данных, брокер, внешние API. Molecule объединяется с Docker-композицией и другими сервисами, чтобы проверить взаимосвязь:

platforms:
  - name: app
    image: centos:stream8
    networks:
      - name: shared-net

• PostgreSQL/Redis поднимаются как отдельные контейнеры в той же сети — роль подключается по имени сервиса.
• Внешние вызовы изолируются фикстурами, но настоящий интеграционный прогон полезен перед релизом.
• Прописывай зависимости через ansible.extra_vars (адреса, порты) — так сценарий остаётся переиспользуемым.

16. Pre-commit и линтеры до прогона

Быстрая проверка до «тяжёлого» прогона экономит циклы CI: синтаксис и стиль ловятся за секунды, а не минуты контейнера. Pre-commit запускает хуки локально в момент коммита:

pre-commit run --all-files  # прогнать все хуки
pre-commit autoupdate        # обновить версии хуков

• Хук ansible-lint режет стиль и риск до того, как роль поедет в сценарий.
• yamllint ловит отступы и дублирующиеся ключи в molecule.yml.
• Комбинация в .pre-commit-config.yaml — локальные и внешние хуки вперемешку.

17. Отладка неудачных прогонов

Сломанная роль не всегда видна по первому логу. Отладка — это последовательная изоляция слоёв: сначала провайдер, затем роли, затем проверки:

molecule login -s default   # войти в контейнер
molecule converge            # повторить приложение (без конвергенции)

• molecule login работает всегда — даже после сбоя: можно зайти внутрь и разобраться вручную.
• Выполняй команды внутри контейнера тем же путём, что и роль — так проверишь idempotence.
• Падает именно проверка — смотри verify изолированно через molecule verify.

Что дальше

Углубляйся в Ansible, научись писать роли, затем добавь Terraform для инфраструктуры и Docker для окружений. Обзор всех курсов — на главной странице.

← Вернуться к курсам