Разработка плагинов

• Плагины обратного вызова
  • Примеры плагинов обратного вызова
  • Настройка плагинов обратного вызова
    • Управление stdout
  • Разработка плагинов обратного вызова
• Плагины подключения
• Плагины поиска
• Плагины переменных
• Плагины фильтров
• Плагины тестов
• Распространение плагинов

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

Доступны следующие типы плагинов:

• Плагины действий — это интерфейсы к модулям и могут выполнять действия на контроллере перед вызовом самих модулей.
• Плагины кэша используются для сохранения кэша «фактов», чтобы избежать дорогостоящих операций сбора фактов.
• Плагины обратного вызова позволяют подключиться к событиям Ansible для отображения или ведения журнала.
• Плагины подключения определяют способ связи с хостами инвентаризации.
• Плагины фильтров позволяют манипулировать данными внутри Ansible-игр и/или шаблонов. Это функция Jinja2; Ansible поставляется с дополнительными плагинами фильтров.
• Плагины поиска используются для извлечения данных из внешнего источника. Они реализуются с помощью пользовательской функции Jinja2.
• Плагины стратегии контролируют поток игры и логику выполнения.
• Плагины оболочки обрабатывают команды низкого уровня и форматирование для различных оболочек, которые Ansible может встретить на удаленных хостах.
• Плагины тестов позволяют проверять данные внутри Ansible-игр и/или шаблонов. Это функция Jinja2; Ansible поставляется с дополнительными плагинами тестов.
• Плагины переменных вводят дополнительные данные переменных в Ansible-запуски, которые не поступали из инвентаризации, книги сценариев или командной строки.

В этом разделе описываются различные типы плагинов и способы их реализации.

Плагины обратного вызова

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

Примеры плагинов обратного вызова

Ansible поставляется с рядом плагинов обратного вызова, которые вы можете изучить для примеров. Их можно найти в lib/ansible/plugins/callback.

Плагин обратного вызова log_plays — это пример того, как перехватывать события книги сценариев в файл журнала, а плагин обратного вызова mail отправляет электронные письма при завершении книги сценариев.

Предоставляемый плагин обратного вызова osx_say особенно интересен — он отвечает синтезированной речью компьютера на OS X в связи с событиями книги сценариев и гарантированно развлечет и/или раздражит коллег.

Настройка плагинов обратного вызова

Вы можете активировать пользовательский плагин обратного вызова, поместив его в папку callback_plugins рядом с вашим сценарием или внутри роли, или поместив его в один из источников каталога callback, настроенных в ansible.cfg.

Плагины загружаются в алфавитном порядке; например, плагин, реализованный в файле с именем 1_first.py будет выполняться перед файлом плагина с именем 2_second.py.

Большинство плагинов обратного вызова, поставляемых с Ansible, по умолчанию отключены и должны быть включены в ваш файл ansible.cfg для работы. Например:

#callback_whitelist = timer, mail, mycallbackplugin

Управление stdout

Вы можете иметь только один плагин в качестве основного менеджера консольного вывода. Если вы хотите заменить стандартный, вы должны определить CALLBACK_TYPE = stdout в подклассе, а затем настроить плагин stdout в ansible.cfg. Например:

#stdout_callback = mycallbackplugin

Разработка плагинов обратного вызова

Плагины обратного вызова создаются путем создания нового класса с классом Base(Callbacks) в качестве родительского класса:

from ansible.plugins.callback import CallbackBase
from ansible import constants as C

class CallbackModule(CallbackBase):
    pass

Оттуда переопределите определенные методы из CallbackBase, для которых вы хотите предоставить обратный вызов. Для плагинов, предназначенных для использования с Ansible версии 2.0 и выше, вы должны переопределять только методы, начинающиеся с v2. Полный список методов, которые вы можете переопределить, см. в __init__.py в каталоге lib/ansible/plugins/callback.

Следующий пример демонстрирует, как реализован плагин таймера Ansible:

# Make coding more python3-ish
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

from datetime import datetime

from ansible.plugins.callback import CallbackBase


