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

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

Вы можете устанавливать и использовать коллекции через Ansible Galaxy.

• Подробную информацию о разработке коллекций см. в Руководстве по разработке коллекций.
• Состояние разработки Коллекций и часто задаваемые вопросы см. в Руководстве сообщества Ansible Collections.

• Установка коллекций

  • Установка коллекций с помощью ansible-galaxy
  • Установка более старой версии коллекции
  • Установка коллекции из репозитория Git
  • Основные места поиска репозиториев
  • Указание места поиска коллекций
  • Установка нескольких коллекций с помощью файла требований
  • Загрузка коллекции для автономного использования
  • Настройка клиента ansible-galaxy
• Загрузка коллекций
• Список коллекций

• Проверка коллекций

  • Проверка коллекций с помощью ansible-galaxy
• Использование коллекций в плейбуке

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

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

Установка коллекций

Установка коллекций с помощью ansible-galaxy

По умолчанию, ansible-galaxy collection install использует https://galaxy.ansible.com в качестве сервера Galaxy (как указано в файле ansible.cfg в разделе GALAXY_SERVER). Вам не нужна дополнительная настройка.

См. Настройка клиента ansible-galaxy, если вы используете другой сервер Galaxy, такой как Red Hat Automation Hub.

Для установки коллекции, размещённой в Galaxy:

ansible-galaxy collection install my_namespace.my_collection

Вы также можете напрямую использовать пакет tarball из своего билда:

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

При использовании опции -p для указания пути установки используйте одно из значений, настроенных в COLLECTIONS_PATHS, так как именно здесь Ansible ожидает найти коллекции. Если вы не укажете путь, ansible-galaxy collection install устанавливает коллекцию в первый путь, определённый в COLLECTIONS_PATHS, который по умолчанию равен ~/.ansible/collections

Вы также можете сохранить коллекцию рядом с текущим плейбуком, в структуре каталогов collections/ansible_collections/.

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

См. Структура коллекции для получения подробной информации о структуре каталога коллекции.

Установка более старой версии коллекции

Вы можете установить только одну версию коллекции одновременно. По умолчанию ansible-galaxy устанавливает последнюю доступную версию. Если вы хотите установить определённую версию, вы можете добавить идентификатор диапазона версий. Например, чтобы установить версию 1.0.0-beta.1 коллекции:

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

Вы можете указать несколько идентификаторов диапазонов, разделенных ,. Используйте одинарные кавычки, чтобы оболочка передала всю команду, включая >, !, и другие операторы, вместе. Например, чтобы установить последнюю версию, которая больше или равна 1.0.0 и меньше 2.0.0:

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

Ansible всегда установит последнюю версию, которая соответствует указанным вами идентификаторам диапазона. Вы можете использовать следующие идентификаторы диапазонов:

• *: Последняя версия. Это значение по умолчанию.
• !=: Не равна указанной версии.
• ==: Точно указанная версия.
• >=: Больше или равно указанной версии.
• >: Больше указанной версии.
• <=: Меньше или равно указанной версии.
• <: Меньше указанной версии.

Установка коллекции из репозитория Git

Вы можете установить коллекцию из репозитория Git, указав URI репозитория вместо имени коллекции или пути к файлу tar.gz. Коллекция должна содержать файл galaxy.yml, который будет использоваться для генерации данных артефакта коллекции из каталога. URI должен быть префиксным git+ (или git@ для использования приватного репозитория с SSH-аутентификацией) и необязательно поддерживает разделитель запятыми 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 git@github.com:organization/repo_name.git

# Install a collection from a local git repository
ansible-galaxy collection install git+file:///home/user/path/to/repo/.git

В файле requirements.yml вы также можете использовать ключи type и version в дополнение к использованию синтаксиса git+repo,version для имени коллекции.

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

Репозитории Git также могут использоваться для зависимостей коллекций. Это может быть полезно для локальной разработки и тестирования, но создаваемые/опубликованные артефакты должны зависеть только от других артефактов.

dependencies: {'git@github.com:organization/repo_name.git': 'devel'}

Основные места поиска репозиториев

По умолчанию в репозитории для коллекций ищутся два пути.

Первый — это файл galaxy.yml в корневом каталоге пути к репозиторию. Если файл galaxy.yml существует, он используется как метаданные коллекции, и коллекция будет установлена.

