在本地添加模块和插件

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

如果您正在使用本地模块或插件，但 Ansible 找不到它，此页面就是您所需的一切。

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

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

您可以复制其他人的模块和插件。
编写新模块时，您可以选择任何您喜欢的编程语言。
您无需克隆任何存储库。
您无需打开拉取请求。
您无需添加测试（尽管我们建议您这样做！）。

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

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

插件扩展了 Ansible 的核心功能。大多数插件类型在 /usr/bin/ansible 进程内的控制节点上执行。插件为 Ansible 的核心功能提供了选项和扩展：转换数据、记录输出、连接到清单等等。
模块是一种插件类型，它在“目标”（通常是远程系统）上执行自动化任务。模块充当 Ansible 在其自身进程中（在控制节点之外）执行的独立脚本。模块主要通过 JSON 与 Ansible 交互，接受参数并通过在退出之前将 JSON 字符串打印到标准输出返回信息。与其他插件（必须用 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 以在指定位置加载独立的本地插件，并使其可供所有剧本和角色使用。或者，您可以使独立的本地插件仅可供特定剧本或角色使用。

注意

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

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

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

将您的本地插件添加到一个默认配置的位置。有关插件类型的正确配置设置的详细信息，请参阅配置设置。默认位置可能会在未经通知的情况下更改。
将本地插件的位置添加到环境变量或配置中
- 相关的 ANSIBLE_plugin_type_PLUGINS 环境变量 - 例如，$ANSIBLE_INVENTORY_PLUGINS 或 $ANSIBLE_VARS_PLUGINS
- 相关的 plugin_type_PATH 配置设置，其中大多数以 DEFAULT_ 开头 - 例如，DEFAULT_CALLBACK_PLUGIN_PATH 或 DEFAULT_FILTER_PLUGIN_PATH 或 BECOME_PLUGIN_PATH

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

ansible-config dump |grep plugin_type_PATH

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

要确认 plugins/plugin_type/my_local_plugin 是否可用

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

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

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

Ansible 会自动加载与您的剧本或角色相邻的某些目录中的所有插件，并从名为插件类型的目录中分别加载每种类型的插件。这些位置中的独立插件仅可供父目录中的特定剧本或角色使用。

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

警告

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

警告

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

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

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