本地添加模块和插件

您可以通过添加自定义模块或插件来扩展 Ansible。您可以从头创建它们，也可以复制现有的模块或插件以供本地使用。您可以将本地模块或插件存储在 Ansible 控制节点上，并与您的团队或组织共享。您还可以通过将插件和模块包含在集合中，然后在 Ansible Galaxy 上发布集合来共享它们。

如果您正在使用本地模块或插件，但 Ansible 找不到它，那么这个页面就是您所需要的。

如果您想创建插件或模块，请参阅开发插件、开发模块和开发集合。

使用本地模块和插件扩展 Ansible 可以提供如下快捷方式：

• 您可以复制其他人的模块和插件。

• 在编写新模块时，您可以选择您喜欢的任何编程语言。

• 您不必克隆任何存储库。

• 您不必打开 Pull Request。

• 您不必添加测试（尽管我们建议您这样做！）。

模块和插件：有什么区别？

如果您希望向 Ansible 添加功能，您可能想知道是否需要模块或插件。以下是一个简短的概述，可帮助您了解您需要什么：

• 插件扩展了 Ansible 的核心功能。大多数插件类型在控制节点上的 /usr/bin/ansible 进程中执行。插件为 Ansible 的核心功能提供了选项和扩展：转换数据、记录输出、连接到清单等等。

• 模块是一种插件类型，它在“目标”（通常是远程系统）上执行自动化任务。模块作为独立的脚本工作，Ansible 在其自己的进程中执行这些脚本，而不是在控制节点之外执行。模块主要通过 JSON 与 Ansible 交互，接受参数并通过在退出之前将 JSON 字符串打印到 stdout 来返回信息。与其他插件（必须用 Python 编写）不同，模块可以用任何语言编写；尽管 Ansible 仅提供 Python 和 Powershell 中的模块。

在集合中添加模块和插件

您可以通过创建集合来添加模块和插件。使用集合，您可以在任何 Playbook 或角色中使用自定义模块和插件。您可以通过 Ansible Galaxy 随时轻松共享您的集合。

此页面的其余部分描述了使用本地独立模块或插件的其他方法。

在集合之外添加模块或插件

您可以配置 Ansible 以在特定位置加载独立的本地模块或插件，并使它们可用于所有 Playbook 和角色（使用配置的路径）。或者，您可以使非集合本地模块或插件仅对某些 Playbook 或角色可用（使用相邻的路径）。

为所有 Playbook 和角色添加独立的本地模块

要自动加载独立的本地模块并使其可用于所有 Playbook 和角色，请使用DEFAULT_MODULE_PATH 配置设置或 ANSIBLE_LIBRARY 环境变量。配置设置和环境变量采用冒号分隔的列表，类似于 $PATH。您有两个选择：

• 将您的独立的本地模块添加到默认配置的位置之一。有关详细信息，请参阅DEFAULT_MODULE_PATH 配置设置。默认位置可能会在不通知的情况下更改。

• 将您的独立的本地模块的位置添加到环境变量或配置中：

  • ANSIBLE_LIBRARY 环境变量

  • DEFAULT_MODULE_PATH 配置设置

要查看模块的当前配置设置：

ansible-config dump |grep DEFAULT_MODULE_PATH

将您的模块文件保存到这些位置之一后，Ansible 会加载它，您可以在任何本地任务、Playbook 或角色中使用它。

要确认 my_local_module 是否可用：

• 键入 ansible localhost -m my_local_module 以查看该模块的输出，或者

• 键入 ansible-doc -t module my_local_module 以查看该模块的文档

注意

这适用于所有插件类型，但每种插件类型都需要特定的配置和/或相邻的目录，请参见下文。

注意

ansible-doc 命令可以从 Python 编写的模块或相邻的 YAML 文件中解析模块文档。如果您有一个用 Python 以外的编程语言编写的模块，您应该在与模块文件相邻的 Python 或 YAML 文件中编写文档。相邻的 YAML 文档文件

为选定的 Playbook 或单个角色添加独立的本地模块

Ansible 会自动将 Playbook 或角色相邻的某些目录中的所有可执行文件加载为模块。这些位置中的独立模块仅对父目录中的特定 Playbook、多个 Playbook 或角色可用。

• 要仅在选定的 Playbook 或多个 Playbook 中使用独立模块，请将该模块存储在包含 Playbook 或多个 Playbook 的目录中的名为 library 的子目录中。

