Вклад вашего модуля в Ansible

Модули высокого качества с минимальными зависимостями могут быть включены в Ansible, но модули (просто из-за предпочтений разработчиков в программировании) должны быть реализованы на Python и использовать общий код AnsibleModule, а также должны в целом использовать согласованные аргументы с остальной частью программы. Обратитесь в список рассылки, чтобы узнать о требованиях, если хотите, и отправьте запрос на получение изменений в проект ansible. Включенные модули будут поставляться с Ansible и также имеют возможность быть повышены до статуса «ядра», что дает им немного более высокий приоритет разработки (хотя они будут работать точно так же).

Список проверок для вклада модулей

Следующие пункты списка проверок являются важными рекомендациями для тех, кто хочет внести вклад в разработку модулей для Ansible в GitHub. Прочитайте эти рекомендации перед отправкой вашего PR/предложения.

• Символ шебанга всегда должен быть #!/usr/bin/python. Это позволяет ansible_python_interpreter работать
• Модули должны быть написаны для поддержки Python 2.6. Если это невозможно, минимальная необходимая версия Python и обоснование должны быть объяснены в разделе требований в DOCUMENTATION. В Ansible-2.3 минимальное требование к модулям составляло Python-2.4.
• Модули должны быть написаны с использованием правильного синтаксиса Python-3. В какой-то момент в будущем мы разработаем правила для работы с Python-3, но пока этого нет. Обратитесь к Ansible и Python 3 за помощью по выполнению этой задачи.
• Модули должны иметь раздел метаданных. Для подавляющего большинства новых модулей метаданные должны выглядеть точно так же:

ANSIBLE_METADATA = {'status': ['preview'],
                    'supported_by': 'community',
                    'metadata_version': '1.1'}

Полная спецификация метаданных модуля находится здесь: Блок метаданных Ansible

• Документация: убедитесь, что она существует

  • Документация по модулю должна кратко и точно определять, что делает каждый модуль и параметр, и как он работает с другими в базовой системе. Документация должна быть написана для широкой аудитории – читаемая как специалистами, так и непрофессионалами. Эта документация не предназначена для обучения абсолютного новичка, но она также не должна быть предназначена только для посвященных (нужно найти баланс).
  • Описание должно всегда начинаться с заглавной буквы и заканчиваться точкой. Согласованность всегда полезна.
  • Настройка required требуется только в случае истины, в противном случае предполагается ложь.
  • Если required ложно/отсутствует, default может быть указано (предполагается «null», если отсутствует). Убедитесь, что параметр по умолчанию в документации соответствует параметру по умолчанию в коде.
  • Документирование default не требуется для required: true.
  • Удалите ненужные документы, такие как aliases: [] или choices: [].
  • Не используйте булевы значения в списке выбора. Например, в списке choices: [‘no’, ‘verify’, ‘always], «нет» будет интерпретироваться как булево значение (вы можете проверить константы BOOLEANS_* в basic.py, чтобы увидеть полный список ключевых слов булевых значений). Если ваш параметр действительно является булевым, просто используйте type=bool; нет необходимости заполнять «choices».
  • Для новых модулей или параметров в модуле добавьте version_added. Версия должна соответствовать значению текущей версии разработки и является строкой (а не числом с плавающей точкой), поэтому обязательно заключите её в кавычки.
  • Проверьте, что аргументы в документации и словаре спецификаций модуля идентичны.
  • Для паролей/секретных аргументов должно быть установлено no_log=True.
  • Требования должны быть задокументированы, используя поле requirements=[].
  • Автор должен быть указан, с его именем и идентификатором GitHub, как минимум.
  • Убедитесь, что вы используете U() для URL-адресов, I() для имён параметров, C() для файлов и значений параметров, M() для имён модулей.
  • Если необязательный параметр иногда требуется, это должно быть отражено в документации, например, «Требуется при C(state=present)».
  • Проверьте, что включён заголовок лицензии GPL 3.
  • Использует ли модуль режим проверки? Может ли он быть изменён для его использования? Документируйте это. Документация – друг каждого.
  • Примеры – включайте их, когда это возможно, и убедитесь, что они воспроизводимы.
  • Документируйте структуру возвращаемых значений модуля. Обратитесь к Общие и Документирование вашего модуля для получения дополнительной информации.

