Руководство для участников

README и другие файлы Markdown

Файлы Markdown (с расширением .md) можно найти в нескольких каталогах репозитория. Они предназначены главным образом для разработчиков и тех, кто просматривает репозиторий, и поясняют назначение или контекст других файлов поблизости.

Главное исключение — README.md в корневом каталоге репозитория. Этот файл важнее остальных, поскольку содержит вводную информацию и ссылки для всех, кто просматривает репозиторий, как на GitHub, так и на странице Ansible Galaxy коллекции.

Файлы Markdown можно просматривать прямо на GitHub, поэтому рецензентам легко их проверять, и для них не требуется запускать специальные тесты.

Ваша IDE или редактор кода также могут поддерживать предварительный просмотр этих файлов. Например, в Visual Studio Code есть встроенный предварительный просмотр Markdown.

Документация модулей и плагинов

Документация этого типа создается из структурированного YAML, заключенного в строку Python. Она размещается в том же коде, который описывает, либо в отдельном файле Python, например во фрагменте документации. Дополнительные сведения см. в рекомендациях по формату и документированию модулей.

Документация этого типа имеет строго заданную структуру и проверяется с помощью ansible-test sanity. Полные инструкции доступны на странице тестирования документации модулей.

Кроме того, при сборке сайта документации для запросов на включение изменений (или при локальной сборке) также включается документация модулей и плагинов. Подробности см. в следующем разделе.

Сайт документации коллекции

Сайт документации коллекции — это страница, которую вы читаете сейчас. Он написан в формате reStructuredText (RST) и опубликован на сайте Документации Ansible. Здесь размещается документация в развернутом формате, не подходящая для двух других категорий.

Если вы планируете добавить сюда совершенно новый документ, лучше сначала создать issue на GitHub, чтобы обсудить идею и оптимальную организацию материала.

При подготовке любых материалов для сайта документации коллекции руководствуйтесь руководством по стилю Ansible.

Файлы RST для сайта документации находятся в каталоге docs/docsite/rst/. Для некоторых изменений может также потребоваться отредактировать docs/docsite/extra-docs.yml.

После отправки запроса на включение изменений, затрагивающего документацию коллекции, будет создана новая версия сайта документации и опубликована на временном сайте, а бот оставит комментарий к запросу со ссылкой. Так вы сможете просмотреть отформатированную документацию и заметить возможные ошибки форматирования.

Также можно собрать документацию локально, установив дополнительные зависимости Python и запустив скрипт сборки:

$ pushd docs/preview
$ pip install -r requirements.txt
$ ./build.sh

Созданные HTML-файлы можно найти в docs/preview/build/html и открыть локально в браузере.

Интеграционные тесты

В отличие от других коллекций, для корректного запуска интеграционных тестов нам требуется файл integration_config.yml, поскольку тестам нужны внешние зависимости (например, сервер Vault) и они должны знать, где эти зависимости находятся.

Если вы раньше вносили вклад в эту коллекцию или в плагин поиска hashi_vault, возможно, вы помните, что по умолчанию интеграционные тесты загружали, распаковывали и запускали сервер Vault непосредственно во время тестирования. Этот устаревший режим больше недоступен.

$ pushd tests/integration/targets/setup_localenv_docker

$ pip install -r files/requirements/requirements.txt -c files/requirements/constraints.txt
$ ansible-galaxy collection install -r files/requirements/requirements.yml

$ ./setup.sh

$ popd
$ ansible-test integration --docker default --docker-network hashi_vault_default -v

Расположение и область действия файла

Методы аутентификации реализованы в виде классов в module_utils, в файле с именем plugins/module_utils/_auth_method_<method_name>.py. Начальное подчеркивание указывает, что утилита модуля является внутренней для коллекции и не предназначена для использования за ее пределами. Это позволяет при необходимости вносить изменения без выпуска новой основной версии и ясно показывает потенциальным пользователям нижестоящих проектов, что им не следует полагаться на эти утилиты за пределами содержимого коллекции.

Кроме того, во всех утилитах модулей для методов аутентификации в коллекции должен быть комментарий с таким пояснением, например:

# FOR INTERNAL COLLECTION USE ONLY
# The interfaces in this file are meant for use within the community.hashi_vault collection
# and may not remain stable to outside uses. Changes may be made in ANY release, even a bugfix release.
# See also: https://github.com/ansible/community/issues/539#issuecomment-780839686
# Please open an issue if you have questions about this.

Чтобы понять, как реализуются методы аутентификации, лучше всего изучить существующие методы аутентификации.

Структура класса

Имя каждого класса метода аутентификации должно иметь вид HashiVaultAuthMethod<MethodName>, а сам класс должен наследоваться от HashiVaultAuthMethodBase.

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

Метод аутентификации должен вызывать функцию базового класса __init__.

Необходимо реализовать два метода:

• validate() — этот метод делает все возможное, чтобы обеспечить выполнение требований для аутентификации с помощью данного метода. Это может включать проверку обязательных параметров, проверку их значений, получение дополнительной информации и контекста из среды, подготовку этой информации для использования в authenticate() и т. д. Как правило, он не должен обращаться к Vault и должен по возможности не зависеть от внешних источников и служб, однако это лишь рекомендация, а конкретные требования зависят от особенностей рассматриваемого метода аутентификации. validate() вызывает исключение, если проверка завершается неудачей. В случае успеха метод ничего не возвращает.
• authenticate(client, use_token=False) — этот метод выполняет собственно аутентификацию и возвращает результат API аутентификации (включая токен, сведения об аренде и т. д.). Ему передается объект клиента HVAC, а также необязательный параметр use_token, который указывает, нужно ли установить в поле токена клиента результат аутентификации (обычно это требуется).

