集合结构

集合是一个简单的数据结构。除非你有特定的内容属于其中一个目录，否则所有目录都是可选的。一个集合需要在集合的根目录级别有一个 galaxy.yml 文件。此文件包含 Galaxy 和其他工具打包、构建和发布集合所需的所有元数据。

集合目录和文件 

一个集合可以包含以下目录和文件

collection/
├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   └── .../
├── README.md
├── roles/
│   ├── role1/
│   ├── role2/
│   └── .../
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   └── tasks/
└── tests/

注意

Ansible 仅接受 .md 扩展名作为 README 文件和 /docs 文件夹中的任何文件的扩展名。
有关集合结构示例，请参阅 ansible-collections GitHub 组织。
并非所有目录当前都在使用。这些是未来功能的占位符。

galaxy.yml 

一个集合必须有一个 galaxy.yml 文件，其中包含构建集合工件所需的信息。有关详细信息，请参阅集合 Galaxy 元数据结构。

docs 目录 

使用 docs 文件夹来描述如何使用集合提供的角色和插件，角色需求等等。

对于已认证的集合，Automation Hub 会显示在主 docs 目录中没有子目录的以 markdown 编写的文档。此文档不会发布到 docs.ansible.com 。

对于包含在 Ansible PyPI 软件包中的社区集合，docs.ansible.com 会显示以 reStructuredText (.rst) 编写的文档，这些文档位于 docsite/rst/ 子目录中。在 docs/docsite/extra-docs.yml 中定义额外文档的结构。

---
sections:
- title: Scenario Guide
  toctree:
    - scenario_guide

集合文档的索引页面将显示您在 docs/docsite/extra-docs.yml 中定义的标题，并提供指向您的额外文档的链接。例如，请参阅 community.docker 集合存储库和 community.docker 集合文档。

您可以在集合索引页面和插件页面中添加额外的链接，方法是使用 docs/docsite/links.yml 文件。这将在描述和通信标题下填充链接，以及在各个插件页面末尾填充链接。有关此文件结构和使用情况的完整说明，请参阅 collection_template links.yml 文件。

插件和模块文档

将插件和模块的特定文档嵌入到 Python docstring 中。使用 ansible-doc 来查看集合内插件的文档。

ansible-doc -t lookup my_namespace.my_collection.lookup1

ansible-doc 命令需要完全限定的集合名称 (FQCN) 来显示特定插件文档。在此示例中， my_namespace 是 Galaxy 命名空间， my_collection 是该命名空间内的集合名称。

注意

Ansible 集合的 Galaxy 命名空间在 galaxy.yml 文件中定义。它可能与 GitHub 组织或存储库名称不同。

plugins 目录 

在此处添加“每个插件类型”特定的子目录，包括 module_utils ，它不仅可供模块使用，还可供大多数插件通过使用它们的 FQCN 使用。这是一种在无需在每个剧本中导入角色的情况下分发模块、查找、过滤器等等的方法。

集合中的 Vars 插件不会自动加载，并且始终需要使用其完全限定的集合名称显式启用。有关详细信息，请参阅启用 vars 插件。

集合中的缓存插件可用于事实缓存，但不支持用于库存插件。

module_utils

在集合中使用 module_utils 进行编码时，Python import 语句需要考虑 FQCN 以及 ansible_collections 约定。最终的 Python 导入将类似于 from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something} 。

以下示例代码段显示了一个使用默认 Ansible module_utils 以及集合提供的 module_utils 的 Python 和 PowerShell 模块。在此示例中，命名空间是 community ，集合是 test_collection 。在 Python 示例中，所讨论的 module_util 称为 qradar ，因此其 FQCN 是 community.test_collection.plugins.module_utils.qradar 。

from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_text

from ansible.module_utils.six.moves.urllib.parse import urlencode, quote_plus
from ansible.module_utils.six.moves.urllib.error import HTTPError
from ansible_collections.community.test_collection.plugins.module_utils.qradar import QRadarRequest

argspec = dict(
    name=dict(required=True, type='str'),
    state=dict(choices=['present', 'absent'], required=True),
)

module = AnsibleModule(
    argument_spec=argspec,
    supports_check_mode=True
)

qradar_request = QRadarRequest(
    module,
    headers={"Content-Type": "application/json"},
    not_rest_data_keys=['state']
)

请注意，从 __init__.py 文件导入内容需要使用文件名。

from ansible_collections.namespace.collection_name.plugins.callback.__init__ import CustomBaseClass

在 PowerShell 示例中，所讨论的 module_util 称为 hyperv ，因此其 FQCN 是 community.test_collection.plugins.module_utils.hyperv 。

#!powershell
#AnsibleRequires -CSharpUtil Ansible.Basic
#AnsibleRequires -PowerShell ansible_collections.community.test_collection.plugins.module_utils.hyperv

$spec = @{
    name = @{ required = $true; type = "str" }
    state = @{ required = $true; choices = @("present", "absent") }
}
$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)

Invoke-HyperVFunction -Name $module.Params.name

$module.ExitJson()

roles 目录 

集合角色与现有角色基本相同，但有一些限制。

角色名称现在仅限于包含小写字母数字字符、加号 _ 以及以字母字符开头。

集合中的角色不再包含插件。插件必须位于集合 plugins 目录树中。每个插件都可供集合中的所有角色访问。

角色的目录名称用作角色名称。因此，目录名称必须符合上述角色名称规则。如果角色名称不符合这些规则，则集合导入到 Galaxy 将失败。