• Предсказуемый пользовательский интерфейс: Этот раздел особенно важен, так как это также область, в которой нам нужны существенные улучшения.

  • Согласованность имён по всем модулям (мы стали лучше в этом, но у нас всё ещё есть отклонения).
  • Декларативное действие (а не CRUD) – это упрощает пользователю не заботиться о том, какое состояние существует, а только о конечном состоянии. started/stopped, present/absent – не перегружайте параметры слишком сильно. Предпочтительно добавлять новый, простой параметр, чем добавлять варианты/состояния, которые не подходят к существующим.
  • Держите параметры маленькими, использование ими больших структур данных может сэкономить нам несколько задач, но добавляет сложное требование, которое мы не можем легко проверить перед передачей модулю.
  • Разрешите «экспертный режим». Это может показаться абсолютной противоположностью предыдущему, но всегда лучше позволить опытным пользователям работать со сложными данными. В некоторых случаях это требует разных модулей, так что у вас в итоге будет один (1) экспертный модуль и несколько «раздельных» (ec2_vpc_net?). Причина в том, что многие пользователи считают, что это позволяет выполнять одну задачу и сохраняет задания небольшими (что просто перемещает сложность данных в файлы vars, оставляя у вас немного другой структуру в другом файле YAML). Однако это позволяет более «атомной» операции над базовыми API и службами.

• Информативные ответы: Обратите внимание, что для >= 2.0 требуется документирование возвращаемых данных.

  • Всегда возвращайте полезные данные, даже если изменений нет.
  • Будьте последовательны в возвращаемых значениях (некоторые модули слишком случайны), за исключением случаев, когда это вредно для состояния/действия.
  • Делайте возвращаемые значения повторно используемыми – в большинстве случаев вы не хотите их читать, но вы хотите обработать их и использовать повторно.
  • Возвращайте разницу, если режим разницы включён. Это не требуется для всех модулей, так как это не будет иметь смысла для определённых модулей, но пожалуйста, попытайтесь включить это, когда это уместно).

• Код: Это относится ко всему коду в целом, но часто кажется отсутствующим в модулях, поэтому, пожалуйста, имейте это в виду во время работы.

  • Проводите проверку заранее – быстро завершайте и возвращайте полезные и понятные сообщения об ошибках.
  • Защищённое программирование – модули должны быть спроектированы достаточно просто, чтобы это было легко. Модули всегда должны обрабатывать ошибки корректно и избегать прямых трассировок стека. Ansible справляется с этим лучше в версии 2.0 и возвращает их в результатах.
  • Предсказуемое завершение – если мы должны завершить работу с ошибкой, сделайте это предсказуемым способом. Либо имитируйте поведение базового инструмента, либо общий способ работы системы.
  • Модули не должны выполнять работу других модулей, для этого предназначены роли. Меньше волшебства – лучше.
  • Не изобретайте велосипед. Часть проблемы в том, что совместное использование кода не так просто и не задокументировано, нам также нужно расширить наши базовые функции, чтобы предоставить общие шаблоны (повторные операции, ограничение скорости и т.д.).
  • Поддержка режима проверки. Это не требуется для всех модулей, так как это не будет иметь смысла для определённых модулей, но пожалуйста, попытайтесь включить это, когда это уместно). Для получения дополнительной информации обратитесь к Проверка режима как тест на отклонение и Режим проверки («сухой запуск»).

• Исключения: Модуль должен обрабатывать их. (Исключения – это ошибки)

  • Предоставляйте полезные сообщения о том, что вы делали, и вы можете добавить сообщение об исключении к этому.
  • Избегайте общих обработчиков исключений, они не очень полезны, за исключением случаев, когда базовый API предоставляет очень хорошие сообщения об ошибках, относящиеся к попытке действия.

• Рекомендации, зависящие от модуля: Могут существовать дополнительные рекомендации для определённых семейств модулей.

  • Убедитесь, что вы проверили сами модули для получения дополнительной информации.

    • Amazon

  • Модули должны использовать «extends_documentation_fragment», чтобы обеспечить доступность документации. Например, модуль AWS должен включать:

    extends_documentation_fragment:
        - aws
        - ec2
    

• Модуль не должен использовать sys.exit() –> используйте fail_json() из объекта модуля.
• Импортируйте пользовательские пакеты в try/except и обрабатывайте их с помощью fail_json() в main(), например

