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

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

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

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

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

  • Установка коллекций с помощью ansible-galaxy
  • Установка более старой версии коллекции
  • Установка коллекции из репозитория Git
  • Стандартные расположения поиска репозиториев
  • Указание расположения для поиска коллекций
  • Установка нескольких коллекций с помощью файла requirements
  • Загрузка коллекции для автономного использования
  • Настройка клиента 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

Для обновления коллекции до последней доступной версии с сервера 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

При использовании опции -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 или MANIFEST.json, который будет использован для генерации данных артефакта коллекции из директории. 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 или MANIFEST.json в корневом каталоге пути репозитория. Если файл существует, он используется как метаданные коллекции, и коллекция устанавливается.

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

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

directory/
├── docs/
├── MANIFEST.json
├── plugins/
│   ├── inventory/
│   └── modules/
└── roles/

Указание расположения для поиска коллекций

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

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

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

Загрузка сборки для автономного использования

Чтобы загрузить архив tarball сборки из Galaxy для автономного использования:

1. Перейдите на страницу сборки.
2. Нажмите на Загрузить архив tarball.

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

Настройка клиента 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 для каждого имени сервера. Перейдите по адресу https://galaxy.ansible.com/me/preferences и нажмите Показать ключ 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: Имя пользователя для базовой аутентификации в экземпляре Galaxy. Взаимоисключающий с token.
• password: Пароль для использования в сочетании с username, для базовой аутентификации.
• 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-адресом или путем к архиву tarball, сборка будет загружена повторно с настроенного сервера 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

Вы также можете загрузить каталог исходной сборки. Сборка строится с обязательным файлом galaxy.yml.

ansible-galaxy collection download /path/to/collection

ansible-galaxy collection download git+file:///path/to/collection/.git

Вы можете загрузить несколько исходных сборок из одного пространства имён, указав путь к пространству имён.

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

ansible-galaxy collection install /path/to/ns

Все сборки по умолчанию загружаются в папку ./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 для отображения более подробной информации.

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

> 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. Это верно даже если роль не определяет своего собственного ключевого слова my_namespace.my_collection.

- 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 при загрузке плагинов или ролей. Обратите внимание, что для плагинов, не являющихся действиями или модулями (например, lookups, filters, tests), всё ещё требуется FQCN.

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

Вы также можете распространять playbook в своей коллекции и вызывать их с помощью той же семантики, которую вы используете для плагинов:

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

Изнутри playbook:

- import_playbook: my_namespace.my_collection.playbookX

Несколько рекомендаций при создании таких playbooks: hosts: должны быть универсальными или, по крайней мере, иметь переменный ввод.

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

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

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

Это будет иметь неявную запись в ключевом слове collections: для my_namespace.my_collection так же, как и для ролей. .. см. также:

:ref:`developing_collections`
    Develop or modify a collection.
:ref:`collections_galaxy_meta`
     Understand the collections metadata structure.
`Mailing List <https://groups.google.com/group/ansible-devel>`_
     The development mailing list
`irc.freenode.net <http://irc.freenode.net>`_
     #ansible IRC chat channel