分发集合

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

注意

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

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

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

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

初始配置您的一个或多个分发服务器
构建您的集合 tar 包
准备发布您的集合
发布您的集合

初始配置您的一个或多个分发服务器 

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

在您要使用的每个分发服务器上创建一个命名空间。
获取您要使用的每个分发服务器的 API 令牌。
指定您要使用的每个分发服务器的 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

您不能将 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 参数是不安全的。在命令行上传递秘密可能会将它们暴露给系统上的其他人。

构建您的集合 tar 包 

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

查看 galaxy.yml 文件中的所有设置。有关详细信息，请参见集合 Galaxy 元数据结构。确保您已更新版本号。每次发布集合时，它都必须具有新的版本号。您不能更改分发服务器上现有集合版本的设置。如果您尝试多次上传相同的集合版本，分发服务器将返回错误 Code: conflict.collection_exists。集合遵循语义版本控制规则。有关版本的更多信息，请参见了解集合版本控制。有关 galaxy.yml 文件的更多信息，请参见集合 Galaxy 元数据结构。
在集合的顶层目录内运行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] -

准备发布您的集合 

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

在本地安装集合。
在发布新版本之前，请检查本地安装的集合。

在本地安装您的集合 

您有两种在本地安装集合的方法：

从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。验证新功能是否按预期工作。有关示例和更多详细信息，请参阅使用集合。
检查文档中的错别字。
检查您的 tar 包的版本号是否高于分发服务器上的最新已发布版本。
如果您发现任何问题，请修复它们并重新构建集合 tar 包。

了解集合版本控制 

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

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

对于不兼容的 API 更改，请递增主版本号 x（在 x.y.z 中）。
对于向后兼容的新功能（例如新的模块/插件、参数、返回值），请递增次版本号 y（在 x.y.z 中）。
对于向后兼容的错误修复，请递增修订版本号 z（在 x.y.z 中）。

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

发布您的集合 

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

使用 ansible-galaxy collection publish 命令从命令行发布。
通过分发服务器（Galaxy、Automation Hub）的网站本身发布。

从命令行发布集合 

要使用 ansible-galaxy 从命令行上传集合 tar 包：

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 文档，了解如何直接在 Galaxy 网站上发布您的集合。

另请参阅

使用 Ansible 集合: 了解如何安装和使用集合。
集合 Galaxy 元数据结构: galaxy.yml 文件中使用的字段表
联系方式: 有问题？需要帮助？想分享您的想法？请访问 Ansible 联系指南。