Утилита ansible-galaxy#

Описание#

ansible-galaxy - утилита, предназначенная для выполнения различных операций, связанных с ролями, сбором данных и коллекциями Ansible Core.

Синтаксис утилиты:

ansible-galaxy <options> <type action> ...

Где:

<options> - опции;
<type action> - тип ресурса и соответствующее действие.

Настройка утилиты производится с помощью конфигурационного файла /etc/ansible/ansible.cfg, используемого при наличии, и файла конфигурации пользователя ~/.ansible.cfg, переопределяющего конфигурацию по умолчанию, если она присутствует, описанных в разделе «Конфигурационные файлы ansible.cfg».

Опции#

Опции утилиты представлены в таблице ниже.

Опции `ansible-galaxy`#
Опция	Описание
`--version`	Показать номер версии утилиты, расположение конфигурационного файла, путь поиска модулей, расположение модуля, расположение исполняемого файла и выйти
`-h`, `--help`	Показать справочное сообщение и выйти
`-v`, `--verbose`	Заставить Ansible Core выводить больше отладочных сообщений; увеличение количества `-v` увеличивает уровень подробности, встроенные плагины в настоящее время оценивают до `-vvvvvv`; разумный уровень для начала `-vvv`, отладка подключения может потребовать `-vvvv`; этот аргумент может быть указан несколько раз

Типы ресурсов и действия#

В зависимости от типа ресурса, с которым необходимо работать, для утилиты могут быть заданы различные действия. Задаваемые типы ресурсов:

role - роли;
collection - коллекции.

Примечание

В командах, передаваемых утилите, указанные типы ресурсов всегда должны сочетаться с соответствующими действиями, таким как delete/install/init и проч. Команда с указанием только role/collection не будет выполнена.

Действия для типа ресурсов role#

Действие role init#

Создает скелет роли или коллекции, соответствующий формату метаданных Galaxy. Требуется имя роли или коллекции. Имя коллекции должно быть в формате <namespace>.<collection>.

Опции действия представлены в таблице ниже.

Опции `role init`#
Опция	Описание
`--init-path <init_path>`	Указать путь, по которому будет создан скелет роли; по умолчанию используется текущий рабочий каталог
`--offline`	Не запрашивать API Galaxy при создании ролей
`--role-skeleton <role_skeleton>`	Указать путь к скелету роли, на основе которого должна быть создана новая роль
`--timeout <timeout>`	Установить время ожидания для операций с сервером Galaxy; по умолчанию 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`--type <role_type>`	Инициализировать с использованием альтернативного типа роли; допустимые типы: `container`, `apb` и `network`
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификатов
`-e`, `--extra-vars`	Установить дополнительные переменные в формате «ключ=значение» или YAML/JSON, если имя файла начинается с `@`; этот аргумент может быть указан несколько раз
`-f`, `--force`	Принудительно перезаписать существующую роль или коллекцию
`-s <api_server>`, `--server <api_server>`	Указать URL сервера API Galaxy

Действие role remove#

Удаляет список ролей, переданных в качестве аргументов из локальной системы.

Опции действия представлены в таблице ниже.

Опции `role remove`#
Опция	Описание
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-p`, `--roles-path`	Указать путь к каталогу, содержащему пользовательские роли; по умолчанию используется первый доступный для записи каталог, настроенный с помощью `DEFAULT_ROLES_PATH: {{ ANSIBLE_HOME ~ "/roles:/usr/share/ansible/roles:/etc/ansible/roles" }}`; этот аргумент можно указать несколько раз
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role delete#

Удаляет роли из Ansible Galaxy.

Опции `role delete`#
Опция	Описание
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role list#

Выводит список установленных коллекций или ролей.

Опции `role list`#
Опция	Описание
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-p`, `--roles-path <path>`	Указать путь к каталогу, содержащему пользовательские роли. По умолчанию это первый доступный для записи путь, настроенный через `DEFAULT_ROLES_PATH: {{ ANSIBLE_HOME ~ "/roles:/usr/share/ansible/roles:/etc/ansible/roles" }}`. Этот аргумент может быть указан несколько раз
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role search#