try:
    import foo
    HAS_LIB=True
except:
    HAS_LIB=False

• Структура возвращаемых значений должна быть согласованной, даже если NA/None используются для ключей, обычно возвращаемых при других параметрах.
• Являются ли действия модуля идемпотентными? Если нет, документируйте это в описаниях или примечаниях.
• Импортируйте ansible.module_utils код в том же месте, что и другие библиотеки. В более старом коде это делалось в конце файла, но это больше не нужно.
• Не используйте подстановочные знаки для импорта других модулей Python (например: from ansible.module_utils.basic import *). Это раньше требовалось для кода, импортированного из ansible.module_utils, но начиная с Ansible-2.1, это просто устаревший и плохой подход.
• Модуль должен иметь функцию main, которая оборачивает обычное выполнение.
• Вызывайте вашу main() из условного оператора, чтобы в будущем было возможно их импортировать в модульные тесты, например

if __name__ == '__main__':
    main()

• Попробуйте нормализовать параметры с другими модулями, вы можете иметь псевдонимы, когда пользователь более знаком с именем базового API для опции
• Соблюдение PEP 8 является обязательным. Смотрите PEP 8 для получения дополнительной информации.
• Избегайте «action/command», они императивны, а не декларативны, есть и другие способы выразить то же самое
• Не добавляйте list или info состояния опций в существующий модуль — создайте новый _facts модуль.
• Если вы спрашиваете «как заставить модуль выполнять другие модули»… вам нужно написать роль
• Значения возврата должны быть сериализуемы в формате json с помощью стандартной библиотеки json Python. Базовые типы Python (строки, целые числа, словари, списки и т. д.) подлежат сериализации. Распространённая ошибка — попытка вернуть объект через exit_json(). Вместо этого преобразуйте необходимые поля из объекта в поля словаря и верните словарь.
• При получении URL-адресов используйте либо fetch_url, либо open_url из ansible.module_utils.urls, а не urllib2; urllib2 не проверяет сертификаты TLS по умолчанию и поэтому небезопасен для https.
• Модули фактов должны возвращать факты в поле ansible_facts словаря результатов. module_provided_facts
• Модули, которые предназначены только для сбора фактов, должны реализовывать check_mode. Они не должны вызывать никаких изменений, поэтому достаточно добавить check_mode=True при создании AnsibleModule. (Причина в том, что плейбуки, которые условно зависят от информации о фактах, будут корректно условны в check_mode только в том случае, если факты возвращаются в check_mode).
• Основная аутентификация: module_utils.api содержит некоторые вспомогательные функции для выполнения основной аутентификации с помощью module_utils.urls.fetch_url(). Если вы используете их, вам, возможно, захочется обратиться к переменным среды для значений по умолчанию. Если вы это сделаете, обязательно используйте необобщённые переменные среды (например, API_<MODULENAME>_USERNAME). Использование обобщённых переменных среды, таких как API_USERNAME, приведёт к конфликту между модулями.

Список проверок для модулей Windows

Для получения списка проверок и подробной информации о написании модулей Windows, см. Инструкцию по разработке модулей Ansible для Windows

Устаревание и создание псевдонимов модулей

Начиная с версии 1.8, вы можете сделать модули устаревшими, переименовав их с помощью префикса _, например, old_cloud.py в _old_cloud.py. Это сохраняет модуль доступным, но скрывает его из основных документов и списка.

При устаревании модуля:

1. Установите ANSIBLE_METADATA status в deprecated.

2. В разделе DOCUMENTATION, добавьте поле deprecated, подобное:

   deprecated: Deprecated in 2.3. Use M(whatmoduletouseinstead) instead.
   

3. Добавьте информацию об устаревании в CHANGELOG.md в разделе ###Deprecations:.

Псевдонимы имён модулей

Вы также можете переименовать модули и сохранить псевдоним старого имени, используя символическую ссылку, которая начинается с _. Этот пример позволяет вызывать модуль stat как fileinfo, что делает следующие примеры эквивалентными:

EXAMPLES = '''
ln -s stat.py _fileinfo.py
ansible -m stat -a "path=/tmp" localhost
ansible -m fileinfo -a "path=/tmp" localhost
'''