В классе метода аутентификации также должны быть два поля:

• NAME — имя метода аутентификации.
• OPTIONS — список имен всех параметров, которые могут использоваться методом аутентификации, включая необязательные; этот список не должен содержать параметр auth_method.

Генерация исключений и предупреждений

Поскольку методы аутентификации используются как модулями Ansible, так и плагинами Ansible, любое генерируемое исключение должно подходить для обоих типов компонентов. При необходимости можно генерировать стандартные исключения Python, например KeyError.

В случаях, когда обычно используется AnsibleError (в плагинах) или вызывается module.fail_json() (в модулях), можно вызвать HashiVaultValueError с сообщением об ошибке. Плагины и модули этой коллекции должны обрабатывать этот тип соответствующим образом.

То же относится к предупреждениям: поскольку плагины и модули реализуют их по-разному, код утилит модуля, которому нужно вывести предупреждение, принимает функцию обратного вызова. Это также относится к методам аутентификации.

Базовый класс предоставляет метод warn(), который вызывает функцию обратного вызова, указанную при инициализации класса, поэтому в коде метода аутентификации можно просто использовать self.warn().

Доступ к параметрам

Поскольку методы аутентификации используются и модулями Ansible, и плагинами Ansible, которые получают доступ к параметрам по-разному, в этой коллекции реализован класс HashiVaultOptionAdapter. Он предоставляет единый интерфейс для доступа к значениям параметров в коде, который должен работать и в плагинах, и в модулях.

В нем реализованы следующие методы:

• get_option(key) — получает параметр с указанным именем. Если параметр отсутствует, вызывает KeyError.
• get_option_default(key, default=None) — получает параметр с указанным именем. Если параметр отсутствует, возвращает значение default.
• set_option(key, value) — устанавливает значение указанного параметра key в value.
• set_option_default(key, default=None) — возвращает значение параметра key. Если ключ отсутствует, устанавливает для него значение default и возвращает это значение.
• has_option(key) — возвращает True, если указанный параметр присутствует (значение None считается присутствующим).
• set_options(**kwargs) — устанавливает параметры в соответствии с парами «ключ/значение», указанными в kwargs.
• get_options(*args) — возвращает словарь с именами параметров, указанными в args.
• get_filtered_options(filter, *args) — возвращает словарь с именами параметров, указанными в args, если вызываемый объект filter (которому передаются key и value) возвращает True для данной пары «ключ/значение».
• get_filled_options(*args) — возвращает словарь с именами параметров, указанными в *args, значения которых не равны None.

Аутентификатор

Большая часть содержимого коллекции будет использовать для аутентификации класс HashiVaultAuthenticator, а не обращаться напрямую к каждому отдельному методу аутентификации. Поэтому при добавлении нового метода аутентификации необходимо изменять _authenticator.py, поскольку этот класс импортирует и напрямую использует каждый класс метода. Чтобы найти места, требующие изменений, изучите реализацию этого класса.

Параметры и документация метода аутентификации

Поскольку методы аутентификации используются совместно содержимым коллекции, их параметры документируются в плагинах doc_fragment. Многие параметры используются в нескольких методах аутентификации (например, role_id, username, password), поэтому для каждого метода не создается отдельный фрагмент документации: это привело бы к дублированию описаний параметров.

Вместо этого все параметры методов аутентификации находятся в plugins/doc_fragments/auth.py.

Этот файл содержит стандартное поле DOCUMENTATION, а также поле PLUGINS. Такое разделение необходимо, поскольку некоторые части документации применимы только к плагинам, а именно записи env, ini и vars.

DOCUMENTATION должно содержать все поля, общие для обоих типов компонентов, такие как description, type, version_added, required и т. д., а все специфичное для плагинов следует помещать в PLUGINS.

Поскольку плагины и модули ссылаются на фрагменты документации, обычно нет необходимости изменять строки документации непосредственно в содержимом; если такая необходимость возникнет, создайте issue для обсуждения.

По возможности следует предоставлять варианты env, ini и vars для задания параметров, чтобы обеспечить максимальную гибкость плагинов. Иногда такие варианты не имеют смысла, например, когда требуется указать token (конфиденциальное значение) в ini.

Решая, добавлять ли новые параметры для метода аутентификации, подумайте, можно ли и нужно ли повторно использовать существующие. Если требуется новый параметр, рассмотрите возможность включить в его имя название метода аутентификации, чтобы отличать его от существующих или будущих параметров, которые могут вызвать путаницу в другом контексте.

Например, имена cert_auth_public_key и cert_auth_private_key были выбраны, чтобы их не путали с другими параметрами сертификатов, относящимися к подключению Vault, или с параметрами в других контекстах, где конкретным плагинам или модулям могут потребоваться пары ключей.

Тестирование методов аутентификации

Поскольку методы аутентификации используются во всей коллекции, мы стремимся тщательно их тестировать. Для методов аутентификации предусмотрены как модульные, так и интеграционные тесты; в совокупности они должны обеспечивать высокую уверенность в том, что методы работают должным образом.

flags:
  target_auth_aws_iam:
    paths:
      - plugins/module_utils/_auth_method_aws_iam.py