Выполняет поиск ролей на сервере Ansible Galaxy.

Опции `role search`#
Опция	Описание
`--author <author>`	Указать имя пользователя GitHub
`--galaxy-tags <galaxy_tags>`	Указать список тегов Galaxy для фильтрации
`--platforms <platforms>`	Указать список операционных систем для фильтрации
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role import#

Используется для импорта роли в Ansible Galaxy.

Опции `role import`#
Опция	Описание
`--branch <reference>`	Указать имя ветки для импорта. По умолчанию используется ветка «по умолчанию» репозитория (обычно `master`)
`--no-wait`	Не ждать результатов импорта
`--role-name <role_name>`	Указать имя роли, если оно отличается от имени репозитория
`--status`	Проверить статус последнего запроса на импорт для указанного `github_user`/`github_repo`
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role setup#

Настраивает интеграцию с Github или Travis для ролей Ansible Galaxy.

Опции `role setup`#
Опция	Описание
`--list`	Перечислить все пользовательские интеграции
`--remove <remove_id>`	Удалить интеграцию, соответствующую указанному значению ID. Используйте `--list`, чтобы увидеть значения ID
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-p`, `--roles-path <path>`	Указать путь к каталогу, содержащему пользовательские роли. По умолчанию это первый доступный для записи путь, настроенный через `DEFAULT_ROLES_PATH: {{ ANSIBLE_HOME ~ "/roles:/usr/share/ansible/roles:/etc/ansible/roles" }}`. Этот аргумент может быть указан несколько раз
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role info#

Выводит подробную информацию об установленной роли, а также информацию, доступную из API Galaxy.

Опции `role info`#
Опция	Описание
`--offline`	Не запрашивать Galaxy API при создании ролей
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-p`, `--roles-path <path>`	Указать путь к каталогу, содержащему пользовательские роли. По умолчанию это первый доступный для записи путь, настроенный через `DEFAULT_ROLES_PATH: {{ ANSIBLE_HOME ~ "/roles:/usr/share/ansible/roles:/etc/ansible/roles" }}`. Этот аргумент может быть указан несколько раз
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие role install#

Устанавливает одну или несколько ролей. Можно указать список ролей или использовать опции, указанные ниже (они являются взаимоисключающими). Если передается список, это может быть имя (которое будет загружено через Galaxy API и Github), или локальный архивный файл tar.

Опции `role install`#
Опция	Описание
`--force-with-deps`	Принудительно перезаписать существующую роль и ее зависимости
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-f`, `--force`	Принудительно перезаписать существующую роль или коллекцию
`-g`, `--keep-scm-meta`	Использовать `tar` вместо опции `scm archive` при упаковке роли
`-i`, `--ignore-errors`	Игнорировать ошибки и продолжать со следующей указанной ролью
`-n`, `--no-deps`	Не загружать роли, указанные как зависимости
`-p`, `--roles-path <path>`	Указать путь к каталогу, содержащему пользовательские роли. По умолчанию это первый доступный для записи путь, настроенный через `DEFAULT_ROLES_PATH: {{ ANSIBLE_HOME ~ "/roles:/usr/share/ansible/roles:/etc/ansible/roles" }}`. Этот аргумент может быть указан несколько раз
`-r <requirements>`, `--role-file <requirements>`	Указать файл, содержащий список ролей для установки
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действия для типа ресурсов collection#

Действие collection download#

Загружает коллекции и их зависимости в виде архивного файла для установки офлайн.

Опции `collection download`#
Опция	Описание
`--clear-response-cache`	Очистить существующий кеш ответов сервера
`--no-cache`	Не использовать кеш ответов сервера
`--pre`	Включить предварительные (pre-release) версии. Предварительные версии семантического версионирования игнорируются по умолчанию
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-n`, `--no-deps`	Не загружать коллекции, указанные как зависимости
`-p <download_path>`, `--download-path <download_path>`	Указать каталог для загрузки коллекций
`-r <requirements>`, `--requirements-file <requirements>`	Указать файл, содержащий список коллекций для загрузки
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие collection init#