• 要仅在单个角色中使用独立模块，请将该模块存储在该角色内的名为 library 的子目录中。

注意

这适用于所有插件类型，但每种插件类型都需要特定的配置和/或相邻的目录，请参见下文。

警告

集合中包含的角色不能包含任何模块或其他插件。集合中的所有插件都必须位于集合 plugins 目录树中。该树中的所有插件都可以被集合中的所有角色访问。如果您正在开发新的模块，我们建议您将它们分发到集合中，而不是角色中。

在集合之外本地添加非模块插件

您可以配置 Ansible 以在指定的一个或多个位置加载独立的本地插件，并使它们可用于所有 Playbook 和角色。或者，您可以使独立的本地插件仅对特定的 Playbook 或角色可用。

注意

尽管模块是插件，但适用于其他插件类型的目录名称和环境变量的命名模式并不适用于模块。请参阅在集合外部添加模块或插件。

为所有剧本和角色添加本地非模块插件

要自动加载独立的本地插件并使其可用于所有剧本和角色，请使用要添加的插件类型的配置设置或环境变量。这些配置设置和环境变量采用冒号分隔的列表，类似于 $PATH。 您有两个选择：

• 将您的本地插件添加到默认配置的位置之一。 有关插件类型的正确配置设置的详细信息，请参阅配置设置。默认位置可能会在不通知的情况下更改。

• 将您的本地插件的位置添加到环境变量或配置中

  • 相关的 ANSIBLE_插件类型_PLUGINS 环境变量 - 例如，$ANSIBLE_INVENTORY_PLUGINS 或 $ANSIBLE_VARS_PLUGINS

  • 相关的 插件类型_PATH 配置设置，其中大多数以 DEFAULT_ 开头 - 例如，DEFAULT_CALLBACK_PLUGIN_PATH 或 DEFAULT_FILTER_PLUGIN_PATH 或 BECOME_PLUGIN_PATH

要查看非模块插件的当前配置设置

ansible-config dump |grep plugin_type_PATH

将插件文件添加到这些位置之一后，Ansible会加载它，您可以在任何本地模块、任务、剧本或角色中使用它。 有关环境变量和配置设置的更多信息，请参阅Ansible配置设置。

要确认 plugins/插件类型/my_local_plugin 可用

• 键入 ansible-doc -t <插件类型> my_local_lookup_plugin 以查看该插件的文档 - 例如，ansible-doc -t lookup my_local_lookup_plugin

ansible-doc 命令适用于大多数插件类型，但不适用于 action、filter 或 test 插件。 有关更多详细信息，请参阅ansible-doc。

为选定的剧本或单个角色添加独立的本地插件

Ansible会自动从剧本或角色旁边的某些目录加载所有插件，并从一个以插件类型命名的目录中分别加载每种类型的插件。 这些位置中的独立插件仅适用于父目录中的特定剧本、多个剧本或角色。

• 要仅在选定的剧本或多个剧本中使用独立插件，请将插件存储在包含剧本的目录中，用于正确插件类型（例如，callback_plugins 或 inventory_plugins）的子目录中。 这些目录必须使用 _plugins 后缀。 有关插件类型的完整列表，请参阅使用插件。

• 要仅在单个角色中使用独立插件，请将插件存储在该角色中用于正确插件类型（例如，cache_plugins 或 strategy_plugins）的子目录中。 当作为角色的一部分交付时，插件将在角色执行后立即可用。 这些目录必须使用 _plugins 后缀。 有关插件类型的完整列表，请参阅使用插件。

警告

集合中包含的角色不能包含任何插件。 集合中的所有插件必须位于集合 plugins 目录树中。 该树中的所有插件都可用于集合中的所有角色。 如果您正在开发新的插件，我们建议将它们分发在集合中，而不是在角色中。

警告

某些插件类型在 Ansible 执行的早期阶段是必需的，例如回调、清单和缓存。 这些插件类型无法动态加载，必须存在于配置的路径中，或者通过配置中的 FQCN 引用。

使用 ansible.legacy 访问 ansible.builtin 模块的自定义版本

如果您需要覆盖 ansible.builtin 模块之一并使用 FQCN，则需要使用 ansible.legacy 作为完全限定集合名称 (FQCN) 的一部分。 例如，如果您有自己的 copy 模块，您将通过 ansible.legacy.copy 访问它。 有关如何在集合中对角色使用自定义模块的详细信息，请参阅使用 ansible.legacy 从基于集合的角色访问本地自定义模块。