├── galaxy.yml
├── plugins/
│   ├── lookup/
│   ├── modules/
│   └── module_utils/
└─── README.md

Второй — файл galaxy.yml в каждом каталоге в пути к репозиторию (на один уровень глубже). В этом случае каждый каталог с файлом galaxy.yml устанавливается как коллекция.

directory/
├── docs/
├── galaxy.yml
├── plugins/
│   ├── inventory/
│   └── modules/
└── roles/

Указание места поиска коллекций

Если у вас другая структура репозитория или вы хотите установить только подмножество коллекций, вы можете добавить фрагмент в конец своего URI (перед необязательной разделитель запятых версией) для указания пути, который ansible-galaxy должен проверить на наличие файла(ов) galaxy.yml. Путь должен указывать на каталог с коллекцией или несколькими коллекциями (а не на путь к файлу galaxy.yml).

namespace/
└── name/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    │   ├── README.md
    │   └── modules/
    ├── README.md
    └── roles/

# Install all collections in a particular 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/name/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5

Установка нескольких коллекций с помощью файла требований

Вы также можете создать файл 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: 'version range identifiers (default: ``*``)'
  source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'

Поддерживаемые ключи для записей требований к коллекции — name, version, source, и type.

Ключ version может принимать тот же формат идентификаторов диапазона, что и описано выше. Если вы устанавливаете коллекцию из репозитория Git вместо готового артефакта коллекции, ключ version относится к git commit-ish.

Ключ type может быть установлен на galaxy, url, file, и git. Если type опущен, ключ name используется для неявного определения источника коллекции.

Роли также могут быть указаны и размещены под ключом roles. Значения следуют тому же формату, что и файл требований, используемый в более старых релизах Ansible.

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: 1.9.6

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 будет устанавливать только коллекции или роли соответственно.

Скачивание коллекции для автономного использования

Для скачивания архива коллекции из Galaxy для автономного использования:

1. Перейдите на страницу коллекции.
2. Нажмите на Скачать архив.

Возможно, также потребуется вручную скачать любые зависимые коллекции.

Настройка клиента ansible-galaxy

По умолчанию ansible-galaxy использует https://galaxy.ansible.com в качестве сервера Galaxy (как указано в файле ansible.cfg в разделе GALAXY_SERVER).

Вы можете использовать любой из нижеприведенных вариантов для настройки ansible-galaxy collection для использования других серверов (например, Red Hat Automation Hub или пользовательского сервера Galaxy):

• Установите список серверов в параметре конфигурации GALAXY_SERVER_LIST в файле конфигурации.
• Используйте аргумент командной строки --server для ограничения до одного сервера.

Чтобы настроить список серверов Galaxy в ansible.cfg,

1. Добавьте опцию server_list в раздел [galaxy] для одного или нескольких имён серверов.
2. Создайте новый раздел для каждого имени сервера.
3. Установите опцию url для каждого имени сервера.
4. Необязательно, установите токен API для каждого имени сервера. Подробности см. в разделе Токен API.

Для Automation Hub, дополнительно необходимо:

1. Установите параметр auth_url для каждого имени сервера.
2. Установите токен API для каждого имени сервера. Перейдите на https://cloud.redhat.com/ansible/automation-hub/token/ и нажмите Получить токен API из раскрывающегося списка версий, чтобы скопировать ваш токен API.

Следующий пример демонстрирует конфигурацию нескольких серверов:

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

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token

[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

Параметр GALAXY_SERVER_LIST представляет собой список идентификаторов серверов в порядке приоритета. При поиске коллекции процесс установки будет искать в указанном порядке, например, automation_hub сначала, затем my_org_hub, release_galaxy, и, наконец, test_galaxy, пока коллекция не будет найдена. Фактический экземпляр Galaxy затем определяется в разделе [galaxy_server.{{ id }}], где {{ id }} является идентификатором сервера, определённым в списке. Этот раздел может затем определить следующие ключи:

• url: URL экземпляра Galaxy для подключения. Требуется.
• token: Ключ токена API для аутентификации на экземпляре Galaxy. Взаимоисключающий с username.
• username: Имя пользователя для аутентификации по протоколу Basic на экземпляре Galaxy. Взаимоисключающий с token.
• password: Пароль для использования совместно с username для аутентификации по протоколу Basic.
• auth_url: URL сервера Keycloak 'token_endpoint', если используется аутентификация SSO (например, Automation Hub). Взаимоисключающий с username. Требует token.

Помимо определения этих параметров сервера в файле ansible.cfg, вы также можете определить их как переменные среды. Переменная среды имеет вид ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}, где {{ id }} — заглавная форма идентификатора сервера, а {{ key }} — ключ для определения. Например, я могу определить token для release_galaxy путём установки ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token.

