分发集合

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

注意

在分发您的集合之前，请确保您已更新 galaxy.yml 文件。有关详细信息，请参阅 集合结构。

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

分发服务器	接受的集合
Ansible Galaxy	所有集合
Pulp 3 Galaxy	所有集合，支持签名集合
Red Hat 自动化中心	仅限由 Red Hat 认证的集合，支持签名集合
私有托管的自动化中心	由所有者授权的集合

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

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 自动化中心和私有自动化中心，您必须在上传您的集合之前创建命名空间。要创建命名空间

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

• 要创建 Red Hat 自动化中心上的命名空间，请参阅 Ansible 认证内容常见问题解答。

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

获取您的 API 令牌

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

要获取您的 API 令牌

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

• 要获取自动化中心的 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 参数是不安全的。在命令行中传递机密可能会将它们暴露给系统上的其他人。

构建您的集合压缩包

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

1. 检查galaxy.yml文件中的所有设置。有关详细信息，请参阅Collection Galaxy 元数据结构。确保已更新版本号。每次发布集合时，它必须具有一个新的版本号。您不能在分发服务器上对集合的现有版本进行更改。如果您尝试多次上传相同的集合版本，分发服务器将返回错误Code: conflict.collection_exists。集合遵循语义版本控制规则。有关版本的更多信息，请参阅理解集合版本控制。有关galaxy.yml文件的更多信息，请参阅Collection 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文件的更多信息，请参阅Collection 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+，除非您使用 SSH 身份验证且用户为 git（例如，[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 会从以下仓库结构中安装集合 1 和集合 2

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

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

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 中的 x。

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

• 对于向后兼容的错误修复，请增加补丁版本号 z，即 x.y.z 中的 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 沟通指南