Опции `collection init`#
Опция	Описание
`--collection-skeleton <collection_skeleton>`	Указать путь к скелету коллекции, на основе которого должна быть создана новая коллекция
`--init-path <init_path>`	Указать путь, в котором будет создан скелет коллекции. По умолчанию используется текущий рабочий каталог
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-e`, `--extra-vars <vars>`	Установить дополнительные переменные в формате «ключ=значение» или YAML/JSON; если файл, то добавить `@` перед именем файла. Этот аргумент может быть указан несколько раз
`-f`, `--force`	Принудительно перезаписать существующую роль или коллекцию
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие collection build#

Создает артефакт (архив .tar.gz) коллекции Ansible Galaxy, который можно сохранить в центральном репозитории, таком как Ansible Galaxy. По умолчанию выполняет сборку из текущего рабочего каталога. При необходимости можно указать путь input к коллекции (где находится файл galaxy.yml).

Опции `collection build`#
Опция	Описание
`--output-path <output_path>`	Указать путь, в который будет собрана коллекция. По умолчанию используется текущий рабочий каталог
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-f`, `--force`	Принудительно перезаписать существующую роль или коллекцию
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие collection publish#

Публикует коллекцию в Ansible Galaxy. Для публикации требуется указать путь к архиву коллекции.

Опции `collection publish`#
Опция	Описание
`--import-timeout <import_timeout>`	Установить время ожидания завершения процесса импорта коллекции
`--no-wait`	Не ждать результатов валидации импорта
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие collection install#

Устанавливает одну или несколько коллекций. Можно указать список коллекций или использовать опции, указанные ниже (они являются взаимоисключающими). Если передается список, это может быть имя (которое будет загружено через Galaxy API и Github), или локальный архивный файл tar.

Опции `collection install`#
Опция	Описание
`--clear-response-cache`	Очистить существующий кеш ответов сервера
`--disable-gpg-verify`	Отключить проверку подписи GPG при установке коллекций с сервера Galaxy
`--force-with-deps`	Принудительно перезаписать существующую коллекцию и ее зависимости
`--ignore-signature-status-code`	Игнорировать код статуса подписи. Этот аргумент может быть указан несколько раз
`--ignore-signature-status-codes`	Указать список кодов статуса, которые следует игнорировать при проверке подписи (например, `NO_PUBKEY FAILURE`). Указываются после позиционных аргументов или используется `–` для разделения. Этот аргумент может быть указан несколько раз
`--keyring <keyring>`	Указать хранилище ключей, используемое при проверке подписи
`--no-cache`	Не использовать кеш ответов сервера
`--offline`	Установить артефакты коллекции (`tarballs`) без обращения к дистрибутивным серверам. Не применяется к коллекциям в удаленных Git-репозиториях или URL-адресам удаленных `tarballs`
`--pre`	Включить предварительные (pre-release) версии. Предварительные версии семантического версионирования игнорируются по умолчанию
`--required-valid-signature-count <required_valid_signature_count>`	Указать количество подписей, которые должны успешно пройти проверку для коллекции. Это должно быть положительное целое число или `-1`, чтобы обозначить, что все подписи должны быть использованы для проверки коллекции. Добавьте `+` перед значением, чтобы действие завершалось с ошибкой, если не найдены действительные подписи для коллекции (например, `+all`)
`--signature`	Указать дополнительный источник подписи для проверки подлинности `MANIFEST.json` перед установкой коллекции с сервера Galaxy. Используется вместе с позиционным именем коллекции (является взаимоисключающим с `–requirements-file`). Этот аргумент может быть указан несколько раз
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-U`, `--upgrade`	Обновить установленные артефакты коллекции. Также обновит зависимости, если не указано `–no-deps`
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-f`, `--force`	Принудительно перезаписать существующую роль или коллекцию
`-i`, `--ignore-errors`	Игнорировать ошибки при установке и продолжать со следующей указанной коллекцией. Не будет игнорировать ошибки конфликта зависимостей
`-n`, `--no-deps`	Не загружать коллекции, указанные как зависимости
`-p <collections_path>`, `--collections-path <collections_path>`	Указать путь к каталогу, содержащему пользовательские коллекции
`-r <requirements>`, `--requirements-file <requirements>`	Указать файл, содержащий список коллекций для установки
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие collection list#

