分发集合

集合是 Ansible 内容的一种分发格式。一个典型的集合包含解决一组相关用例的模块和其他插件。例如，一个集合可以自动化特定数据库的管理。集合还可以包含角色和剧本。

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

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

分发集合包括四个主要步骤

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

2. 构建集合压缩包

3. 准备发布集合

4. 发布集合

分发服务器或服务器的初始配置

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

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 上创建命名空间，请参阅 Ansible 认证内容常见问题解答。

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

获取 API 令牌

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

要获取 API 令牌

• 要获取 Galaxy 的 API 令牌，请转到 Galaxy 个人资料首选项 页面，然后单击 API 密钥。

• 要获取 Automation Hub 的 API 令牌，请转到 令牌页面 并单击 加载令牌。

指定 API 令牌和分发服务器

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

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

• 您可以将令牌作为参数传递给命令行，作为 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

您不能将 apt-key 与 galaxy_server_list 中定义的任何服务器一起使用。有关完整详细信息，请参阅 配置 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 参数是不安全的。在命令行中传递机密可能会将它们暴露给系统上的其他人。

构建集合压缩包

配置完一个或多个分发服务器后，构建集合压缩包。集合压缩包是发布的工件，是您上传和其他人下载以安装您的集合的对象。要构建集合压缩包

1. 查看您galaxy.yml 文件中的版本号。每次发布集合时，它都必须有一个新的版本号。您不能在分发服务器上更改集合的现有版本。如果您尝试多次上传相同的集合版本，分发服务器将返回错误Code: conflict.collection_exists。集合遵循语义版本控制规则。有关版本的更多信息，请参阅了解集合版本控制。有关galaxy.yml 文件的更多信息，请参阅集合 Galaxy 元数据结构。

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

collection_dir#> ansible-galaxy collection build

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

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

注意

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

• 当前 Galaxy 压缩包的最大大小为 2 MB。

您可以将压缩包上传到一个或多个分发服务器。您也可以通过将压缩包复制到目标系统上直接安装您的集合来本地分发您的集合。

忽略文件和文件夹

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

包含所有内容，并进行显式忽略

默认情况下，构建步骤将包含集合目录中的所有文件（压缩包除外），这些文件包括：

• galaxy.yml

• *.pyc

• *.retry

• tests/output

• 根目录中之前构建的压缩包

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

要从集合压缩包中排除其他文件和文件夹，请在集合的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. 在发布新版本之前，查看本地安装的集合。

在本地安装您的集合

您有两种选择可以在本地安装您的集合。

• 从压缩包中在本地安装您的集合。

• 从您的 Git 存储库中在本地安装您的集合。

从压缩包中在本地安装您的集合

要从压缩包中在本地安装您的集合，请运行ansible-galaxy collection install 并指定集合压缩包。您也可以使用-p 标志来指定位置。例如

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

将压缩包安装到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 存储库中安装可以让你在创建压缩包并发布集合之前查看你的集合。作为用户，从 Git 存储库中安装可以让您使用尚未出现在 Galaxy 或 Automation Hub 中的集合或版本。

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

在命令行中从 Git 存储库中安装集合

要从命令行中从 Git 存储库中安装集合，请使用存储库的 URI，而不是集合名称或tar.gz 文件的路径。使用前缀git+，除非您使用 SSH 身份验证并使用用户git（例如，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

回顾你的集合

回顾集合

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

• 检查文档中的错别字。

• 检查你的压缩包的版本号是否高于分发服务器上的最新发布版本。

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

理解集合版本控制

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

在设置集合的版本时遵循语义版本控制。总结

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

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

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

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

发布你的集合

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

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

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

从命令行发布集合

要使用 ansible-galaxy 从命令行上传集合压缩包

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 参数，并在你的 我的导入 页面中手动查看导入进度。

从网站发布集合

要直接在 Galaxy 网站上发布你的集合

1. 转到 我的内容 页面，然后点击你其中一个命名空间上的 **添加内容** 按钮。

2. 在 **添加内容** 对话框中，点击 **上传新集合**，并从本地文件系统中选择集合归档文件。

当你上传集合时，Ansible 始终将压缩包上传到 galaxy.yml 文件中的集合元数据中指定的命名空间，无论你在网站上选择哪个命名空间。如果你不是集合元数据中指定的命名空间的所有者，上传请求将失败。

Galaxy 上传并接受集合后，网站将显示 **我的导入** 页面。此页面显示导入过程信息。你可以在那里查看上传的任何错误或警告。

另请参阅

使用 Ansible 集合

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

集合 Galaxy 元数据结构

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

邮件列表

开发邮件列表

实时聊天

如何加入 Ansible 聊天频道