В апреле 2023 года разработчики Molecule представили мажорный релиз инструмента в версии 5.0.0.  Помимо множества багфиксов и улучшений различной степени важности, пользователи получили возможность написать свой собственный драйвер, подключить его в уже существующие сценарии тестирования ролей и использовать как molecule.docker или molecule.openstack. Я не нашел или плохо искал статей об этом и решил написать поэтапное руководство по разработке собственного драйвера — от примитивного «Hello world» до работающего прототипа. В статье вы найдете пример custom_docker доработки оригинального драйвера molecule.docker,  описание базовых классов и методов из API Molecule, а также рассказ о нюансах разработки и эксплуатации, с которыми я столкнулся.  В YADRO мы проводим тестирование ролей и наработок с использованием виртуальных машин. Однако перед созданием ВМ для тестирования роли нам нужно выполнить ряд проверок: подготовить XML-шаблоны, изменить диски. У стандартных драйверов недостаточный для нас функционал, есть вопросы к гибкости и скорости работы. Все это делает невозможным использование стандартных драйверов вроде molecule.libvirt. До релиза 5.0.0 структура сценария внутри наших ролей выглядела следующим образом: Помимо файлов molecule, converge и verify, в сценарии хранилась вся дополнительная информация для создания платформы: задачи, шаблоны, плейбуки. Пока не было необходимости менять метод для создания виртуальной машины, все эти файлы оставались без исправлений и копировались из роли в роль, из сценария в сценарий. Это вызывало ряд проблем — как повседневных, так и гипотетических: Для создания новой роли инженеру надо было копировать структуру — вручную или с использованием сторонних инструментов. Повышался порог вхождения. Новоприбывший инженер получал ворох дополнительных файлов, в большинстве случаев с фразой: «Это служебное, менять вряд ли понадобится». Но, если ему встречался какой-то баг, это увеличивало время решения задачи: надо было долго разбираться самому или идти к автору кода. Если мы хотели изменить подход к созданию платформы, приходилось менять все существующие сценарии вручную — например, в какой-то момент пришлось вносить правки в XML-шаблон виртуальной машины. И получалось, что где-то все создавалось со старым шаблоном, где-то — с новым. Копировать файлы вручную — сложно и муторно. Делать форки одного репозитория — создавать неразбериху в Git-дереве. Я решил скрыть логику создания платформы от конечного пользователя и начал изучать внутреннее устройство Molecule, чтобы найти способ создания собственного драйвера. Чтобы решить эту задачу для Molecule до версии 5.0.0, нужно было заморочиться. Имя любого драйвера, который мы хотим использовать, должно указываться в JSON-схеме в репозитории Molecule. Поэтому мы должны были не просто описать логику создания и удаления площадкой, но и склонировать репозиторий Molecule, чтобы исправить файл JSON-схемы. А затем хранить локально копии двух репозиториев. После релиза 5.0.0 этап с клонированием можно пропустить. Если имя кастомного драйвера соответствует одному из указанных шаблонов — molecule-*, molecule_*, custom-* или custom_*, то он автоматически становится доступным для использования. Это позволило нам уменьшить структуру внутри сценария до желаемой: Теперь я расскажу, как писал такой драйвер. Но сначала — немного подготовки. Для простоты будем делать прототип драйвера для работы с Docker. Это позволит раскрыть почти все тонкости работы Molecule-драйверов. В статье будут упоминаться две директории — molecule_custom_docker и hello_world. Внутри первой будет храниться исходный код для кастомного драйвера, во второй — простая Ansible-роль, которая для тестов Molecule будет использовать новый драйвер. Содержимое роли hello_world: hello_world/tasks/main.yml Для написания драйвера необходим Python не старее версии 3.10 и Molecule от версии 5.0.1 и выше. Также понадобятся базовые знания Ansible. Так как плагин будет работать с Docker, необходимо обеспечить безрутовый доступ для команд. Информацию по настройке можно найти на официальной странице Docker. Разработку можно разделить на несколько этапов: Создать скелет проекта внутри molecule_custom_driver, настроить сборку Python-пакета. Добавить логику для создания платформ через драйвер custom_docker. Добавить поддержку команд molecule create и molecule destroy. Реализовать механизмы для выполнения команд molecule converge и molecule login. Поехали!  Инициализируем пустой репозиторий в директории molecule_custom_docker, создадим скелет проекта для драйвера: Опишем базовый класс нашего драйвера, который наследуется от класса molecule.api.Driver, переопределим конструктор. Создадим геттеры и сеттеры для поля _name. Без этого Molecule не сможет получать информацию о кастомном драйвере: src/molecule_custom_docker/driver.py За основу для служебных файлов pyproject.toml и setup.cfg возьмем существующие в molecule_docker: setup.cfg pyproject.toml После добавления TOML и CFG-файлов код драйвера можно упаковать в Python-пакет, а сам драйвер custom_docker становится допустимым для использования в Molecule. Проверим: Проверим возможность создания сценария: Ошибка говорит о том, что Molecule не может найти директорию шаблона и ищет этот шаблон в подкаталоге cookiecutter. CookieCutter — это библиотека и CLI-утилита, которая позволяет создавать проекты из шаблонов, используя Jinja2-шаблоны под капотом. CookieCutter-шаблоном является директория или репозиторий, где на верхнем уровне располагается файл cookiecutter.json — конфигурационный файл. Директория с конфигурационным файлом называется корнем шаблона. Внутри конфигурационного файла описываются правила генерации, подключаются дополнительные модули, а также перечисляются переменные, которые могут быть использованы не только внутри файлов, но и для имен файлов и каталогов шаблона. Обращение к переменным возможно через использование префикса cookiecutter: {{ cookiecutter.<variable_name> }}. Создадим шаблон CookieCutter для драйвера: В конфигурационном файле cookiecutter.json инициализируем следующие переменные: src/molecule_custom_docker/cookiecutter/cookiecutter.json После инициализации переменных, при вызове генерации через CookieCutter, все строки вида "{{ cookiecutter.molecule_directory }}" будут заменены на "molecule", "{{ cookiecuter.dependency_name }}" на "OVERRIDDEN" и так далее. Значение "OVERRIDDEN" не является служебным. Оно используется для обозначения тех полей, которые будут перезаписаны при вызове CookieCutter из Molecule. Конкретные значения будут вычислены динамически на основе флагов, переданных команде molecule init scenario. Например, значение dependency_name будет взято из флага --dependency-name, driver_name — из флага --driver-name. Напрямую, без указания в cookiecutter.json, значения из Molecule невозможно использовать в CookieCutter-шаблоне. Добавим необходимые директории и файлы в корень шаблона: Проверим возможность создания сценариев с использованием шаблонов: Рассмотрим сценарий default. Внутри содержатся два файла: конфигурационный файл сценария Molecule, а также плейбук для проверки. molecule/default/molecule.yml Данный файл создался на основе полей из команды molecule init scenario и шаблона в основном репозитории Molecule. Добавим собственные шаблоны для файлов внутри директории сценария. Они будут доступны для редактирования пользователем.  src/molecule_custom_docker/cookiecutter/{{cookiecutter.molecule_directory}}/{{cookiecutter.scenario_name}}/molecule.yml src/molecule_custom_docker/cookiecutter/{{cookiecutter.molecule_directory}}/{{cookiecutter.scenario_name}}/converge.yml Создадим сценарий test_c, который будет использовать плагин custom_docker и собственный шаблон: Для проверки работы команд molecule create и molecule destroy добавим плейбуки create.yml, destroy.yml. При инициализации сценария они не будут отображаться. Плейбуки должны располагаться в директории playbooks: src/molecule_custom_docker/playbooks/create.yml src/molecule_custom_docker/playbooks/destroy.yml Проверим создание и удаление платформ в сценарии test_c: Ошибка возникает на задаче удаления файлов из временной директории сценария. По умолчанию список сохраняемых файлов не инициализирован, что вызывает ошибку при соединении списков. Избавимся от ошибки, переопределив метод default_safe_files: src/molecule_custom_docker/driver.py После исправления файла driver.py удаление платформ проходит без ошибок. Реализуем создание и удаление Docker-контейнеров в плейбуках create и destroy соответственно: src/molecule_custom_docker/playbooks/create.yml  src/molecule_custom_docker/playbooks/destroy.yml  Для создания контейнеров используется коллекция community.docker, которая может не существовать у конечного пользователя. Чтобы определить коллекцию как Ansible-зависимость драйвера, переопределим метод required_collections: src/molecule_custom_docker/driver.py Версия коллекции, указываемая в этой функции, является минимально допустимой. Все Ansible-зависимости драйвера устанавливаются на этапе dependency при выполнении сценария. Проверим получение зависимостей и создание платформы для сценария test_c: Вывод аналогичен и для удаления платформ. На данный момент команды molecule create и molecule destroy выполняются без ошибок. Структура пакета выглядит следующим образом: Проверим возможность «прогона» роли hello_wolrd на платформе сценария test_c: По умолчанию Molecule будет пытаться подключиться к созданным платформам через SSH. Изменим это поведение, переопределив метод ansible_connections_options, где сменим плагин для подключения с SSH на community.docker.docker: src/molecule_custom_docker/driver.py После добавления converge на хостах выполняется успешно: Ура! Создаваемые драйвером платформы стали доступны для тестирования. Каждый драйвер Molecule позволяет пользователю зайти на созданную платформу, и custom_docker не должен отличаться. Поддержка этих функций также настраивается в driver.py путем переопределения методов login_options и login_cmd_template. Первая отвечает за добавление опций к подключению, вторая должна возвращать шаблон строки, куда будут добавлены данные для подключения. src/molecule_custom_docker/driver.py Переменная instance будет добавлена из словаря от функции login_options, columns и lines — из Molecule напрямую. Все ключи, указанные в login_options, доступны для использования внутри login_cmd_template. Обе функции отвечают за работоспособность команды molecule login. Проверим возможность подключения для сущностей из сценария test_c: Итог: теперь драйвер поддерживает команду molecule_login. В случаях, когда значения параметров создаваемой платформы определяются на этапе инициализации, следует использовать отдельный конфигурационный файл. Изменим логику таким образом, чтобы для команды login использовался ID контейнера, а не его имя. Доработаем плейбук создания платформы. Добавим задачи поиска ID, а также генерации конфига в конец плейбука: src/molecule_custom_docker/playbooks/create.yml Теперь при выполнении команды molecule create будет генерироваться файл ~/.cache/molecule/<role_name>/<scenario_name>/instance_config.yml , в котором есть список словарей, содержащих информацию о созданных платформах. ~/.cache/molecule/hello_world/test_c/instance_config.yml Значение для ключа ID вычисляется в ходе работы Ansible-плейбука и недоступно для использования внутри Python-кода. Путь до файла instance_config.yml доступен в свойстве Driver._config.driver.instance_config. Доработаем драйвер, чтобы при molecule login использовался ID контейнера: src/molecule_custom_docker/driver.py Итог: при вызове команды molecule login будет использоваться значение из файла с информацией о платформе. Дальше нас ждет почти бесконечный цикл внедрения новых фич и оптимизации уже написанного кода. В процессе дальнейшей разработки и эксплуатации я призываю помнить, что: Окружение пользователя может отличаться. Рано или поздно возникнет пользователь, у которого нет даже базовых коллекций для работы Ansible или какой-либо библиотеки Python. Так было у нас. Следите за тем, что импортируется, запускается и загружается. Внутри драйвера используется библиотека Python? Укажите ее в зависимостях к пакету. Используются Ansible-модули, которые начинаются не с ansible.builtin? Добавьте коллекцию в required_collections. Лучше использовать временные директории. Вместо того чтобы формировать шаблоны для виртуальной машины через lookup-модуль, мы сохраняем сгенерированный файл во временную директорию. Это не раз спасало нас в ходе разработки и отладки новых фич для плагина.  README.md спасет вас от потока вопросов в чатах и почте. Например, мы с командой храним в стартовой документации информацию о том, как установить драйвер, какие пакеты нужны для корректной работы, как протестировать роль. Спасибо за внимание! Исходный код для molecule_custom_docker вы найдете в репозитории на GitHub. Тексты, которые могут вас заинтересовать:   → Как ограничить количество выполняющихся задач в Jenkins при вызове parallel: сравниваем решения → История печатных плат: от Эйслера до наших дней → Простые правила, которые помогают писать на Go без побочных эффектов