创建新集合

从 Ansible 2.10 开始，相关的模块应该在集合中开发。Ansible 核心团队和社区编制了这些模块开发技巧和窍门，以帮助公司为其产品开发 Ansible 模块，以及用户为第三方产品开发 Ansible 模块。有关集合格式的更详细描述以及其他开发指南，请参阅 开发集合。

注意

**许可要求** 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 或集合中并且已移至新集合的内容必须保留其在先前存储库中的许可证。

  • 以前提交者添加的版权条目也必须保留在任何移动文件中。

在开始编码之前

此先决条件列表旨在帮助确保你开发出高质量的模块，这些模块能够很好地与 ansible-core 配合使用并提供无缝的用户体验。

  • 通读 开发模块 中链接的所有页面；特别关注 将你的模块贡献给现有的 Ansible 集合。

  • 我们鼓励符合 PEP 8 规范。有关更多信息，请参阅 pep8。

  • 我们鼓励支持 Python 2.6+ 和 Python 3.5+。

  • 查看 Ansible Galaxy，并查看你功能领域（如云、网络、数据库）中的命名约定。

  • 能力越大，责任越大：Ansible 集合维护者有责任帮助保持内容更新，并定期发布他们负责的集合。与所有成功的社区项目一样，集合维护者应密切关注报告的问题和贡献。

  • 我们强烈建议进行单元测试和/或集成测试。当需要外部资源（如云或网络设备）时，单元测试特别有价值。有关更多信息，请参阅 测试 Ansible。

命名约定

插件和模块的完全限定集合名称 (FQCN) 包括三个元素

  • Galaxy 命名空间，通常代表公司或组织

  • 集合名称，通常代表产品或操作系统

  • 插件或模块名称

    • 始终为小写

    • 单词之间用下划线 (_) 字符分隔

    • 单数，而不是复数，例如，command，而不是 commands

例如，community.mongodb.mongodb_linux 或 cisco.meraki.meraki_device。

在 GitHub（或其他地方）上，如果组织和存储库名称与你在 Ansible Galaxy 上的命名空间和集合名称匹配，这会很方便，但这不是必需的。但是，你选择的插件名称始终与代码存储库和 Galaxy 上的集合工件中的名称相同。

与我们交谈

在编码之前传播你的想法有助于你采用良好的做法并避免常见错误。阅读“在开始编码之前”部分后，你应该对模块的结构有一个合理的了解。列出你提出的插件和/或模块名称，并简要描述每个名称的功能。在 IRC 或邮件列表上传播该列表，以便 Ansible 社区可以审查你的想法，以确保一致性和熟悉程度。一致、可预测和熟悉的名称和功能使你的集合更易于使用。

在哪里获得支持

Ansible 拥有一个充满活力且知识渊博的模块开发人员社区，它是获得答案的好资源。

在 Ansible 社区指南 中，你可以找到如何

  • 订阅邮件列表 - 我们建议使用“Ansible 开发列表”和“Ansible 公告列表”。

  • #ansible-devel - 我们发现，在 #ansible-devel 聊天频道（使用 ansible.im 上的 Matrix 或使用 irc.libera.chat 上的 IRC）上进行交流对开发人员来说最有效，这样我们就可以进行互动式对话。

  • 工作组和其他聊天频道会议 - 加入各种每周会议 会议时间表页面

必需文件

你的集合应包含以下文件以供使用

  • 一个 __init__.py 文件 - 一个空文件，用于初始化命名空间并允许 Python 导入文件。必需

  • 至少一个插件，例如，/plugins/modules/$your_first_module.py。必需

  • 如果需要，一个或多个 /plugins/doc_fragments/$topic.py 文件 - 代码文档，例如有关常见参数的详细信息。可选

  • 如果需要，一个或多个 /plugins/module_utils/$topic.py 文件 - 在多个模块之间共享的代码，例如常见参数。可选

准备就绪后，请再次查看 将你的模块贡献给现有的 Ansible 集合。如果你要创建新的集合，你需要负责与存储库相关的全部过程，包括设置贡献规则、寻找审阅者以及测试和维护集合中的代码。

如果你需要帮助或建议，请考虑加入 #ansible-devel 聊天频道（使用 ansible.im 上的 Matrix 或使用 irc.libera.chat 上的 IRC）。有关更多信息，请参阅 在哪里获得支持 和 与 Ansible 社区交流。

Git 或 GitHub 新手

我们知道这可能是你第一次使用 Git 或 GitHub。以下指南可能对你有所帮助