在 playbook 中使用集合

安装后，你可以通过其完全限定的集合名称 (FQCN) 引用集合内容

- name: Reference a collection content using its FQCN
  hosts: all
  tasks:

    - name: Call a module using FQCN
      my_namespace.my_collection.my_module:
        option1: value

这适用于角色或集合中分发的任何类型的插件

- name: Reference collections contents using their FQCNs
  hosts: all
  tasks:

    - name: Import a role
      ansible.builtin.import_role:
        name: my_namespace.my_collection.role1

    - name: Call a module
      my_namespace.mycollection.my_module:
        option1: value

    - name: Call a debug task
      ansible.builtin.debug:
        msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'

使用 collections 关键字简化模块名称

collections 关键字允许你定义一个集合列表，你的角色或 playbook 应在其中搜索不合格的模块和操作名称。因此，你可以使用 collections 关键字，然后简单地在整个角色或 playbook 中通过其简短名称引用模块和操作插件。

警告

如果你的 playbook 同时使用 collections 关键字和一个或多个角色，则这些角色不会继承 playbook 设置的集合。这就是我们建议你始终使用 FQCN 的原因之一。请参阅下面的角色详细信息。

在角色中使用 collections

在角色中，你可以使用角色 meta/main.yml 中的 collections 关键字控制 Ansible 在角色内部搜索哪些集合。Ansible 将使用角色内部定义的集合列表，即使调用该角色的 playbook 在单独的 collections 关键字条目中定义了不同的集合。集合中定义的角色总是首先隐式搜索它们自己的集合，因此你不需要使用 collections 关键字来访问同一集合中包含的模块、操作或其他角色。

# myrole/meta/main.yml
collections:
  - my_namespace.first_collection
  - my_namespace.second_collection
  - other_namespace.other_collection

在 playbook 中使用 collections

在 playbook 中，你可以控制 Ansible 搜索要执行的模块和操作插件的集合。但是，你在 playbook 中调用的任何角色都会定义它们自己的集合搜索顺序；它们不会继承调用 playbook 的设置。即使角色没有定义它自己的 collections 关键字，也是如此。

- name: Run a play using the collections keyword
  hosts: all
  collections:
    - my_namespace.my_collection

  tasks:

    - name: Import a role
      ansible.builtin.import_role:
        name: role1

    - name: Run a module not specifying FQCN
      my_module:
        option1: value

    - name: Run a debug task
      ansible.builtin.debug:
        msg: '{{ lookup("my_namespace.my_collection.lookup1", "param1")| my_namespace.my_collection.filter1 }}'

collections 关键字只是为非命名空间插件和角色引用创建了一个有序的“搜索路径”。它不会安装内容或以其他方式更改 Ansible 加载插件或角色时的行为。请注意，非操作或模块插件（例如，查找、过滤器和测试）仍然需要 FQCN。

当使用 collections 关键字时，没有必要将 ansible.builtin 作为搜索列表的一部分添加。当省略时，以下内容默认可用

  1. 通过 ansible-base/ansible-core 提供的标准 Ansible 模块和插件

  2. 支持旧的第三方插件路径

一般来说，最好使用模块或插件的 FQCN 而不是 collections 关键字。

使用集合中的 playbook

2.11 版本中的新功能。

你还可以在你的集合中分发 playbook，并使用与插件相同的语义调用它们

ansible-playbook my_namespace.my_collection.playbook1 -i ./myinventory

从 playbook 内部

- name: Import a playbook
  ansible.builtin.import_playbook: my_namespace.my_collection.playbookX

在创建此类 playbook 时，有几个建议，hosts: 应该是通用的，或者至少应该有一个变量输入。

- hosts: all  # Use --limit or customized inventory to restrict hosts targeted

- hosts: localhost  # For things you want to restrict to the control node

- hosts: '{{target|default("webservers")}}'  # Assumes inventory provides a 'webservers' group, but can also use ``-e 'target=host1,host2'``

这将在 collections: 关键字中有一个隐含的条目 my_namespace.my_collection，就像角色一样。

注意

  • playbook 名称与其他集合资源一样，有一组受限制的有效字符。名称只能包含小写字母数字字符，加上 _ 并且必须以字母字符开头。破折号 - 字符对于集合中的 playbook 名称无效。名称包含无效字符的 playbook 是不可寻址的：这是用于加载集合资源的 Python 导入器的限制。

  • 集合中的 playbook 不支持“相邻”插件，所有插件必须位于集合特定的目录中。