Для операций, использующих только один сервер Galaxy (например, команды publish, info, или install), команда ansible-galaxy collection использует первый элемент в списке server_list, если не указан явный сервер с помощью аргумента --server.

Загрузка коллекций

Чтобы скачать коллекцию и её зависимости для автономной установки, выполните ansible-galaxy collection download. Это скачивает указанные коллекции и их зависимости в указанную папку и создаёт файл requirements.yml, который можно использовать для установки этих коллекций на хост без доступа к серверу Galaxy. Все коллекции по умолчанию загружаются в папку ./collections.

Как и команда install, коллекции берутся из конфигурированного конфигурационного файла сервера Galaxy. Даже если коллекция для скачивания была указана с помощью URL-адреса или пути к файлу tar, коллекция будет перескачиваться с сервера Galaxy, настроенного по умолчанию.

Коллекции можно указать как одну или несколько коллекций или с помощью файла requirements.yml так же, как ansible-galaxy collection install.

Чтобы скачать одну коллекцию и её зависимости:

ansible-galaxy collection download my_namespace.my_collection

Чтобы скачать одну коллекцию в определённой версии:

ansible-galaxy collection download my_namespace.my_collection:1.0.0

Чтобы скачать несколько коллекций, либо укажите несколько коллекций как аргументы командной строки, как показано выше, или используйте файл требований в формате, описанном в разделе Установка нескольких коллекций с помощью файла требований.

ansible-galaxy collection download -r requirements.yml

Все коллекции по умолчанию скачиваются в папку ./collections, но вы можете использовать -p или --download-path для указания другого пути:

ansible-galaxy collection download my_namespace.my_collection -p ~/offline-collections

После скачивания коллекций папка содержит указанные коллекции, их зависимости и файл requirements.yml . Вы можете использовать эту папку так же, как с ansible-galaxy collection install для установки коллекций на хост без доступа к серверу Galaxy или Automation Hub.

# This must be run from the folder that contains the offline collections and requirements.yml file downloaded
# by the internet-connected host
cd ~/offline-collections
ansible-galaxy collection install -r requirements.yml

Просмотр коллекций

Чтобы просмотреть установленные коллекции, выполните ansible-galaxy collection list. Это отобразит все установленные коллекции, найденные в настроенных путях поиска коллекций. Также будут отображены коллекции в разработке, содержащие файл galaxy.yml вместо MANIFEST.json. Также будет показан путь расположения коллекций и информация о версии. Если информация о версии недоступна, для номера версии отображается *.

# /home/astark/.ansible/collections/ansible_collections
Collection                 Version
-------------------------- -------
cisco.aci                  0.0.5
cisco.mso                  0.0.4
sandwiches.ham             *
splunk.es                  0.0.5

# /usr/share/ansible/collections/ansible_collections
Collection        Version
----------------- -------
fortinet.fortios  1.0.6
pureport.pureport 0.0.8
sensu.sensu_go    1.3.0

Выполните с аргументом -vvv для отображения более подробной информации.

Чтобы просмотреть определённую коллекцию, передайте валидное полное имя коллекции (FQCN) в команду ansible-galaxy collection list. Будут показаны все экземпляры этой коллекции.

> ansible-galaxy collection list fortinet.fortios

# /home/astark/.ansible/collections/ansible_collections
Collection       Version
---------------- -------
fortinet.fortios 1.0.1

# /usr/share/ansible/collections/ansible_collections
Collection       Version
---------------- -------
fortinet.fortios 1.0.6

Чтобы искать коллекции в других путях, используйте опцию -p . Укажите несколько путей поиска, разделив их : . Список путей, указанных в командной строке, будет добавлен в начало настроенных путей поиска коллекций.

> ansible-galaxy collection list -p '/opt/ansible/collections:/etc/ansible/collections'

