安装集合

注意

如果你按照本段所述手动安装集合，那么当你升级 ansible 软件包或 ansible-core 时，该集合不会自动升级。

在容器中安装集合

你可以在称为执行环境的容器中安装集合及其依赖项。有关详细信息，请参阅执行环境入门。

使用 `ansible-galaxy` 安装集合

默认情况下，ansible-galaxy collection install 使用 https://galaxy.ansible.com 作为 Galaxy 服务器（如 ansible.cfg 文件中 GALAXY_SERVER 所示）。你无需任何其他配置。默认情况下，Ansible 将集合安装在 ~/.ansible/collections 的 ansible_collections 目录下。

如果你正在使用任何其他 Galaxy 服务器（例如 Red Hat Automation Hub），请参阅配置 ansible-galaxy 客户端。

要安装托管在 Galaxy 中的集合

ansible-galaxy collection install my_namespace.my_collection

要将集合升级到 Galaxy 服务器上可用的最新版本，你可以使用 --upgrade 选项

ansible-galaxy collection install my_namespace.my_collection --upgrade

你也可以直接使用你的构建中的 tarball

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

你可以从本地源目录构建和安装集合。 ansible-galaxy 实用程序将使用目录中的 MANIFEST.json 或 galaxy.yml 元数据构建集合。

ansible-galaxy collection install /path/to/collection -p ./collections

你也可以在命名空间目录中安装多个集合。

ns/
├── collection1/
│   ├── MANIFEST.json
│   └── plugins/
└── collection2/
    ├── galaxy.yml
    └── plugins/

ansible-galaxy collection install /path/to/ns -p ./collections

注意

安装命令会自动将路径 ansible_collections 附加到使用 -p 选项指定的路径，除非父目录已经在名为 ansible_collections 的文件夹中。

当使用 -p 选项指定安装路径时，请使用 COLLECTIONS_PATHS 中配置的值之一，因为这是 Ansible 本身期望找到集合的位置。如果你没有指定路径，ansible-galaxy collection install 会将集合安装到 COLLECTIONS_PATHS 中定义的第一个路径，默认情况下是 ~/.ansible/collections。

使用签名验证安装集合

如果集合已由分发服务器签署，则服务器将提供 ASCII 盔甲化的分离签名，以在使用它来验证集合内容之前验证 MANIFEST.json 的真实性。此选项并非在所有分发服务器上都可用。有关支持集合签名的服务器列表，请参阅分发集合中的表格。

要对签署的集合使用签名验证

为 ansible-galaxy 配置 GnuPG 密钥环，或者在你安装签署的集合时使用 --keyring 选项提供密钥环的路径。

将分发服务器上的公钥导入该密钥环。

gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc

在你安装集合时验证签名。
```
ansible-galaxy collection install my_namespace.my_collection --keyring ~/.ansible/pubring.kbx
```
如果你已配置 GnuPG 密钥环，则无需使用 --keyring 选项。
可选地，可以在安装后随时验证签名，以证明集合未被篡改。有关详细信息，请参阅验证签署的集合。

你也可以包含除分发服务器提供的签名之外的其他签名。使用 --signature 选项使用这些附加签名验证集合的 MANIFEST.json。补充签名应作为 URI 提供。

ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --keyring ~/.ansible/pubring.kbx

GnuPG 验证仅针对从分发服务器安装的集合进行。用户提供的签名不用于验证从 Git 仓库、源目录或指向 tar.gz 文件的 URL/路径安装的集合。

你也可以在集合 requirements.yml 文件中的 signatures 键下包含其他签名。

# requirements.yml
collections:
  - name: ns.coll
    version: 1.0.0
    signatures:
      - https://examplehost.com/detached_signature.asc
      - file:///path/to/local/detached_signature.asc

有关如何使用此文件安装集合的详细信息，请参阅集合需求文件。

默认情况下，如果至少有一个签名成功验证了集合，则验证被认为成功。可以使用 --required-valid-signature-count 或 GALAXY_REQUIRED_VALID_SIGNATURE_COUNT 配置所需的签名数量。可以通过将选项设置为 all 来要求所有签名。如果未找到任何有效签名，则要使签名验证失败，请在值前面加上 +，例如 +all 或 +1。

export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=2
ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc

可以使用 --ignore-signature-status-code 或 GALAXY_REQUIRED_VALID_SIGNATURE_COUNT 忽略某些 GnuPG 错误。 GALAXY_REQUIRED_VALID_SIGNATURE_COUNT 应该是一个列表，并且可以多次提供 --ignore-signature-status-code 来忽略多个其他错误状态代码。

此示例要求分发服务器提供的任何签名验证集合，除非它们因 NO_PUBKEY 失败

export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=all
ansible-galaxy collection install my_namespace.my_collection --ignore-signature-status-code NO_PUBKEY

如果上述示例的验证失败，则只会显示除 NO_PUBKEY 之外的错误。

如果验证不成功，则不会安装集合。可以使用 --disable-gpg-verify 或通过配置 GALAXY_DISABLE_GPG_VERIFY 禁用 GnuPG 签名验证。

安装较旧版本的集合

