ansible Developing Plugins

• Action plugins是模块的前端，可以在调用模块本身之前对控制器执行操作。
• Cache plugins用于保存“facts”的缓存，以避免代价高昂的fact-gathering操作。
• Callback plugins使您能够挂接到ansible事件中进行显示或记录。
• Connection plugins定义了如何与库存主机通信。
• Filters plugins允许您操纵Ansible plays和/或模板内的数据。 这是一个Jinja2功能; Ansible支持额外的过滤器插件。
• Lookup plugins用于从外部来源拉取数据。 这些是使用定制的Jinja2功能实现的。
• Strategy plugins控制play and execution逻辑的流程。
• Shell插件处理可以在远程主机上遇到的不同shell的低级命令和格式。
• Test plugins允许您验证ansible play和/或模板中的数据。 这是一个Jinja2功能; ansible支持额外的测试插件。
• Vars插件将额外的可变数据注入到ansible run 中，不是来自inventory，play或命令行。

Callback Plugins

回调插件可以在响应事件时将新行为添加到ansible。 默认情况下，回调插件控制运行命令行程序时看到的大部分输出。

Example Callback Plugins

Ansible带有一些回调插件，您可以查看示例。 这些可以在lib / ansible / plugins / callback中找到 。

log_plays回调是如何截取日志文件的playbook事件的一个例子，当Playbook完成时邮件回调发送电子邮件。

提供的osx_say回调特别有趣 - 它将与OS X上的计算机合成语音相关的剧本事件进行回应，并保证对同事的娱乐和/或烦恼。

Configuring Callback Plugins

您可以通过将其放回到与play或role內部的callback_plugins目录中，或将其放置在ansible.cfg中配置的一个回调目录源中来激活自定义回调。

插件以字母数字顺序加载; 例如，在名为1_first.py的文件中实现的插件将在名为2_second.py的插件文件之前运行。

默认情况下，Ansible附带的大多数回调都被禁用，并且需要在您的ansible.cfg文件中列入白名单才能运行。 例如：

#callback_whitelist = timer, mail, mycallbackplugin

Managing stdout

您只能有一个插件是您的控制台输出的主要经理。 如果要替换默认值，则应在子类中定义CALLBACK_TYPE = stdout，然后在ansible.cfg中配置stdout插件。 例如：

  #stdout_callback = mycallbackplugin

Developing Callback Plugins

回调插件是通过以Base（Callbacks）类作为父类创建一个新类创建的：

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

class CallbackModule(CallbackBase):
    pass

从那里，覆盖您要为其提供回调的CallbackBase中的特定方法。 对于要与可复制版本2.0及更高版本一起使用的插件，您应该仅覆盖以v2开头的方法。 有关可以覆盖的方法的完整列表，请参阅lib / ansible / plugins / callback目录中的__init__.py 。

以下示例显示了如何实现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)))

请注意，对于Ansible> = 2.0正常运行的插件，需要使用CALLBACK_VERSION和CALLBACK_NAME定义。

Connection Plugins

默认情况下，Ansys提供了一个'paramiko'SSH，本机ssh（简称'ssh'），'本地'连接类型，还有一些小的玩家，如'chroot'和'jail'。 所有这些都可以用于剧本和/ usr / bin / ansible来决定如何与远程机器通话。 这些连接类型的基本知识将在“ 入门”部分中介绍。 如果您想扩展Ansible以支持其他传输（SNMP，消息总线等），就像复制其中一个现有模块的格式并将其放入连接插件目录一样简单。 连接的“smart”值允许基于系统功能选择paramiko或openssh，如果OpenSSH支持ControlPersist，则在Ansible 1.2.1和更高版本中选择“ssh”。 以前的版本不支持“smart”。

关于编写连接插件的更多文档正在等待，尽管您可以轻松地跳转到lib / ansible / plugins / connection中

Lookup Plugins

Lookup插件用于从外部数据存储中提取数据。 可以在Playbook中使用Lookup插件，playbooks - 通过查找插件实现“with_fileglob”和“with_item”等手册语言结构，并将值返回到变量或参数中。

这是一个简单的查找插件实现 - 此查找将文本文件的内容作为变量返回：

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字符的查找插件实现返回的任何字符串都必须转换为Python的unicode类型，因为这些字符串将通过jinja2运行。 为此，您可以使用：

  from ansible.module_utils._text import to_text
 result_string = to_text （ result_string ）

有关更多示例查找插件，请查看此处包含的查找插件的源代码： lib / ansible / plugins / lookup 。

有关查找插件的使用示例，请参阅使用查找 。

Vars Plugins

过滤器插件用于操纵数据。 它们是Jinja2的功能，也可以在模板模块使用的Jinja2模板中使用。 与所有插件一样，它们可以轻松扩展，而不是为每个插件提供一个文件，您可以拥有多个每个文件。 Ansible随附的大多数过滤插件位于core.py中 。

有关详细信息，请参阅lib / ansible / plugins / filter 。

测试插件

测试插件用于验证数据。 它们是Jinja2的功能，也可以在模板模块使用的Jinja2模板中使用。 与所有插件一样，它们可以轻松扩展，而不是为每个插件提供一个文件，您可以拥有多个每个文件。 Ansible随附的大多数测试插件都驻留在core.py中 。 这些特别适用于一些过滤器插件，如map和select ; 它们也可用于条件指令，如： 。

有关详细信息，请参阅lib / ansible / plugins / test 。

Distributing Plugins

插件从库安装路径和配置的插件目录加载（检查您的ansible.cfg ）。 该位置可能因安装Ansible（pip，rpm，deb等）或OS / Distribution / Packager的方式而异。 如果您有以下子文件夹之一与您的Playbook相邻或在角色中自动加载插件：