# /opt/ansible/collections/ansible_collections
Collection      Version
--------------- -------
sandwiches.club 1.7.2

# /etc/ansible/collections/ansible_collections
Collection     Version
-------------- -------
sandwiches.pbj 1.2.0

# /home/astark/.ansible/collections/ansible_collections
Collection                 Version
-------------------------- -------
cisco.aci                  0.0.5
cisco.mso                  0.0.4
fortinet.fortios           1.0.1
sandwiches.ham             *
splunk.es                  0.0.5

# /usr/share/ansible/collections/ansible_collections
Collection        Version
----------------- -------
fortinet.fortios  1.0.6
pureport.pureport 0.0.8
sensu.sensu_go    1.3.0

Проверка коллекций

Проверка коллекций с помощью ansible-galaxy

После установки можно проверить, что содержимое установленной коллекции соответствует содержимому коллекции на сервере. Эта функция предполагает, что коллекция установлена в одном из настроенных путей коллекций и что коллекция существует на одном из настроенных серверов Galaxy.

ansible-galaxy collection verify my_namespace.my_collection

Выход команды ansible-galaxy collection verify будет пустым, если проверка успешна. Если коллекция была изменена, изменённые файлы будут перечислены под именем коллекции.

ansible-galaxy collection verify my_namespace.my_collection
Collection my_namespace.my_collection contains modified content in the following files:
my_namespace.my_collection
    plugins/inventory/my_inventory.py
    plugins/modules/my_module.py

Можно использовать флаг -vvv для отображения дополнительной информации, такой как версия и путь установленной коллекции, URL удалённой коллекции, используемой для проверки, и вывод успешной проверки.

ansible-galaxy collection verify my_namespace.my_collection -vvv
...
Verifying 'my_namespace.my_collection:1.0.0'.
Installed collection found at '/path/to/ansible_collections/my_namespace/my_collection/'
Remote collection found at 'https://galaxy.ansible.com/download/my_namespace-my_collection-1.0.0.tar.gz'
Successfully verified that checksums for 'my_namespace.my_collection:1.0.0' match the remote collection

Если у вас установлена предварительная версия или не последняя версия коллекции, необходимо указать конкретную версию для проверки. Если версия опущена, установленная коллекция проверяется на соответствие последней версии, доступной на сервере.

ansible-galaxy collection verify my_namespace.my_collection:1.0.0

Помимо формата namespace.collection_name:version, вы можете предоставить коллекции для проверки в файле requirements.yml. Зависимости, перечисленные в requirements.yml, не включаются в процесс проверки и должны проверяться отдельно.

ansible-galaxy collection verify -r requirements.yml

Проверка по файлам tar.gz не поддерживается. Если ваш файл requirements.yml содержит пути к файлам tar или URL-адреса для установки, вы можете использовать флаг --ignore-errors, чтобы убедиться, что все коллекции, использующие формат namespace.name в файле, обработаны.

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

После установки вы можете ссылаться на содержимое коллекции по её полному имени (FQCN):

- hosts: all
  tasks:
    - my_namespace.my_collection.mymodule:
        option1: value

Это работает для ролей или любого типа плагинов, распределённых в рамках коллекции:

- hosts: all
  tasks:
    - import_role:
        name: my_namespace.my_collection.role1

    - my_namespace.mycollection.mymodule:
        option1: value

    - debug:
        msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'

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

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

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

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

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

Использование collections в playbooks

В playbook вы можете контролировать коллекции, которые Ansible ищет для модулей и плагинов действий для выполнения. Однако любые роли, которые вы вызываете в своём playbook, определяют свой собственный порядок поиска коллекций; они не наследуют настройки вызывающего playbook. Это справедливо даже если роль не определяет собственного ключевого слова collections.

- hosts: all
  collections:
    - my_namespace.my_collection

  tasks:
    - import_role:
        name: role1

    - mymodule:
        option1: value

    - debug:
        msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'

Ключевое слово collections просто создаёт упорядоченный «путь поиска» для ссылок на плагины и роли без указания полного имени. Оно не устанавливает содержимое и не изменяет поведение Ansible относительно загрузки плагинов или ролей. Обратите внимание, что для плагинов, не являющихся действиями или модулями (например, для lookup, filters, tests), всё равно требуется FQCN.