您一次只能安装一个版本的集合。默认情况下，ansible-galaxy会安装最新版本。如果您想安装特定版本，可以添加版本范围标识符。例如，要安装集合的 1.0.0-beta.1 版本

ansible-galaxy collection install my_namespace.my_collection:==1.0.0-beta.1

您可以使用 , 分隔指定多个范围标识符。使用单引号，这样 shell 才能传递整个命令，包括 >、! 和其他运算符。例如，要安装大于等于 1.0.0 且小于 2.0.0 的最新版本

ansible-galaxy collection install 'my_namespace.my_collection:>=1.0.0,<2.0.0'

Ansible 将始终安装满足您指定的范围标识符的最新版本。您可以使用以下范围标识符

*：最新版本。这是默认值。
!=：不等于指定版本。
==：与指定版本完全相同。
>=：大于或等于指定版本。
>：大于指定版本。
<=：小于或等于指定版本。
<：小于指定版本。

注意

默认情况下，ansible-galaxy会忽略预发布版本。要安装预发布版本，您必须使用 == 范围标识符来显式要求它。

使用需求文件安装多个集合

您可以设置一个 requirements.yml 文件，以便用一个命令安装多个集合。此文件是一个 YAML 文件，格式如下

---
collections:
# With just the collection name
- my_namespace.my_collection

# With the collection name, version, and source options
- name: my_namespace.my_other_collection
  version: ">=1.2.0" # Version range identifiers (default: ``*``)
  source: ... # The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)

您可以为每个集合条目指定以下键

name

version

signatures

source

type

version 键使用与安装较旧版本的集合中记录的相同的范围标识符格式。

signatures 键接受一个签名源列表，这些签名源用于补充在集合安装和 ansible-galaxy collection verify 期间在 Galaxy 服务器上找到的签名源。签名源应是包含分离签名的 URI。如果指定了签名，则必须提供 --keyring CLI 选项。

签名仅用于验证 Galaxy 服务器上的集合。用户提供的签名不用于验证从 git 存储库、源目录或 tar.gz 文件的 URL/路径安装的集合。

collections:
  - name: namespace.name
    version: 1.0.0
    type: galaxy
    signatures:
      - https://examplehost.com/detached_signature.asc
      - file:///path/to/local/detached_signature.asc

type 键可以设置为 file、galaxy、git、url、dir 或 subdirs。如果省略了 type，则 name 键用于隐式确定集合的来源。

使用 type: git 安装集合时，version 键可以引用分支或 git commit-ish 对象（提交或标签）。例如

collections:
  - name: https://github.com/organization/repo_name.git
    type: git
    version: devel

您还可以在 requirements.yml 文件中，在 roles 键下添加角色。这些值遵循与旧版本 Ansible 中使用的需求文件相同的格式。

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: "1.9.6" # note that ranges are not supported for roles


collections:
  # Install a collection from Ansible Galaxy.
  - name: geerlingguy.php_roles
    version: ">=0.9.3"
    source: https://galaxy.ansible.com

要同时使用一个命令安装角色和集合，请运行以下命令

$ ansible-galaxy install -r requirements.yml

运行 ansible-galaxy collection install -r 或 ansible-galaxy role install -r 将分别仅安装集合或角色。

注意

当指定自定义集合或角色安装路径时，从同一个需求文件安装角色和集合将无法正常工作。在这种情况下，将跳过集合，该命令将像 ansible-galaxy role install 一样处理每个集合。

下载集合以供离线使用

要从 Galaxy 下载集合压缩包以供离线使用，请执行以下操作

导航到集合页面。
单击下载压缩包。

您可能还需要手动下载任何依赖的集合。

在剧本旁边安装集合

您可以将集合在本地安装到项目中的剧本旁边，而不是安装到系统上的全局位置或 AWX 上。

在剧本旁边使用本地安装的集合有一些好处，例如

确保项目的所有用户都使用相同的集合版本。
使用自包含项目可以轻松地在不同环境之间移动。提高可移植性还能在设置新环境时减少开销。这在云环境中部署 Ansible 剧本时是一个优势。
在本地管理集合可以让您将它们与剧本一起版本化。
在本地安装集合可以将它们与在有多个项目的环境中的全局安装隔离。

以下是在 collections/ansible_collections/ 目录结构下将集合保留在当前剧本旁边的示例。

./
├── play.yml
├── collections/
│   └── ansible_collections/
│               └── my_namespace/
│                   └── my_collection/<collection structure lives here>

有关集合目录结构的详细信息，请参阅集合结构。

从源文件安装集合

Ansible 还可以通过几种方式从源目录进行安装

collections:
  # directory containing the collection
  - source: ./my_namespace/my_collection/
    type: dir

  # directory containing a namespace, with collections as subdirectories
  - source: ./my_namespace/
    type: subdirs

Ansible 还可以通过直接指定输出文件来安装使用 ansible-galaxy collection build 收集或从 Galaxy 下载以供离线使用的集合

collections:
  - name: /tmp/my_namespace-my_collection-1.0.0.tar.gz
    type: file

注意

