Руководство по Module Helper

Быстрый старт

См. пример из документации Ansible, написанный с использованием ModuleHelper. Но имейте в виду, что в нём представлены не все возможности MH:

from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper


class MyTest(ModuleHelper):
    module = dict(
        argument_spec=dict(
            name=dict(type='str', required=True),
            new=dict(type='bool', required=False, default=False),
        ),
        supports_check_mode=True,
    )

    def __run__(self):
        self.vars.original_message = ''
        self.vars.message = ''
        if self.check_mode:
            return
        self.vars.original_message = self.vars.name
        self.vars.message = 'goodbye'
        self.changed = self.vars['new']
        if self.vars.name == "fail me":
            self.do_raise("You requested this to fail")


def main():
    MyTest.execute()


if __name__ == '__main__':
    main()

Введение

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

from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper


class MyTest(ModuleHelper):
    # behavior for module paramaters ONLY, see below for further information
    output_params = ()
    change_params = ()
    diff_params = ()
    facts_params = ()

    facts_name = None   # used if generating facts, from parameters or otherwise

    module = dict(
        argument_spec=dict(...),
        # ...
    )

После импорта класса ModuleHelper необходимо объявить собственный класс, расширяющий его.

Проще всего задать модуль, создав переменную класса module со словарём, содержащим точные аргументы, которые будут переданы в качестве параметров в AnsibleModule. Если вы предпочитаете самостоятельно создавать объект AnsibleModule, просто присвойте его переменной класса module. MH также принимает параметр module в конструкторе. Если этот параметр используется, он переопределяет переменную класса. Параметр также может быть типа dict или AnsibleModule.

Помимо определения модуля, можно использовать другие переменные для управления поведением MH. Эти переменные следует задавать в самом начале класса; их назначение объясняется в этом документе.

Основная логика MH выполняется в методе ModuleHelper.run(), который выглядит так:

@module_fails_on_exception
def run(self):
    self.__init_module__()
    self.__run__()
    self.__quit_module__()
    output = self.output
    if 'failed' not in output:
        output['failed'] = False
    self.module.exit_json(changed=self.has_changed(), **output)

Модуль должен реализовать метод ModuleHelper.__run__(); большинство модулей смогут выполнять свои действия, реализовав только этот метод MH. Однако в некоторых случаях может понадобиться выполнить действия до или после основных задач. В таких случаях следует реализовать соответственно ModuleHelper.__init_module__() и ModuleHelper.__quit_module__().

Обратите внимание: результат формируется методом self.output, который является методом @property. По умолчанию это свойство собирает все переменные, помеченные для вывода, и возвращает их значения в словаре. Кроме того, стандартный self.output также обрабатывает facts Ansible и режим diff. Также обратите внимание: статус изменений формируется методом self.has_changed(), обычно вычисляемым на основе переменных, помеченных для отслеживания изменений их содержимого.

Пример из раздела Быстрый старт можно записать и так:

def __init_module__(self):
    self.vars.original_message = ''
    self.vars.message = ''

def __run__(self):
    if self.check_mode:
        return
    self.vars.original_message = self.vars.name
    self.vars.message = 'goodbye'
    self.changed = self.vars['new']

def __quit_module__(self):
    if self.vars.name == "fail me":
        self.do_raise("You requested this to fail")

Обратите внимание, что здесь нет вызовов module.exit_json() и module.fail_json(): если модуль завершается с ошибкой, выбросьте исключение. Для этого можно использовать вспомогательный метод self.do_raise() или выбросить исключение обычным способом в Python. Если исключение не выброшено, модуль считается успешно выполненным.

В модулях Ansible должна быть функция main() и стандартная проверка для '__main__'. При использовании MH это должно выглядеть так:

def main():
    MyTest.execute()


if __name__ == '__main__':
    main()

Метод класса execute() — это всего лишь сокращённая запись для:

m = MyTest()
m.run()

При необходимости в execute() можно передать параметр AnsibleModule.

Параметры, переменные и вывод

Все параметры автоматически становятся переменными в атрибуте self.vars, имеющем тип VarDict. Использование self.vars позволяет получить единый механизм доступа к параметрам, а также предоставить переменные в качестве возвращаемых значений модуля. Как описано в Руководстве по VarDict, с переменными в VarDict связаны метаданные. Один из атрибутов этих метаданных помечает переменную для вывода, и MH использует его для формирования возвращаемых значений модуля.

