Локальная установка

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

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

Здесь -p ./collections – путь к каталогу для установки коллекции.

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

ansible-galaxy collection install /path/to/collection -p ./collections

Здесь /path/to/collection – путь к каталогу, который содержит файлы разрабатываемой коллекции.

В результате выполнения команды Ansible соберет коллекцию на основе файлов MANIFEST.json или galaxy.yml.

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

ansible-galaxy collection install /path/to/directory -p ./collections

Здесь /path/to/directory – путь к каталогу, коллекции из которого необходимо установить.

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

По умолчанию утилита ansible-galaxy устанавливает последнюю доступную версию коллекции.

Чтобы установить определенную версию коллекции, укажите ее после названия коллекции с использованием идентификатора диапазона ==. Например, чтобы установить версию 1.0.1 коллекции my_namespace.my_collection, используйте следующую команду:

ansible-galaxy collection install my_namespace.my_collection:==1.0.1

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

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

Примечание

По умолчанию утилита ansible-galaxy игнорирует предварительные версии, например, бета-версии. Если необходимо установить такую версию, укажите ее с помощью идентификатора диапазона ==, например:

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

Доступные идентификаторы диапазона:

• * – самая последняя версия (по умолчанию);

• != – не равна указанной версии;

• == – равна указанной версии;

• >= – больше или равна указанной версии;

• > – больше указанной версии;

• <= – меньше или равна указанной версии;

• < – меньше указанной версии.

Установка с использованием файла requirements.yml

Файл requirements.yml позволяет устанавливать несколько коллекций.

Для каждой коллекции можно указать следующую информацию:

• name – название;

• version – версия (можно указать диапазон версий);

• source – URL источника, из которого будет загружена коллекция;

• type – тип источника:

  • dir – локальный каталог;

  • file – локальный файл в формате tar.gz;

  • galaxy – реестр коллекций;

  • git – репозиторий Git;

  • subdirs – подкаталог внутри каталога, указанного в поле source;

  • url – URL-адрес.

Например, для установки коллекции из репозитория Git, добавьте в requirements.yml следующие данные:

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

В файле requirements.yml можно указать роли, используя ключ roles, например:

roles:
  - name: geerlingguy.java
    version: "1.9.6"

collections:
  - name: geerlingguy.php_roles
    version: ">=0.9.3"
    source: https://galaxy.ansible.com

Чтобы установить роли и коллекции, указанные в файле requirements.yml, используйте следующую команду:

ansible-galaxy install -r requirements.yml

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

ansible-galaxy collection install -r requirements.yml

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

ansible-galaxy role install -r requirements.yml

Важно

Если в аргументах указан путь к целевому каталогу для установки, ansible-galaxy установит только роли и пропустит коллекции.

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

Установка коллекций из репозитория Git подходит для тестирования и работы с неофициальными версиями.

Чтобы установить коллекцию из репозитория Git с помощью командной строки, вместо названия коллекции используйте URI репозитория. Перед URI необходимо добавить префикс git+, если вы не используете SSH-аутентификацию. Вы можете указать ветку, коммит или тег с помощью синтаксиса, где нужное значение отделяется запятой от URI репозитория.

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

ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel

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

ansible-galaxy collection install git@github.com:organization/repo_name.git

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

ansible-galaxy collection install git+file:///home/user/path/to/repo_name.git

Важно

Встраивание учетных данных в URI небезопасно. Используйте надежные варианты аутентификации, чтобы ваши учетные данные не были раскрыты в журналах или где-либо еще.

При установке коллекции из репозитория Ansible использует метаданные коллекции, содержащиеся в файлах galaxy.yml или MANIFEST.json, чтобы корректно собрать коллекцию.

По умолчанию Ansible ищет файлы метаданных в двух местах репозитория:

• в корневом каталоге;

• в каждом каталоге на один уровень ниже от корня.

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

Пример структуры репозитория с одной коллекцией:

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

Если в одном или нескольких каталогах по пути к репозиторию (на один уровень ниже) существует файл galaxy.yml или MANIFEST.json, Ansible устанавливает каждый каталог с файлом метаданных как коллекцию.

Пример репозитория с двумя коллекциями:

├── collection1/
│   ├── docs/
│   ├── galaxy.yml
│   └── plugins/
│       ├── inventory/
│       └── modules/
└── collection2/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    |   ├── filter/
    |   └── modules/
    └── roles/

Если структура репозитория отличается, или вам нужна только определенная коллекция, можно указать путь к каталогу с метаданными через символ # в URI репозитория. Например, чтобы установить только collection2 из примера выше, используйте команду:

ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/collection2

Использование ключевого слова

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

Важно

Если в наборе сценариев используется как ключевое слово collections, так и одна или несколько ролей, то роли не используют коллекции, определенные в наборе сценариев. Это значит, что внутри роли нельзя ссылаться на коллекцию, заданную в наборе сценариев, и ее необходимо указывать явно. Это одна из причин, по которой рекомендуется всегда использовать FQCN.

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

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

Пример заполнения файла роли:

collections:
  - my_namespace.first_collection
  - my_namespace.second_collection
  - other_namespace.other_collection

Использование в наборах сценариев

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

Пример набора сценариев:

- 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 в список поиска. Если его не включить, по умолчанию доступно следующее содержимое:

• стандартные модули и расширения Ansible, доступные через ansible-base или ansible-core;

• поддержка старых путей расширений третьих сторон.

Примечание

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

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

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

• из командной строки:

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

• из другого набора сценариев:

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

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

• Глобальное выполнение на всех узлах. При необходимости можно ограничить выполнение с помощью аргумента --limit или пользовательского инвентаря:

  - hosts: all
  

• Ограничение на управляющий узел (localhost), используется для задач, которые выполняются на управляющем узле:

  - hosts: localhost
  

• Гибкое указание целевых узлов через переменную:

  - hosts: '{{ target | default("webservers") }}'
  

  Здесь target – переменная, которую можно задать через параметр -e 'target=host1,host2'. Если переменная не передана, используется группа узлов webservers из инвентаря.

Примечание

Список используемых источников

• Коллекции Ansible