相对路径是从当前工作目录（您从那里调用 ansible-galaxy install -r 的位置）计算得出的。它们不是相对于 requirements.yml 文件进行计算的。

从 Git 存储库安装集合

您可以从 Git 存储库安装集合，而不是从 Galaxy 或 Automation Hub 安装。作为开发人员，从 Git 存储库安装可以让您在创建压缩包和发布集合之前查看您的集合。作为用户，从 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

配置 `ansible-galaxy` 客户端

默认情况下，ansible-galaxy 使用 https://galaxy.ansible.com 作为 Galaxy 服务器（如 ansible.cfg 文件中 GALAXY_SERVER 所示）。

你可以使用以下任一选项来配置 ansible-galaxy collection 以使用其他服务器（例如自定义 Galaxy 服务器）。

在 GALAXY_SERVER_LIST 配置选项中设置服务器列表，该选项位于配置文件中。
使用 --server 命令行参数限制到单个服务器。

要在 ansible.cfg 中配置 Galaxy 服务器列表，请执行以下操作：

在 [galaxy] 部分下添加 server_list 选项，并将一个或多个服务器名称添加到该选项中。
为每个服务器名称创建一个新的部分。
设置每个服务器名称的 url 选项。
可以选择设置每个服务器名称的 API 令牌。访问 https://galaxy.ansible.com/me/preferences 并单击显示 API 密钥。

注意

每个服务器名称的 url 选项必须以正斜杠 / 结尾。如果你没有在 Galaxy 服务器列表中设置 API 令牌，请使用 --api-key 参数将令牌传递给 ansible-galaxy collection publish 命令。

以下示例显示了如何配置多个服务器。

[galaxy]
server_list = my_org_hub, release_galaxy, test_galaxy, my_galaxy_ng

[galaxy_server.my_org_hub]
url=https://automation.my_org/
username=my_user
password=my_pass

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token

[galaxy_server.test_galaxy]
url=https://galaxy-dev.ansible.com/
token=my_test_token

[galaxy_server.my_galaxy_ng]
url=http://my_galaxy_ng:8000/api/automation-hub/
auth_url=http://my_keycloak:8080/auth/realms/myco/protocol/openid-connect/token
client_id=galaxy-ng
token=my_keycloak_access_token

注意

你可以使用 --server 命令行参数在 server_list 中选择一个明确的 Galaxy 服务器，该参数的值应与服务器名称匹配。要使用服务器列表中不存在的服务器，请将该值设置为访问该服务器的 URL（服务器列表中的所有服务器将被忽略）。此外，你不能对任何预定义服务器使用 --api-key 参数。只有当你没有定义服务器列表，或者在 --server 参数中指定了一个 URL 时，才能使用 api_key 参数。

Galaxy 服务器列表配置选项

GALAXY_SERVER_LIST 选项是一个按优先级排序的服务器标识符列表。在搜索集合时，安装过程将按此顺序搜索，例如，首先搜索 automation_hub，然后搜索 my_org_hub，再搜索 release_galaxy，最后搜索 test_galaxy，直到找到该集合。实际的 Galaxy 实例将在 [galaxy_server.{{ id }}] 部分下定义，其中 {{ id }} 是在列表中定义的服务器标识符。然后，该部分可以定义以下键。

url：要连接到的 Galaxy 实例的 URL。必填。
token：用于对 Galaxy 实例进行身份验证的 API 令牌密钥。与 username 相互排斥。
username：用于对 Galaxy 实例进行基本身份验证的用户名。与 token 相互排斥。
password：用于基本身份验证的密码，与 username 结合使用。
auth_url：如果使用 SSO 身份验证（例如 galaxyNG），则为 Keycloak 服务器 ‘token_endpoint’ 的 URL。与 username 相互排斥。需要 token。
validate_certs：是否验证 Galaxy 服务器的 TLS 证书。默认情况下为 True，除非提供了 --ignore-certs 选项或 GALAXY_IGNORE_CERTS 配置为 True。
client_id：要用于身份验证的 Keycloak 令牌的 client_id。需要 auth_url 和 token。默认的 client_id 是 cloud-services，用于与 Red Hat SSO 协作。
timeout：等待 Galaxy 服务器响应的最大秒数。

除了在 ansible.cfg 文件中定义这些服务器选项外，你也可以将它们定义为环境变量。环境变量的格式为 ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}，其中 {{ id }} 是服务器标识符的大写形式，而 {{ key }} 是要定义的键。例如，你可以通过设置 ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token 来定义 release_galaxy 的 token。

对于仅使用一个 Galaxy 服务器的操作（例如，publish、info 或 install 命令），ansible-galaxy collection 命令会使用 server_list 中的第一项，除非你使用 --server 参数传递了明确的服务器。

注意

ansible-galaxy 可以搜索其他配置的 Galaxy 实例中的依赖项，以支持以下用例：一个集合可以依赖于来自另一个 Galaxy 实例的集合。

删除集合

如果你不再需要一个集合，只需从文件系统中删除安装目录即可。路径可能因你的操作系统而异。

rm -rf ~/.ansible/collections/ansible_collections/community/general
rm -rf ./venv/lib/python3.9/site-packages/ansible_collections/community/general