使用和开发模块实用程序

Ansible 提供了许多模块实用程序，或共享代码片段，这些代码片段提供了一些辅助函数，您可以在开发自己的模块时使用它们。 basic.py 模块实用程序提供了访问 Ansible 库的主要入口点，所有 Python Ansible 模块都必须从 ansible.module_utils 中导入某些内容。一个常见的选择是导入 AnsibleModule

from ansible.module_utils.basic import AnsibleModule

ansible.module_utils 命名空间不是一个简单的 Python 包：它是在每次任务调用时动态构建的，通过提取导入并根据从活动配置派生的 搜索路径 解决与命名空间匹配的那些导入。

为了减少集合或本地模块中的维护负担，您可以将重复的代码提取到一个或多个模块实用程序中，并将它们导入到您的模块中。例如，如果您有自己的自定义模块，这些模块导入了一个 my_shared_code 库，您可以将其放置在一个 ./module_utils/my_shared_code.py 文件中，如下所示

from ansible.module_utils.my_shared_code import MySharedCodeClient

当您运行 ansible-playbook 时，Ansible 将合并您本地 module_utils 目录中的所有文件到 ansible.module_utils 命名空间中，顺序由 Ansible 搜索路径 定义。

命名和查找模块实用程序

您通常可以从模块实用程序的名称和/或位置判断它做什么。通用实用程序（许多不同类型的模块共享的代码）位于主要的 ansible/ansible 代码库中，位于 common 子目录或 lib/ansible/module_utils 的根目录中。由特定模块集使用的实用程序通常位于与这些模块相同的集合中。例如

  • lib/ansible/module_utils/urls.py 包含用于解析 URL 的共享代码

  • openstack.cloud.plugins.module_utils.openstack.py 包含用于处理 OpenStack 实例的模块的实用程序

  • ansible.netcommon.plugins.module_utils.network.common.config.py 包含用于网络模块的实用程序函数

按照这种模式使用您自己的模块实用程序，可以使所有内容易于查找和使用。

标准模块实用程序

Ansible 附带了广泛的 module_utils 文件库。您可以在主 Ansible 路径下的 lib/ansible/module_utils 目录中找到模块实用程序源代码。我们将在下面描述最广泛使用的实用程序。有关任何特定模块实用程序的更多详细信息，请参阅 module_utils 的源代码。

注意

许可要求 Ansible 强制执行以下许可要求

  • 实用程序（lib/ansible/module_utils/ 中的文件）可能具有以下两种许可证之一

    • module_utils 中的文件仅用于特定供应商的硬件、提供商或服务，可能根据 GPLv3+ 许可。在 module_utils 下添加具有 GPLv3+ 许可的新文件需要获得核心团队的批准。

    • 所有其他 module_utils 必须根据 BSD 许可，以便 GPL 许可的第三方和 Galaxy 模块可以使用它们。

    • 如果对 module_utils 中文件的适当许可证存在疑问，Ansible 核心团队将在 Ansible 核心社区会议期间做出决定。

  • 所有其他与 Ansible 一起提供的文件，包括所有模块，必须根据 GPL 许可（GPLv3 或更高版本）进行许可。

  • 现有的许可要求仍然适用于 ansible/ansible（ansible-core）中的内容。

  • 以前在 ansible/ansible 或集合中，并已移至新集合的内容必须保留其在先前存储库中的许可证。

  • 先前提交者提交的版权条目也必须保留在所有移动的文件中。

  • api.py - 支持通用 API 模块

  • basic.py - Ansible 模块的通用定义和辅助实用程序

  • common/dict_transformations.py - 字典转换的辅助函数

  • common/file.py - 用于处理文件的辅助函数

  • common/text/ - 用于转换和格式化文本的辅助函数

  • common/parameters.py - 用于处理模块参数的辅助函数

  • common/sys_info.py - 用于获取发行版和平台信息的函数

  • common/validation.py - 用于根据模块参数规范验证模块参数的辅助函数

  • facts/ - 返回事实的模块的实用程序目录。有关更多信息，请参见 PR 23012

  • json_utils.py - 用于过滤模块 JSON 输出周围不相关输出的实用程序，例如前导行和尾随行

  • powershell/ - Windows PowerShell 模块的定义和辅助函数目录

  • pycompat24.py - Python 2.4 的异常解决方法

  • service.py - 使模块能够与 Linux 服务一起工作的实用程序（占位符，未在使用中）

  • six/__init__.py - Six Python 库 的捆绑副本，用于帮助编写与 Python 2 和 Python 3 兼容的代码

  • splitter.py - 用于处理 Jinja2 模板的字符串拆分和操作实用程序

  • urls.py - 用于处理 http 和 https 请求的实用程序

一些常用的实用程序已迁移到 Ansible 2.10 中的集合，包括

  • ismount.py 迁移到 ansible.posix.plugins.module_utils.mount.py - 修复 os.path.ismount 的单个辅助函数

  • known_hosts.py 迁移到 community.general.plugins.module_utils.known_hosts.py - 用于处理 known_hosts 文件的实用程序

有关迁移内容及其目标集合的列表，请参阅 runtime.yml 文件。