分发集合

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

注意

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

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

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

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

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 自动化中心和私有自动化中心，您必须先创建一个命名空间，然后才能上传您的集合。要创建命名空间

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

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

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

获取您的 API 令牌

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

要获取您的 API 令牌

• 要获取 Galaxy 的 API 令牌，请转到 Galaxy 个人资料偏好设置 页面，然后单击 API 密钥。

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

构建集合 tarball

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

1. 检查你 galaxy.yml 文件中的所有设置。详情请参考 Collection Galaxy 元数据结构。确保你更新了版本号。每次发布你的 collection 时，它必须有新的版本号。你不能对分发服务器上已有的 collection 版本进行修改。如果你试图上传同一个 collection 版本多次，分发服务器将返回错误 Code: conflict.collection_exists。Collections 遵循语义版本控制规则。有关版本的更多信息，请参阅 了解 collection 版本控制。有关 galaxy.yml 文件的更多信息，请参考 Collection Galaxy 元数据结构.

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

collection_dir#> ansible-galaxy collection build

此命令会在当前目录中构建一个 collection 的 tarball，你可以将其上传到你的分发服务器。

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

注意

• 为了减少 collection 的大小，某些文件和文件夹在默认情况下会被从 collection tarball 中排除。如果你的 collection 目录包含其他你想要排除的文件，请参考 忽略文件和文件夹。

• 当前 Galaxy tarball 的最大尺寸为 2 MB。

你可以将你的 tarball 上传到一个或多个分发服务器。你也可以通过将 tarball 复制到目标系统上直接安装你的 collection 来进行本地分发。

忽略文件和文件夹

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

使用显式忽略包含所有文件

默认情况下，构建步骤会在 collection 目录中包含所有文件，除了以下文件：

• galaxy.yml

• *.pyc

• *.retry

• tests/output

• 根目录中之前构建的 tarball

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

要从你的 collection tarball 中排除其他文件和文件夹，请在 collection 的 galaxy.yml 文件中使用 build_ignore 键设置一个文件 glob-like 模式列表。这些模式使用以下特殊字符进行通配符匹配：

• *: 匹配所有内容

• ?: 匹配任何单个字符

• [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

签署 collection

你可以在 Pulp 3 Galaxy 服务器上包含一个 GnuPG 签名，用于你的 collection。有关详细信息，请参考 启用 collection 签名。

你可以使用以下步骤，使用 gpg CLI 手动生成 collection 的分离签名。此步骤假设你已生成 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] -

准备发布你的 collection

每次发布你的 collection 时，你都必须在分发服务器上创建一个 新版本。在你发布 collection 的某个版本之后，你不能删除或修改该版本。为了避免不必要的额外版本，请在发布之前本地检查你的 collection 是否存在 bug、错别字和其他问题。

1. 在本地安装 collection。

2. 在发布新版本之前，请查看本地安装的 collection。

在本地安装你的 collection

在本地安装你的 collection 时，你有两种选择：

• 从 tarball 在本地安装你的 collection。

• 从你的 Git 仓库在本地安装你的 collection。

从 tarball 在本地安装你的 collection

要从 tarball 在本地安装你的 collection，请运行 ansible-galaxy collection install 并指定 collection tarball。你也可以选择使用 -p 标志指定位置。例如

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

将 tarball 安装到 COLLECTIONS_PATHS 中配置的目录中，以便 Ansible 可以轻松找到并加载 collection。如果你没有指定路径值，ansible-galaxy collection install 会将 collection 安装到 COLLECTIONS_PATHS 中定义的第一个路径中。

从 Git 仓库在本地安装你的 collection

要从 Git 仓库在本地安装你的 collection，请指定仓库和要安装的分支

collection_dir#> ansible-galaxy collection install git+https://github.com/org/repo.git,devel

你可以从 git 仓库而不是从 Galaxy 或 Automation Hub 安装 collection。作为开发者，从 git 仓库安装可以让你在创建 tarball 并发布 collection 之前审查你的 collection。作为用户，从 git 仓库安装可以让你使用尚未在 Galaxy 或 Automation Hub 中的 collection 或版本。此功能旨在作为内容开发者的最小捷径，如前所述，git 仓库可能不支持来自 ansible-galaxy CLI 的完整功能集。在复杂情况下，更灵活的选择可能是将 git clone 仓库到 collection 安装目录的正确文件结构中。

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

从命令行安装来自 git 仓库的 collection

要从命令行安装来自 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

查看您的集合

查看集合

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

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

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

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

了解集合版本控制

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

在为您的集合设置版本时，请遵循语义版本控制。概括来说

• 为不兼容的 API 更改，增加 x.y.z 中的 x（主版本号）。

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

• 为向后兼容的错误修复，增加 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 沟通指南