Выводит список установленных коллекций или ролей.

Опции `collection list`#
Опция	Описание
`--format <output_format>`	Указать формат для отображения списка коллекций
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-p <collections_path>`, `--collections-path <collections_path>`	Указать один или несколько каталогов для поиска коллекций дополнительно к значению по умолчанию `COLLECTIONS_PATHS`. Разделяйте несколько путей символом `:`. Этот аргумент может быть указан несколько раз
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Действие collection verify#

Сравнивает контрольные суммы коллекций, найденных на сервере, с установленной копией. Не проверяет зависимости.

Опции `collection verify`#
Опция	Описание
`--ignore-signature-status-code`	Игнорировать код статуса подписи. Этот аргумент может быть указан несколько раз
`--ignore-signature-status-codes`	Указать список кодов статуса, которые следует игнорировать при проверке подписи (например, `NO_PUBKEY FAILURE`). Указываются после позиционных аргументов или используется `–` для разделения. Этот аргумент может быть указан несколько раз
`--keyring <keyring>`	Указать хранилище ключей, используемое при проверке подписи
`--offline`	Проверить целостность коллекции локально без обращения к серверу для получения канонического хеша манифеста
`--required-valid-signature-count <required_valid_signature_count>`	Указать количество подписей, которые должны успешно пройти проверку для коллекции. Это должно быть положительное целое число или `all`, чтобы обозначить, что все подписи должны быть использованы для проверки коллекции. Добавьте `+` перед значением, чтобы действие завершалось с ошибкой, если не найдены действительные подписи для коллекции (например, `+all`)
`--signature`	Указать дополнительный источник подписи для проверки подлинности `MANIFEST.json` перед использованием его для проверки остального содержимого коллекции с сервера Galaxy. Используется вместе с позиционным именем коллекции (является взаимоисключающим с `–requirements-file`). Этот аргумент может быть указан несколько раз
`--timeout <timeout>`	Установить время ожидания операций на сервере Galaxy; по умолчанию составляет 60 секунд
`--token <api_key>`, `--api-key <api_key>`	Указать ключ API Ansible Galaxy
`-c`, `--ignore-certs`	Игнорировать ошибки проверки SSL-сертификата
`-i`, `--ignore-errors`	Игнорировать ошибки при проверке и продолжать со следующей указанной коллекцией
`-p <collections_path>`, `--collections-path <collections_path>`	Указать один или несколько каталогов для поиска коллекций дополнительно к значению по умолчанию `COLLECTIONS_PATHS`. Разделяйте несколько путей символом `:`. Этот аргумент может быть указан несколько раз
`-r <requirements>`, `--requirements-file <requirements>`	Указать файл, содержащий список коллекций для проверки
`-s <api_server>`, `--server <api_server>`	Указать URL-адрес сервера Galaxy API

Переменные окружения#

Переменная окружения, влияющая на работу утилиты - ANSIBLE_CONFIG - переопределить конфигурационный файл по умолчанию.

Другие варианты доступны в качестве параметров ansible.cfg (подробнее - в разделе «Конфигурационные файлы ansible.cfg»).

Примеры использования#

Установите коллекцию mynamespace.mycollection из Ansible Galaxy:
```
ansible-galaxy collection install mynamespace.mycollection
```
Установите список коллекций, содержащийся в файле requirements.yml:
```
ansible-galaxy collection install -r requirements.yml
```
Выведите список установленных коллекций:
```
ansible-galaxy collection list
```

Установите роль example.role:

ansible-galaxy role install example.role

Выведите список установленных ролей:
```
ansible-galaxy role list
```

Дополнительная информация#

Дополнительную информацию можно получить, выполнив команду:

ansible-galaxy --help