分发集合

集合（Collection）是 Ansible 内容的一种分发格式。一个典型的集合包含针对一组相关用例的模块和其他插件。例如，一个集合可以实现特定数据库管理任务的自动化。集合还可以包含角色（roles）和剧本（playbooks）。

注意

在分发集合之前，请确保已更新 galaxy.yml 文件。详情请参阅 集合结构。

要分发您的集合并让其他人使用它，您可以将其发布到一个或多个 分发服务器 上。分发服务器包括

分发服务器	接受的集合
Ansible Galaxy	所有集合
Pulp 3 Galaxy	所有集合，支持已签名的集合
Red Hat Automation Hub	仅限经 Red Hat 认证的集合，支持已签名的集合
私有托管的 Automation Hub	所有者授权的集合

分发集合主要涉及四个步骤

1. 分发服务器的初始配置

2. 构建集合 tarball

3. 发布集合的准备工作

4. 发布集合

分发服务器的初始配置

配置到一个或多个分发服务器的连接，以便可以在那里发布集合。您只需要为每个分发服务器配置一次。每次发布新集合或现有集合的新版本时，都必须重复其他步骤（构建集合 tarball、准备发布和发布集合）。

1. 在您想要使用的每个分发服务器上创建一个命名空间。

2. 获取您想要使用的每个分发服务器的 API 令牌。

3. 为每个想要使用的分发服务器指定 API 令牌。

创建命名空间

您必须将集合上传到每个分发服务器上的某个命名空间中。如果您拥有 Ansible Galaxy 的登录账号，通常您的 Ansible Galaxy 用户名也是一个 Ansible Galaxy 命名空间。

警告

Ansible Galaxy 上的命名空间不能包含连字符。如果您的 Ansible Galaxy 登录用户名包含连字符，那么您的 Galaxy 用户名将不作为 Galaxy 命名空间使用。例如，awesome-user 是 Ansible Galaxy 的合法用户名，但它不是一个合法的命名空间。

您可以根据需要选择在 Ansible Galaxy 上创建额外的命名空间。对于 Red Hat Automation Hub 和私有 Automation Hub，您必须先创建命名空间，然后才能上传集合。创建命名空间的步骤如下

• 要在 Galaxy 上创建命名空间，请参阅 Galaxy 文档网站上的 Galaxy 命名空间 以获取详细信息。

• 要在 Red Hat Automation Hub 上创建命名空间，请参阅 Red Hat 自动化内容文档。

在每个集合的 galaxy.yml 文件中指定命名空间。有关 galaxy.yml 文件的更多信息，请参阅 集合 Galaxy 元数据结构。

获取您的 API 令牌

API 令牌用于验证您与每个分发服务器的连接。您需要为每个分发服务器提供单独的 API 令牌。使用正确的 API 令牌来安全连接到每个分发服务器并保护您的内容。

获取 API 令牌的方法

• 获取 Galaxy 的 API 令牌，请参阅 Galaxy 文档。

• 获取 Automation Hub 的 API 令牌，请参阅 Red Hat 自动化内容文档。

指定您的 API 令牌和分发服务器

每次发布集合时，都必须指定 API 令牌和分发服务器以创建安全连接。您有两种指定令牌和分发服务器的选项

• 您可以在配置中配置令牌，作为 ansible.cfg 文件中 galaxy_server_list 条目的一部分。使用配置是最安全的选择。

• 您可以在命令行中将令牌作为 ansible-galaxy 命令的参数传递。如果您在命令行中传递令牌，则可以通过命令行指定服务器，使用默认设置，或者在配置中设置服务器。在命令行传递令牌是不安全的，因为在命令行输入机密信息可能会将其暴露给系统上的其他用户。

在配置中指定令牌和分发服务器

默认情况下，Ansible Galaxy 被配置为唯一的分发服务器。您可以通过编辑 ansible.cfg 文件中的 galaxy_server_list 部分，添加其他分发服务器并在配置中指定您的 API 令牌。这是管理分发服务器认证最安全的方法。为每个服务器指定 URL 和令牌。例如

[galaxy]
server_list = release_galaxy

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=abcdefghijklmnopqrtuvwxyz

您不能对 galaxy_server_list 中定义的任何服务器使用 apt-key。有关完整详细信息，请参阅 配置 ansible-galaxy 客户端。

在命令行中指定令牌

您可以使用 ansible-galaxy 命令的 --token 参数在命令行中指定 API 令牌。在命令行传递令牌时，有三种指定分发服务器的方法

• 使用 ansible-galaxy 命令的 --server 参数