В отличие от новых переменных, созданных в VarDict, параметры модуля по умолчанию не включаются в вывод. Чтобы включить некоторые параметры модуля в вывод, перечислите их в переменной класса output_params.

class MyTest(ModuleHelper):
    output_params = ('state', 'name')
    ...

Ещё одна полезная функция MH, основанная на использовании VarDict, — автоматическое отслеживание изменений при установке метаданных change=True. Чтобы включить эту функцию для параметров модуля, снова перечислите их в переменной класса change_params.

class MyTest(ModuleHelper):
    # example from community.general.xfconf
    change_params = ('value', )
    ...

Аналогично, чтобы использовать режим diff Ansible, можно задать для параметров модуля метаданные diff=True и diff_params. В этом случае MH автоматически сформирует вывод diff для переменных, значения которых изменились.

class MyTest(ModuleHelper):
    diff_params = ('value', )

    def __run__(self):
        # example from community.general.gio_mime
        self.vars.set_meta("handler", initial_value=gio_mime_get(self.runner, self.vars.mime_type), diff=True, change=True)

Кроме того, если модуль должен возвращать факты, а не значения, используйте для параметров модуля метаданные fact=True и fact_params. Также необходимо указать facts_name, например:

class VolumeFacts(ModuleHelper):
    facts_name = 'volume_facts'

    def __init_module__(self):
        self.vars.set("volume", 123, fact=True)

В результате будет сформирован факт Ansible, например:

- name: Obtain volume facts
  some.collection.volume_facts:
    # parameters

- name: Print volume facts
  debug:
    msg: Volume fact is {{ ansible_facts.volume_facts.volume }}

Обработка изменений

В MH есть много способов указать на изменение при выполнении модуля. Рассмотрим их:

# using __init_module__() as example, it works the same in __run__() and __quit_module__()
def __init_module__(self):
    # example from community.general.ansible_galaxy_install
    self.vars.set("new_roles", {}, change=True)

    # example of "hidden" variable used only to track change in a value from community.general.gconftool2
    self.vars.set('_value', self.vars.previous_value, output=False, change=True)

    # enable change-tracking without assigning value
    self.vars.set_meta("new_roles", change=True)

    # if you must forcibly set an initial value to the variable
    self.vars.set_meta("new_roles", initial_value=[])
    ...

Исключения

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

from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelperException

def __init_module__(self):
    if not complex_validation():
        self.do_raise("Validation failed!")

    # Or passing output variables
    awesomeness = calculate_awesomeness()
    if awesomeness > 1000:
        self.do_raise("Over awesome, I cannot handle it!", update_output={"awesomeness": awesomeness})
        # which is just a convenience shortcut for
        raise ModuleHelperException("...", update_output={...})

Все исключения, производные от Exception, перехватываются и преобразуются в вызов fail_json(). Однако при необходимости можно самостоятельно вызвать self.module.fail_json() — это сработает, но имейте в виду, что в этом случае выходные переменные не будут обработаны автоматически.

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

Делегирование AnsibleModule

Перечисленные ниже свойства и методы MH без изменений делегируются базовому экземпляру AnsibleModule в self.module:

• check_mode
• get_bin_path()
• warn()
• deprecate()

Кроме того, MH также делегирует:

• diff_mode в self.module._diff
• verbosity в self.module._verbosity

Начиная с community.general 10.3.0, MH также делегирует метод debug в self.module. Если в каком-либо существующем модуле уже определён атрибут debug, появится предупреждение с просьбой переименовать его. Начиная с выпуска community.general 12.0.0 делегирование будет выполняться безусловно и переопределит любые существующие методы или свойства подклассов.

Декораторы

Следующие декораторы следует использовать только внутри класса ModuleHelper.

from ansible_collections.community.general.plugins.module_utils.module_helper import cause_changes

# adapted excerpt from the community.general.jira module
class JIRA(StateModuleHelper):
    @cause_changes(when="success")
    def operation_create(self):
        ...

from ansible_collections.community.general.plugins.module_utils.module_helper import check_mode_skip

# adapted excerpt from the community.general.locale_gen module
class LocaleGen(StateModuleHelper):
    @check_mode_skip
    def __state_fallback__(self):
        ...