class CallbackModule(CallbackBase):
    """
    This callback module tells you how long your plays ran for.
    """
    CALLBACK_VERSION = 2.0
    CALLBACK_TYPE = 'aggregate'
    CALLBACK_NAME = 'timer'
    CALLBACK_NEEDS_WHITELIST = True

    def __init__(self):

        super(CallbackModule, self).__init__()

        self.start_time = datetime.now()

    def days_hours_minutes_seconds(self, runtime):
        minutes = (runtime.seconds // 60) % 60
        r_seconds = runtime.seconds - (minutes * 60)
        return runtime.days, runtime.seconds // 3600, minutes, r_seconds

    def playbook_on_stats(self, stats):
        self.v2_playbook_on_stats(stats)

    def v2_playbook_on_stats(self, stats):
        end_time = datetime.now()
        runtime = end_time - self.start_time
        self._display.display("Playbook run took %s days, %s hours, %s minutes, %s seconds" % (self.days_hours_minutes_seconds(runtime)))

Обратите внимание, что определения CALLBACK_VERSION и CALLBACK_NAME необходимы для правильной работы плагинов для Ansible >=2.0.

Плагины подключения

По умолчанию Ansible поставляется с типом подключения «paramiko» SSH, встроенным ssh (просто «ssh»), «local» и некоторыми дополнительными типами, такими как «chroot» и «jail». Все эти типы подключения могут быть использованы в книгах сценариев и с /usr/bin/ansible, чтобы определить, как вы хотите взаимодействовать с удаленными машинами. Основы этих типов подключения описаны в разделе Начало работы. Если вам нужно расширить Ansible для поддержки других транспортных средств (SNMP, шина сообщений и т. д.), достаточно скопировать формат одного из существующих модулей и поместить его в каталог плагинов подключения. Значение «smart» для подключения позволяет выбрать paramiko или openssh на основе возможностей системы и выбирает «ssh», если OpenSSH поддерживает ControlPersist, в Ansible 1.2.1 и более поздних версиях. Предыдущие версии не поддерживали «smart».

Более подробная документация по написанию плагинов подключения ожидается, но вы можете зайти в lib/ansible/plugins/connection и легко разобраться.

Плагины поиска

Плагины поиска используются для извлечения данных из внешних хранилищ данных. Плагины поиска могут использоваться в книгах сценариев как для циклов — такие конструкции языка книги сценариев, как «with_fileglob» и «with_items», реализованы с помощью плагинов поиска — так и для возврата значений в переменную или параметр.

Вот простая реализация плагина поиска — этот плагин возвращает содержимое текстового файла как переменную:

from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase

try:
    from __main__ import display
except ImportError:
    from ansible.utils.display import Display
    display = Display()


class LookupModule(LookupBase):

    def run(self, terms, variables=None, **kwargs):

        ret = []

        for term in terms:
            display.debug("File lookup term: %s" % term)

            # Find the file in the expected search path
            lookupfile = self.find_file_in_search_path(variables, 'files', term)
            display.vvvv(u"File lookup using %s as file" % lookupfile)
            try:
                if lookupfile:
                    contents, show_data = self._loader._get_file_contents(lookupfile)
                    ret.append(contents.rstrip())
                else:
                    raise AnsibleParserError()
            except AnsibleParserError:
                raise AnsibleError("could not locate file in lookup: %s" % term)

        return ret

Пример того, как вызывается этот плагин поиска:

---
- hosts: all
  vars:
     contents: "{{ lookup('file', '/etc/foo.txt') }}"

  tasks:

     - debug: msg="the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}"

Ошибки, возникающие во время выполнения, должны возвращаться путем поднятия AnsibleError() с сообщением, описывающим ошибку. Любые строки, возвращаемые реализацией вашего плагина поиска, которые могут содержать не-ASCII-символы, должны быть преобразованы в тип unicode Python, потому что эти строки будут переданы в jinja2. Для этого вы можете использовать:

from ansible.module_utils._text import to_text
result_string = to_text(result_string)

Для получения дополнительных примеров плагинов поиска см. исходный код плагинов поиска, включенных в Ansible, здесь: lib/ansible/plugins/lookup.

Примеры использования плагинов поиска см. в Использование плагинов поиска.

Плагины переменных

Конструкции книги сценариев, такие как «host_vars» и «group_vars», работают с помощью плагинов «vars». Они вводят дополнительные данные переменных в Ansible-запуски, которые не поступают из инвентаризации, книги сценариев или командной строки. Обратите внимание, что переменные также могут возвращаться из инвентаризации, поэтому в большинстве случаев вам не нужно писать или понимать vars_plugins.

Более подробная документация по написанию плагинов vars ожидается, но вы можете зайти в lib/ansible/plugins и легко разобраться.

Если вы хотите написать vars_plugin, скорее всего, вам следует написать скрипт инвентаризации вместо него.

Плагины фильтров

Плагины фильтров используются для обработки данных. Они являются функцией Jinja2 и также доступны в шаблонах Jinja2, используемых модулем template. Как и все плагины, их можно легко расширить, но вместо файла для каждого плагина можно иметь несколько плагинов в одном файле. Большинство плагинов фильтров, поставляемых с Ansible, находятся в core.py.

Дополнительные сведения см. в lib/ansible/plugins/filter.

Плагины тестов

Плагины тестов предназначены для проверки данных. Они являются функцией Jinja2 и также доступны в шаблонах Jinja2, используемых модулем template. Как и все плагины, их можно легко расширить, но вместо файла для каждого плагина можно иметь несколько плагинов в одном файле. Большинство плагинов тестов, поставляемых с Ansible, находятся в core.py. Они особенно полезны в сочетании с некоторыми плагинами фильтров, такими как map и select; они также доступны для условных директив, таких как when:.

Дополнительные сведения см. в lib/ansible/plugins/test.

Распространение плагинов

Плагины загружаются из пути установленного каталога библиотеки и настроенного каталога плагинов (см. ansible.cfg). Расположение может варьироваться в зависимости от того, как вы установили Ansible (pip, rpm, deb и т. д.) или операционной системой/дистрибутивом/пакетировщиком. Плагины автоматически загружаются, когда у вас есть один из следующих подкаталогов рядом с вашей книгой сценариев или внутри роли:

• action_plugins
• lookup_plugins
• callback_plugins
• connection_plugins
• filter_plugins
• strategy_plugins
• cache_plugins
• test_plugins
• shell_plugins

При распространении в качестве части роли плагин будет доступен сразу после вызова роли в игре.