创建集合

要创建集合

  1. 使用 ansible-galaxy collection init 命令创建一个新集合，可以选择使用自定义集合模板。

  2. 向集合添加模块和其他内容。

  3. 使用 ansible-galaxy collection build 将集合构建为集合构件。

  4. 使用 ansible-galaxy collection publish 将集合构件发布到 Galaxy。

然后，用户可以在其系统上安装你的集合。

命名你的集合

集合名称由命名空间和名称组成，两者用句点 ( .) 分隔。命名空间和名称都应该是有效的 Python 标识符。这意味着它们应由 ASCII 字母、数字和下划线组成。

注意

通常，命名空间和名称使用小写字母、数字和下划线，但不使用大写字母。

你应确保你使用的命名空间未被其他人注册，方法是查看 Ansible Galaxy 的命名空间列表。如果你选择的命名空间甚至是完整的集合名称与 Galaxy 上的另一个集合冲突，则如果你或其他人使用你的集合名称运行 ansible-galaxy collection install，则可能会导致你最终得到另一个集合。即使命名空间目前不存在，也可能会在以后由其他人创建。

如果你想在 Ansible Galaxy 上请求新的命名空间，请在 github.com/ansible/galaxy 上创建一个问题。

有一些特殊的命名空间

ansible：

ansible 命名空间由 Red Hat 拥有，并保留用于官方 Ansible 集合。两个特殊成员是合成的 ansible.builtin 和 ansible.legacy 集合。这些集合在 Ansible Galaxy 上找不到，而是内置于 ansible-core 中。

community：

community 命名空间由 Ansible 社区拥有。此命名空间中的集合通常位于 GitHub ansible-collection 组织中。如果你想在此命名空间中创建集合，请在论坛上请求它。

local：

local 命名空间在 Ansible Galaxy 上不包含任何集合，并且目的是永远不会更改。你可以将 local 命名空间用于本地计算机或本地 Git 存储库中的集合，而不必担心与 Ansible Galaxy 上实际存在的集合发生冲突。

创建新集合

在包含 ansible_collections 的路径中创建集合框架，例如 collections/ansible_collections/。

要启动新集合，请在你的集合目录中运行以下命令

ansible_collections#> ansible-galaxy collection init my_namespace.my_collection

注意

命名空间和集合名称都使用相同的严格要求集。有关这些要求，请参阅 Galaxy 文档站点上的 Galaxy 命名空间。

它将创建结构 [my_namespace]/[my_collection]/[集合 框架]。

提示

如果 Git 用于版本控制，则应在集合目录中初始化相应的存储库。

集合存在后，你可以使用你想要在集合内的内容填充目录。有关可以在集合中放置哪些内容的更好了解，请参阅 ansible-collections GitHub 组织。

参考：ansible-galaxy collection 命令

当前，ansible-galaxy collection 命令实现以下子命令

  • init：基于 Ansible 随附的默认模板或你自己的模板创建基本集合。

  • build：创建可以上传到 Galaxy 或你自己的存储库的集合构件。

  • publish：将构建的集合构件发布到 Galaxy。

  • install：安装一个或多个集合。

要了解有关 ansible-galaxy 命令行工具的更多信息，请参阅 ansible-galaxy 手册页。

从自定义模板创建集合

内置的集合模板是一个使用 ansible-core 的简单集合示例，但如果你想简化你的开发过程，你可能需要创建自定义集合模板以传递给 ansible-galaxy collection init。

集合骨架是一个看起来像集合目录的目录，但任何 .j2 文件（不包括 templates/ 和 roles/*/templates/ 中的文件）都将由 ansible-galaxy collection init 模板化。骨架的 galaxy.yml.j2 文件应使用变量 namespace 和 collection_name，它们派生自 ansible-galaxy init namespace.collection_name，并将填充已初始化集合的 galaxy.yml 文件中的元数据。默认情况下还有一些额外的变量可用（例如，version 为 1.0.0），并且可以使用 --extra-vars 来补充/覆盖这些变量。

一个接受可选字典变量 dependencies 的 galaxy.yml.j2 文件示例可能如下所示

namespace: {{ namespace }}
name: {{ collection_name }}
version: "{{ (version|quote) is version("0.0.0", operator="gt", version_type="semver")|ternary(version, undef("version must be a valid semantic version greater than 0.0.0")) }}"
dependencies: {{ dependencies|default({}, true) }}

要使用新模板初始化集合，请使用 ansible-galaxy collection init 传递骨架的路径

ansible_collections#> ansible-galaxy collection init --collection-skeleton /path/to/my/namespace/skeleton --extra-vars "@my_vars_file.json" my_namespace.my_collection

注意

在 ansible-core 2.17 之前，集合骨架模板仅限于少数硬编码变量，包括 namespace、collection_name 和 version。

注意

默认集合骨架使用一个内部过滤器 comment_ify，该过滤器不能通过 --collection-skeleton 访问。使用 ansible-doc -t filter|test --list 查看可用的插件。

使用 ansible-creator 创建集合

ansible-creator 旨在快速搭建 Ansible 集合项目。

注意

Ansible 开发工具 包提供了一种便捷的方法来安装 ansible-creator 以及一组用于开发自动化内容的精选工具。

在安装 ansible-creator 后，您可以通过以下方式之一初始化项目

  • 使用 init 子命令。

  • 在 Visual Studio Code 中使用 Ansible 扩展使用 ansible-creator。

另请参阅

使用 Ansible 集合

了解如何安装和使用集合。

集合结构

集合骨架中包含的目录和文件

Ansible 开发工具 (ADT)

用于创建和测试 Ansible 内容的 Python 包。

沟通

有问题？需要帮助？想分享您的想法？请访问 Ansible 沟通指南