分发集合

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

注意

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

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

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

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

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

2. 构建你的集合 tar 包

3. 准备发布你的集合

4. 发布你的集合

分发服务器的初始配置

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

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

你不能将 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 包：

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 仓库安装允许您在创建 tar 包并发布集合之前审查您的集合。作为用户，从 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 沟通指南