• 依赖默认设置 (https://galaxy.ansible.com)

• 通过在 ansible.cfg 文件中创建 GALAXY_SERVER 设置来配置服务器

例如

ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --token abcdefghijklmnopqrtuvwxyz

警告

使用 --token 参数是不安全的。在命令行传递机密信息可能会将其暴露给系统上的其他人。

构建您的集合 tarball

配置好一个或多个分发服务器后，构建集合 tarball。集合 tarball 是发布工件，即您上传且其他用户下载以安装您集合的对象。构建集合 tarball 的步骤

1. 查看 galaxy.yml 文件中的所有设置。详情请参阅 集合 Galaxy 元数据结构。确保已更新版本号。每次发布集合时，都必须使用新的版本号。您无法对分发服务器上已存在的集合版本进行更改。如果您尝试多次上传同一集合版本，分发服务器将返回错误 Code: conflict.collection_exists。集合遵循语义版本控制规则。有关版本的更多信息，请参阅 了解集合版本控制。有关 galaxy.yml 文件的更多信息，请参阅 集合 Galaxy 元数据结构。

2. 在集合的顶层目录中运行 ansible-galaxy collection build。例如

collection_dir#> ansible-galaxy collection build

此命令会在当前目录中构建集合的 tarball，您可以将其上传到您选择的分发服务器

my_collection/
├── galaxy.yml
├── ...
├── my_namespace-my_collection-1.0.0.tar.gz
└── ...

注意

• 为了减小集合大小，某些文件和文件夹默认会被排除在集合 tarball 之外。如果您的集合目录中包含其他您想要排除的文件，请参阅 忽略文件和文件夹。

• 当前的 Galaxy 最大 tarball 大小为 20 MB。

您可以将 tarball 上传到一个或多个分发服务器。您也可以通过复制 tarball 直接在目标系统上安装集合，从而在本地分发您的集合。

忽略文件和文件夹

您可以使用 build_ignore 或 清单指令 (Manifest Directives) 从集合中排除文件。有关 galaxy.yml 文件的更多信息，请参阅 集合 Galaxy 元数据结构。

包含所有文件，并显式忽略部分文件

默认情况下，构建步骤会将集合目录中的所有文件包含在 tarball 中，以下内容除外

• galaxy.yml

• *.pyc

• *.retry

• tests/output

• 根目录中以前构建的 tarball

• 各种版本控制目录，例如 .git/

要从集合 tarball 中排除其他文件和文件夹，请在集合的 galaxy.yml 文件中的 build_ignore 键下设置一系列类似文件 glob 的模式列表。这些模式使用以下特殊字符进行通配符匹配

• *: 匹配所有内容

• ?: 匹配任何单个字符

• [seq]: 匹配序列中的任何字符

• [!seq]: 匹配不在序列中的任何字符

例如，要排除 playbooks 文件夹内的 sensitive 文件夹以及任何 .tar.gz 归档文件，请在您的 galaxy.yml 文件中进行如下设置

build_ignore:
- playbooks/sensitive
- '*.tar.gz'

注意

build_ignore 功能仅在 Ansible 2.10 或更高版本的 ansible-galaxy collection build 中受支持。

清单指令

版本 2.14 新增。

galaxy.yml 文件支持历史上用于 Python 打包的清单指令，如 MANIFEST.in 命令 所述。

注意

使用 manifest 需要安装可选的 distlib Python 依赖项。

注意

manifest 功能仅在 ansible-core 2.14 或更高版本的 ansible-galaxy collection build 中受支持，且与 build_ignore 互斥。

例如，要排除 playbooks 文件夹内的 sensitive 文件夹以及任何 .tar.gz 归档文件，请在您的 galaxy.yml 文件中进行如下设置

manifest:
  directives:
    - recursive-exclude playbooks/sensitive **
    - global-exclude *.tar.gz

默认情况下，MANIFEST.in 样式的指令会默认排除所有文件，但已内置了默认指令。这些默认指令描述如下。要在构建过程中查看正在使用的指令，请在 ansible-galaxy collection build 命令中加入 -vvv 参数。

include meta/*.yml
include *.txt *.md *.rst COPYING LICENSE
recursive-include tests **
recursive-include docs **.rst **.yml **.yaml **.json **.j2 **.txt
recursive-include roles **.yml **.yaml **.json **.j2
recursive-include playbooks **.yml **.yaml **.json
recursive-include changelogs **.yml **.yaml
recursive-include plugins */**.py
recursive-include plugins/become **.yml **.yaml
recursive-include plugins/cache **.yml **.yaml
recursive-include plugins/callback **.yml **.yaml
recursive-include plugins/cliconf **.yml **.yaml
recursive-include plugins/connection **.yml **.yaml
recursive-include plugins/filter **.yml **.yaml
recursive-include plugins/httpapi **.yml **.yaml
recursive-include plugins/inventory **.yml **.yaml
recursive-include plugins/lookup **.yml **.yaml
recursive-include plugins/netconf **.yml **.yaml
recursive-include plugins/shell **.yml **.yaml
recursive-include plugins/strategy **.yml **.yaml
recursive-include plugins/test **.yml **.yaml
recursive-include plugins/vars **.yml **.yaml
recursive-include plugins/modules **.ps1 **.yml **.yaml
recursive-include plugins/module_utils **.ps1 **.psm1 **.cs
# manifest.directives from galaxy.yml inserted here
exclude galaxy.yml galaxy.yaml MANIFEST.json FILES.json <namespace>-<name>-*.tar.gz
recursive-exclude tests/output **
global-exclude /.* /__pycache__

注意

<namespace>-<name>-*.tar.gz 会展开为实际的 namespace 和 name。

galaxy.yml 中提供的 manifest.directives 会插入到默认包含项之后，默认排除项之前。

要在不提供自定义指令的情况下启用清单指令的使用，请在 galaxy.yml 文件中插入 manifest: {} 或 manifest: null，并移除所有 build_ignore 的使用。

如果默认的清单指令无法满足您的需求，您可以将 galaxy.yml 中的 manifest.omit_default_directives 设置为 true。然后，您必须在 galaxy.yml 中指定一套完整的清单指令。上面记录的默认设置是一个很好的起点。

以下是一个不包含默认指令的示例。

manifest:
  directives:
    - include meta/runtime.yml
    - include README.md LICENSE
    - recursive-include plugins */**.py
    - exclude galaxy.yml MANIFEST.json FILES.json <namespace>-<name>-*.tar.gz
    - recursive-exclude tests/output **
  omit_default_directives: true

签名集合

您可以在 Pulp 3 Galaxy 服务器上为您的集合包含 GnuPG 签名。详情请参阅 启用集合签名。

您可以使用 gpg CLI 通过以下步骤为集合手动生成分离签名。此步骤假设您已经生成了 GPG 私钥，但未涵盖该过程。

ansible-galaxy collection build
tar -Oxzf namespace-name-1.0.0.tar.gz MANIFEST.json | gpg --output namespace-name-1.0.0.asc --detach-sign --armor --local-user email@example.com -

准备发布您的集合

每次发布集合时，都必须在分发服务器上创建一个 新版本。在发布集合的某个版本后，您无法删除或修改该版本。为了避免产生不必要的额外版本，请在发布前在本地检查您的集合是否存在错误、拼写错误和其他问题

1. 在本地安装集合。

2. 在发布新版本之前，审查本地安装的集合。

在本地安装您的集合

您有两种在本地安装集合的选项

• 从 tarball 本地安装您的集合。

• 从您的 Git 仓库本地安装您的集合。

从 tarball 本地安装您的集合

要从 tarball 本地安装集合，请运行 ansible-galaxy collection install 并指定集合 tarball。您可以选择使用 -p 标志指定安装位置。例如

collection_dir#> ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections

将 tarball 安装到 COLLECTIONS_PATHS 中配置的目录，以便 Ansible 可以轻松找到并加载该集合。如果您未指定路径值，ansible-galaxy collection install 会将集合安装在 COLLECTIONS_PATHS 中定义的第一个路径中。

从 Git 仓库本地安装您的集合

要从 Git 仓库本地安装集合，请指定您要安装的仓库和分支

collection_dir#> ansible-galaxy collection install git+https://github.com/org/repo.git,devel

您可以从 git 仓库而不是从 Galaxy 或 Automation Hub 安装集合。作为开发者，从 git 仓库安装可以让您在创建 tarball 和发布集合之前审查您的集合。作为用户，从 git 仓库安装可以让您使用尚未出现在 Galaxy 或 Automation Hub 中的集合或版本。此功能旨在作为内容开发者的一种最小捷径，如前所述，git 仓库可能不支持 ansible-galaxy CLI 的全部功能。在复杂情况下，更灵活的选择可能是将仓库 git clone 到集合安装目录的正确文件结构中。

仓库必须包含 galaxy.yml 或 MANIFEST.json 文件。此文件提供元数据，例如集合的版本号和命名空间。

在命令行上从 git 仓库安装集合

要在命令行上从 git 仓库安装集合，请使用仓库的 URI，而不是集合名称或 tar.gz 文件的路径。使用前缀 git+，除非您在使用带有用户 git 的 SSH 认证（例如 git@github.com:ansible-collections/ansible.windows.git）。您可以使用以逗号分隔的 git commit-ish 语法来指定分支、提交或标签。

例如

# Install a collection in a repository using the latest commit on the branch 'devel'
ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel

# Install a collection from a private GitHub repository
ansible-galaxy collection install git@github.com:organization/repo_name.git

# Install a collection from a local git repository
ansible-galaxy collection install git+file:///home/user/path/to/repo_name.git

警告

将凭据嵌入到 git URI 中是不安全的。使用安全的认证选项，防止您的凭据暴露在日志或其他地方。

• 使用 SSH 认证

• 使用 netrc 认证

• 在 git 配置中使用 http.extraHeader

• 在 git 配置中使用 url.<base>.pushInsteadOf

在 git 仓库中指定集合位置

当您从 git 仓库安装集合时，Ansible 会使用集合的 galaxy.yml 或 MANIFEST.json 元数据文件来构建集合。默认情况下，Ansible 会搜索两个路径以查找集合的 galaxy.yml 或 MANIFEST.json 元数据文件：

• 仓库的顶层。

• 仓库路径中的每个目录（深一层）。

如果仓库顶层存在 galaxy.yml 或 MANIFEST.json 文件，Ansible 会使用该文件中的集合元数据来安装单个集合。

├── galaxy.yml
├── plugins/
│   ├── lookup/
│   ├── modules/
│   └── module_utils/
└─── README.md

如果仓库路径中的一个或多个目录（深一层）中存在 galaxy.yml 或 MANIFEST.json 文件，Ansible 会将每个包含元数据的目录安装为集合。例如，Ansible 默认安装此仓库结构中的 collection1 和 collection2：

├── collection1
│   ├── docs/
│   ├── galaxy.yml
│   └── plugins/
│       ├── inventory/
│       └── modules/
└── collection2
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    |   ├── filter/
    |   └── modules/
    └── roles/

如果您有不同的仓库结构，或者只想安装集合的子集，可以在 URI 末尾（在可选的逗号分隔版本之前）添加一个片段，以指示元数据文件的位置。路径应为目录，而不是元数据文件本身。例如，要仅从包含两个集合的示例仓库中安装 collection2：

ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/collection2/

在某些仓库中，主目录对应于命名空间：

namespace/
├── collectionA/
|   ├── docs/
|   ├── galaxy.yml
|   ├── plugins/
|   │   ├── README.md
|   │   └── modules/
|   ├── README.md
|   └── roles/
└── collectionB/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    │   ├── connection/
    │   └── modules/
    ├── README.md
    └── roles/

您可以安装此仓库中的所有集合，或从特定提交中安装一个集合：

# Install all collections in the namespace
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/

# Install an individual collection using a specific commit
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/collectionA/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5

审查您的集合

审查集合

• 运行一个使用您集合中模块和插件的剧本。验证新特性和功能是否按预期工作。有关示例和更多详细信息，请参阅 使用集合。

• 检查文档是否有拼写错误。

• 检查 tarball 的版本号是否高于分发服务器上已发布的最新版本。

• 如果发现任何问题，请修复它们并重新构建集合 tarball。

了解集合版本控制

更改集合的唯一方法是发布新版本。集合的最新版本（按最高版本号计算）是 Galaxy 和 Automation Hub 各处显示的版本。用户仍然可以下载旧版本。

在设置集合版本时，请遵循语义版本控制。总结如下

• 对于不兼容的 API 更改，增加主版本号 x（即 x.y.z 中的 x）。

• 对于以向后兼容方式添加的新功能（例如新模块/插件、参数、返回值），增加次版本号 y（即 x.y.z 中的 y）。

• 对于向后兼容的错误修复，增加修订版本号 z（即 x.y.z 中的 z）。

阅读官方 语义版本控制 文档以获取详细信息和示例。

发布您的集合

分发集合的最后一步是将 tarball 发布到 Ansible Galaxy、Red Hat Automation Hub 或私有托管的 Automation Hub 实例。您可以通过两种方式发布集合

• 从命令行使用 ansible-galaxy collection publish 命令

• 从分发服务器（Galaxy、Automation Hub）本身的网站发布

从命令行发布集合

要使用 ansible-galaxy 从命令行上传集合 tarball

ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz

注意

此 ansible-galaxy 命令假设您已检索并将 API 令牌存储在配置中。详情请参阅 指定您的 API 令牌和分发服务器。

ansible-galaxy collection publish 命令会触发导入过程，就像您通过 Galaxy 网站上传集合一样。该命令会等待导入过程完成后再报告状态。如果您希望在不等待导入结果的情况下继续，请使用 --no-wait 参数，并在您的 我的导入 (My Imports) 页面手动查看导入进度。

从网站发布集合

请参阅 Galaxy 文档，了解如何直接在 Galaxy 网站上发布您的集合。

另请参阅

使用 Ansible 集合

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

集合 Galaxy 元数据结构

galaxy.yml 文件中使用的字段表

交流方式

有疑问？需要帮助？想分享你的想法？请访问 Ansible 通信指南