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

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

• Установка коллекций
  • Установка коллекций с помощью ansible-galaxy
  • Установка более старой версии коллекции
  • Установка нескольких коллекций с помощью файла requirements
  • Настройка клиента ansible-galaxy
• Использование коллекций в плейбуке

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

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

Вы можете использовать команду ansible-galaxy collection install для установки коллекции на вашей системе.

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

ansible-galaxy collection install my_namespace.my_collection

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

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 коллекции:

ansible-galaxy collection install my_namespace.my_collection:1.0.0

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

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

• *: Любая версия, по умолчанию используется, если не указан диапазон.
• !=: Версия не равна указанной.
• ==: Версия должна быть указанной.
• >=: Версия больше или равна указанной.
• >: Версия больше указанной.
• <=: Версия меньше или равна указанной.
• <: Версия меньше указанной.

Установка нескольких коллекций с помощью файла 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)'

Ключ version может принимать тот же формат идентификатора диапазона, что и описано выше.

Роли также можно указать и поместить под ключ roles. Значения следуют тому же формату, что и файл requirements, используемый в более ранних версиях 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

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

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

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

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

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

Для 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: Ключ токена для аутентификации на сервере Galaxy, взаимно исключающий с username
• username: Имя пользователя для аутентификации по протоколу basic на сервере Galaxy, взаимно исключающий с token
• password: Пароль для аутентификации по протоколу basic
• auth_url: URL сервера Keycloak ‘token_endpoint’ при использовании SSO аутентификации (например, Automation Hub). Это взаимно исключающий с username. auth_url требует token.

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

Для операций, в которых используется только один сервер Galaxy, т.е. publish, info, login, используется первый элемент в server_list, если явно не был передан сервер в качестве аргумента командной строки.

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

После установки вы можете обратиться к содержимому коллекции по ее полному имени (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, добавленное в Ansible 2.8:

- 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 }}'

Это ключевое слово создаёт «путь поиска» для ссылок на плагины без пространства имён. Оно не импортирует роли или что-либо ещё. Обратите внимание, что для плагинов, не являющихся действиями или модулями, всё равно требуется FQCN.