Руководство разработчика localenv
Роль «localenv» в этой коллекции устанавливает внешние зависимости, необходимые для запуска интеграционных тестов. Идея состоит в том, чтобы предоставить участнику проекта готовый способ настроить локальное окружение согласованным и воспроизводимым образом.
Примечание
Это руководство находится в процессе разработки и содержит очень мало подробностей. Пока что, если вы планируете создать новую роль localenv, лучше всего открыть issue в репозитории и обсудить это. Также может быть полезно ознакомиться с setup_localenv_docker — на сегодняшний день это наиболее полная роль.
Необходимые внешние зависимости
HashiCorp Vault
Для интеграционных тестов требуется сервер Vault. Рекомендуется использовать режим Dev-сервера Vault — это самый простой и быстрый способ запустить сервер.
Для наших целей необходим незашифрованный слушатель (обычный HTTP), поскольку большинство тестов предполагает подключение именно таким способом.
Чтобы запустить тесты, предназначенные для проверки доступа через TLS/HTTPS, необходимо запустить сервер Vault со слушателем, поддерживающим TLS. Нужно указать адрес и порт TLS, а также сертификат CA (или сам сертификат, если он самоподписанный).
Необходим корневой токен сервера Vault, поскольку интеграционные тесты изменяют конфигурацию Vault и предполагают, что этот токен доступен для выполнения таких действий. Можно позволить Vault сгенерировать токен при запуске, а затем получить его, но проще заранее создать токен и передать его Vault с помощью параметра -dev-root-token-id или переменной окружения VAULT_DEV_ROOT_TOKEN_ID (см. параметры Dev-режима).
Соответствующие переменные integration_config.yml
переменная | пример | описание |
|---|---|---|
|
| Полный URL HTTP вашего тестового сервера Vault. |
|
| Полный URL HTTPS вашего тестового сервера Vault. |
|
| Корневой токен, используемый для аутентификации в Vault. |
|
| Используемая версия Vault (обычно это значение задаётся ролью localenv, поэтому вручную установленное значение нигде не используется). |
|
| Открытый сертификат CA, подписавшего сертификат, используемый слушателем TLS Vault (или сам сертификат, если он самоподписанный). |
Прокси-сервер
Прокси-сервер используется для тестирования вариантов подключения через прокси.
Теоретически для этой цели подойдёт любой прокси-сервер, поддерживающий цели http/s, но рекомендуется tinyproxy: он, как следует из названия, небольшой, а также прост в настройке и запуске и доступен в пакетных менеджерах и контейнерах.
Соответствующие переменные integration_config.yml
переменная | пример | описание |
|---|---|---|
|
| Полный URL HTTP вашего прокси-сервера. |
Сервер MMock
MMock (сокращение от Monster Mock) — это HTTP-сервер, предназначенный для имитации ответов HTTP. Он также может прозрачно перенаправлять запросы на реальный сервер. Мы используем его как прокси для нашего тестового сервера Vault, перехватывая определённые вызовы API Vault и возвращая имитационные ответы.
Это полезно для интеграций с Vault, которые сложнее настроить в нашей среде CI.
Например, мы используем его для тестирования метода аутентификации aws_iam, поскольку у нас нет учётной записи AWS, которую можно было бы использовать, настроить и подключить к ней из GitHub CI.
В этих интеграционных тестах все обращения к Vault направляются в MMock, а не непосредственно в Vault. Мы заранее настраиваем MMock так, чтобы он отвечал на соответствующие вызовы, имитируя успешные ответы и ответы с ошибками реального сервера Vault.
Соответствующие переменные integration_config.yml
переменная | пример | описание |
|---|---|---|
|
| Полный URL HTTP сервера MMock. |
Соглашения для роли localenv
- Используйте
files/.outputдля хранения сгенерированных артефактов. - Всё сгенерированное должно находиться в
.gitignore; соответственно, этот процесс не должен перезаписывать или изменять содержимое, не находящееся в.gitignore. Иными словами, это не должно приводить к изменениям статуса git. - Рассмотрите возможность предоставления
setup.sh, чтобы не приходилось вручную выполнять командыansible-. В идеале он должен корректно работать независимо от текущего рабочего каталога. - Создайте пригодный к использованию
integration_config.yml, позволяющий использовать результат работы localenv. Создайте его в каталоге результатов роли, а не за его пределами. Скопируйте его в нужное место, но не перезаписывайте существующий файл. - Если у роли есть внешние зависимости, постарайтесь описать их в файлах, которые можно использовать с соответствующим инструментом, например
requirements.ymlдляansible-galaxyи т. д. - Роли localenv предназначены для запуска вне среды
ansible-test, однако они могут использовать другие роли повторно.
© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/hashi_vault/docsite/localenv_developer_guide.html
