Использование коллекций в плейбуке

Упрощение имён модулей с помощью ключевого слова collections

Ключевое слово collections позволяет задать список коллекций, в которых роль или плейбук будут искать неквалифицированные имена модулей и действий. Таким образом, можно использовать ключевое слово collections, а затем указывать модули и плагины действий в этой роли или плейбуке просто по их кратким именам.

Использование collections в ролях

Внутри роли можно управлять тем, в каких коллекциях Ansible ищет задачи для этой роли, используя ключевое слово collections в файле meta/main.yml роли. Ansible будет использовать список коллекций, заданный внутри роли, даже если в плейбуке, который вызывает эту роль, в отдельной записи ключевого слова collections заданы другие коллекции. Роли, определённые в коллекции, всегда неявно ищут сначала собственную коллекцию, поэтому для доступа к модулям, действиям и другим ролям из той же коллекции ключевое слово collections использовать не нужно.

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

Использование collections в плейбуках

В плейбуке можно управлять тем, в каких коллекциях Ansible ищет модули и плагины действий для выполнения. Однако для любых ролей, вызываемых в плейбуке, задаётся собственный порядок поиска коллекций; они не наследуют настройки вызывающего плейбука. Это верно, даже если в роли не задано собственное ключевое слово 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 при загрузке плагинов или ролей. Обратите внимание: для плагинов, не являющихся действиями или модулями (например, lookup-плагинов, фильтров и тестов), по-прежнему требуется FQCN.

При использовании ключевого слова collections добавлять ansible.builtin в список поиска не требуется. Если его не указывать, по умолчанию доступно следующее содержимое:

1. Стандартные модули и плагины Ansible, доступные через ansible-base/ansible-core
2. Поддержка устаревших путей к плагинам сторонних разработчиков

Как правило, предпочтительнее использовать FQCN модуля или плагина, а не ключевое слово collections.

Использование плейбука из коллекции

Плейбуки также можно распространять в составе коллекции и вызывать, используя ту же семантику, что и для плагинов:

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

Из плейбука:

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

Несколько рекомендаций по созданию таких плейбуков: 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, как и для ролей.