分发集合

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

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

分发服务器	接受的集合
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 上的命名空间，请参阅Ansible 认证内容常见问题解答。

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

获取您的 API 令牌

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

要获取您的 API 令牌

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

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

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

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

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

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

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

默认情况下，Ansible Galaxy 被配置为唯一的分发服务器。您可以添加其他分发服务器并在配置中指定您的 API 令牌或令牌，方法是编辑ansible.cfg文件的galaxy_server_list部分。这是管理分发服务器身份验证的最安全方法。为每个服务器指定 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参数是不安全的。在命令行中传递机密可能会将其暴露给系统上的其他人。

构建您的集合 tarball

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

1. 检查您 galaxy.yml 文件中的版本号。每次发布集合时，都必须使用新的版本号。您不能更改分发服务器上现有集合的版本。如果您尝试多次上传同一集合版本，分发服务器将返回错误 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 大小为 2 MB。

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

忽略文件和文件夹

您可以使用 build_ignore 或 清单指令 从集合中排除文件。有关 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 protected] -

准备发布您的集合

每次发布集合时，都必须在分发服务器上创建 新版本。发布集合版本后，您无法删除或修改该版本。为了避免不必要的额外版本，请在发布之前在本地检查集合中的错误、错别字和其他问题

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 身份验证（例如，[email protected]: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 [email protected]: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

查看您的集合

检查集合。

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

• 检查文档中是否有任何错别字。

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

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

了解集合版本控制

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

在设置集合版本时，请遵循语义化版本控制。总而言之

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

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

• 对于向后兼容的错误修复，请递增修订版本号 z（在 x.y.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 参数，并在您的 我的导入 页面中手动查看导入进度。

从网站发布集合

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

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

2. 在“添加内容”对话框中，单击“上传新集合”，然后从本地文件系统中选择集合归档文件。

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

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

另请参见

使用 Ansible 集合

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

集合 Galaxy 元数据结构

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

沟通

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