使用和开发模块实用程序

Ansible 提供了一系列的模块实用程序（module utilities），即共享代码片段，它们提供了在开发自定义模块时可以使用的一系列辅助函数。basic.py 模块实用程序提供了访问 Ansible 库的主要入口点，所有 Python Ansible 模块都必须从 ansible.module_utils 导入内容。一个常见的选项是导入 AnsibleModule

from ansible.module_utils.basic import AnsibleModule

ansible.module_utils 命名空间并非一个普通的 Python 包：它是为每次任务调用动态构建的，通过提取导入项，并根据由当前配置得出的 搜索路径 来解析与该命名空间匹配的内容。

警告

模块仅能从 ansible.module_utils.* 导入。不支持从 ansible 命名空间的其他部分导入（例如 ansible.errors 或 ansible.parsing.dataloader）。无法保证执行模块的远程目标主机上存在 ansible 包，因此此类导入可能会静默失败或产生不可预知的结果。

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

from ansible.module_utils.my_shared_code import MySharedCodeClient

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

命名和查找模块实用程序

通常可以通过模块实用程序的名称和/或位置来判断其功能。通用实用程序（由多种不同类型模块共用的共享代码）位于主 ansible/ansible 代码库的 common 子目录或 lib/ansible/module_utils 的根目录下。由特定一组模块使用的实用程序通常与这些模块位于同一个 Collection 中。例如：

  • 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 Core 团队将在 Ansible Core 社区会议期间决定。

  • 随 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/ - 为返回事实 (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 中，几个常用的实用程序已迁移到 Collection 中，包括：

  • 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 文件的实用程序

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