您可以将“传统角色”迁移到集合，但它们必须遵循上述规则。如果它们不符合规则，则可能需要重命名角色。您必须将所有基于角色的插件移动到集合特定目录，或者将它们链接到集合特定目录。

注意

对于直接从 GitHub 存储库导入到 Galaxy 的角色，在角色元数据中设置 role_name 值会覆盖 Galaxy 使用的角色名称。对于集合，该值会被忽略。导入集合时，Galaxy 会使用角色目录作为角色的名称，并忽略 role_name 元数据值。

playbooks 目录 

在之前的版本中，您可以使用从命令行到剧本文件的完整路径来引用此目录中的剧本。在 ansible-core 2.11 及更高版本中，您可以使用 FQCN， namespace.collection.playbook （带或不带扩展名），从命令行或从 import_playbook 中引用剧本。这将使剧本保持在“集合上下文中”，就好像您在其中添加了 collections: [ namespace.collection ] 一样。

您可以拥有大多数预期的子目录，例如 files/、vars/ 或 templates/，但没有 roles/，因为这些已经在集合中处理。

此外，集合中的剧本遵循与任何剧本相同的准则，除了以下几项调整。

目录：它必须位于 playbooks/ 目录中。

主机：主机应定义为变量，这样剧本的用户就不会错误地针对整个清单运行任务（如果主机设置为 all）。例如 - hosts: '{{target|default("all")}}'。

要运行任务，用户现在可以使用诸如 ansible-playbook --e 'targets=webservers' 或 ansible-playbook --limit webservers' 之类的命令。无论哪种方式，集合所有者都应该在 docs/ 文件夹或 README 文件中记录他们的剧本以及如何使用它们。

tests 目录 

Ansible 集合的测试方式与 Ansible 本身非常相似，使用 ansible-test 实用程序，该实用程序作为 Ansible 2.9.0 及更高版本的一部分发布。由于 Ansible 集合使用与 Ansible 本身相同的工具（使用 ansible-test）进行测试，因此所有 Ansible 开发人员测试文档都适用于编写集合测试，只需要记住一个关键概念。

有关如何使用 ansible-test 测试集合的特定信息，请参见测试集合。

在阅读测试 Ansible 文档时，会有适用于从 Git 克隆通过源代码运行 Ansible 的内容，这对于 Ansible 开发人员来说是典型的。但是，对于 Ansible 集合作者来说，从源代码运行 Ansible 并不总是典型的，而是从稳定版本运行，并且创建集合不需要从源代码运行 Ansible。因此，当在测试 Ansible 文档中引用处理 ansible-test 二进制路径、命令完成或环境变量时；请记住，对于 Ansible 集合测试来说，这并不是必需的，因为安装包含 ansible-test 的 Ansible 稳定版本的行为应该为您设置这些内容。

meta 目录 

runtime.yml

集合可以在集合的 meta 目录中的 runtime.yml 文件中存储一些额外的元数据。 runtime.yml 文件支持顶级键

requires_ansible:

使用集合所需的 Ansible Core (ansible-core) 版本。多个版本可以用逗号分隔。
```
requires_ansible: ">=2.10,<2.11"
```
注意

虽然版本在幕后是 PEP440 版本说明符，但 Ansible 通过截断 Ansible 版本的预发布段来偏离 PEP440 行为。这意味着 Ansible 2.11.0b1 与 requires_ansible: ">=2.11" 相兼容。

plugin_routing:

集合中 Ansible 需要从其他位置加载的内容，或者已弃用/删除的内容。 plugin_routing 的顶级键是插件类型，具有作为子键的单个插件名称。要为插件定义一个新位置，请将 redirect 字段设置为另一个名称。要弃用插件，请使用 deprecation 字段提供自定义警告消息以及删除版本或日期。如果插件已重命名或移动到新位置，则还应提供 redirect 字段。如果插件将被完全删除，则可以使用 tombstone 用于致命错误消息和删除版本或日期。

plugin_routing:
  inventory:
    kubevirt:
      redirect: community.general.kubevirt
    my_inventory:
      tombstone:
        removal_version: "2.0.0"
        warning_text: my_inventory has been removed. Please use other_inventory instead.
  modules:
    my_module:
      deprecation:
        removal_date: "2021-11-30"
        warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.
      redirect: another.collection.new_module
    podman_image:
      redirect: containers.podman.podman_image
  module_utils:
    ec2:
      redirect: amazon.aws.ec2
    util_dir.subdir.my_util:
      redirect: namespace.name.my_util

import_redirection

Python 导入语句名称及其重定向位置的映射。

import_redirection:
  ansible.module_utils.old_utility:
    redirect: ansible_collections.namespace_name.collection_name.plugins.module_utils.new_location

action_groups

组及其包含的动作插件和模块名称的映射。它们还可能在列表中包含一个特殊的“metadata”字典，该字典可用于包含来自其他组的动作。

action_groups:
  groupname:
    # The special metadata dictionary. All action/module names should be strings.
    - metadata:
        extend_group:
          - another.collection.groupname
          - another_group
    - my_action
  another_group:
    - my_module
    - another.collection.another_module

execution_environments.yml

如果您的集合有要求，您可以在 meta 目录中的 execution-environment.yml 文件中指定它们。这样可以确保用户在构建包含您的集合的执行环境时无需手动添加这些要求。有关详细信息，请参见集合级元数据指南。

另请参见

分发集合: 了解如何打包和发布您的集合
为 Ansible 维护的集合做出贡献: 为选定集合做出贡献的指南
沟通: 有问题？需要帮助？想分享您的想法？请访问 Ansible 沟通指南