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

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

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

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

См. Настройка клиента 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

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

Если коллекция была подписана сервером сервером распространения, сервер предоставит ASCII-зашифрованные отдельные подписи для проверки подлинности MANIFEST.json перед использованием его для проверки содержимого коллекции. Этот параметр недоступен на всех серверах распространения. См. Распространение коллекций для таблицы серверов, поддерживающих подпись коллекций.

Для использования проверки подписи для подписанных коллекций:

1. Настройка хранилища ключей GnuPG для ansible-galaxy, или укажите путь к хранилищу ключей с помощью параметра --keyring при установке подписанной коллекции.

2. Импортируйте открытый ключ с сервера распространения в это хранилище.

   gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx my-public-key.asc
   

3. Проверьте подпись при установке коллекции.

   ansible-galaxy collection install my_namespace.my_collection --keyring ~/.ansible/pubring.kbx
   

   Параметр --keyring не нужен, если вы настроили хранилище ключей GnuPG.

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

Вы также можете добавить подписи, помимо тех, которые предоставляет сервер распространения. Используйте параметр --signature для проверки MANIFEST.json коллекции с этими дополнительными подписями. Дополнительные подписи должны предоставляться как URI.

ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --keyring ~/.ansible/pubring.kbx

Проверка GnuPG происходит только для коллекций, установленных с сервера распространения. Подписи, предоставленные пользователем, не используются для проверки коллекций, установленных из репозиториев Git, каталогов исходных кодов или URL-адресов/путей к файлам tar.gz.

Вы также можете добавить дополнительные подписи в файл requirements.yml коллекции в поле signatures.

# requirements.yml
collections:
  - name: ns.coll
    version: 1.0.0
    signatures:
      - https://examplehost.com/detached_signature.asc
      - file:///path/to/local/detached_signature.asc

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

По умолчанию, проверка считается успешной, если минимум 1 подпись успешно проверит коллекцию. Количество необходимых подписей можно настроить с помощью --required-valid-signature-count или GALAXY_REQUIRED_VALID_SIGNATURE_COUNT. Все подписи можно потребовать, установив параметр в all. Для отказа от проверки подписи, если не найдено ни одной действительной подписи, добавьте значение +, например, +all или +1.

export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=2
ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --signature file:///path/to/local/detached_signature.asc

Некоторые ошибки GnuPG могут быть проигнорированы с помощью --ignore-signature-status-code или GALAXY_REQUIRED_VALID_SIGNATURE_COUNT. GALAXY_REQUIRED_VALID_SIGNATURE_COUNT должен быть списком, а --ignore-signature-status-code можно указывать несколько раз для игнорирования нескольких дополнительных кодов статуса ошибки.

В этом примере требуется, чтобы любые подписи, предоставленные сервером распространения, проверяли коллекцию, за исключением случаев, когда они терпят неудачу из-за NO_PUBKEY:

export ANSIBLE_GALAXY_GPG_KEYRING=~/.ansible/pubring.kbx
export ANSIBLE_GALAXY_REQUIRED_VALID_SIGNATURE_COUNT=all
ansible-galaxy collection install my_namespace.my_collection --ignore-signature-status-code NO_PUBKEY

Если проверка завершится неудачей в приведённом выше примере, будут отображаться только ошибки, отличные от NO_PUBKEY.

Если проверка не пройдена, коллекция не будет установлена. Проверку подписей GnuPG можно отключить с помощью --disable-gpg-verify или настроив GALAXY_DISABLE_GPG_VERIFY.

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

Можно установить только одну версию коллекции за раз. По умолчанию 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 всегда установит последнюю версию, удовлетворяющую указанным вами идентификаторам диапазона. Вы можете использовать следующие идентификаторы диапазона:

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

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

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

Вы можете указать следующие ключи для каждой записи коллекции:

• name
• version
• signatures
• source
• type

Ключ version использует тот же формат идентификатора диапазона, что и в документе Установка более старой версии коллекции.

Ключ signatures принимает список источников подписей, которые используются для дополнения тех, которые найдены на сервере Galaxy во время установки коллекции, и ansible-galaxy collection verify. Источники подписей должны быть URI, содержащими отделённую подпись. Опция командной строки --keyring должна быть предоставлена, если указаны подписи.

Подписи используются только для проверки коллекций на серверах Galaxy. Пользовательские подписи не используются для проверки коллекций, установленных из репозиториев Git, каталогов исходных файлов или URL-адресов/путей к файлам tar.gz.

collections:
  - name: namespace.name
    version: 1.0.0
    type: galaxy
    signatures:
      - https://examplehost.com/detached_signature.asc
      - file:///path/to/local/detached_signature.asc

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

При установке коллекции с помощью type: git, ключ version может ссылаться на ветку или на объект git commit-ish (коммит или тэг). Например:

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

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

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: "1.9.6" # note that ranges are not supported for roles


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

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

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

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

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

Установка коллекций рядом с плейбуками

Вы можете установить коллекции локально рядом с вашими плейбуками внутри вашего проекта вместо глобального расположения на вашей системе или на AWX.

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

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

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

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

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

Установка коллекции из исходных файлов

Ansible также может устанавливать из каталога исходных файлов несколькими способами:

collections:
  # directory containing the collection
  - source: ./my_namespace/my_collection/
    type: dir

  # directory containing a namespace, with collections as subdirectories
  - source: ./my_namespace/
    type: subdirs

Ansible также может установить коллекцию, собранную с помощью ansible-galaxy collection build или загруженную из Galaxy для автономного использования, указав выходной файл непосредственно:

collections:
  - name: /tmp/my_namespace-my_collection-1.0.0.tar.gz
    type: file

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

Вы можете установить коллекцию из Git-репозитория вместо Galaxy или Automation Hub. Как разработчик, установка из Git-репозитория позволяет вам просмотреть вашу коллекцию перед созданием архива tar и публикацией коллекции. Как пользователь, установка из Git-репозитория позволяет использовать коллекции или версии, которые ещё не находятся в Galaxy или Automation Hub. Эта функция предназначена в качестве минимального средства для разработчиков контента, как описано ранее, и Git-репозитории могут не поддерживать полный набор функций из командной строки ansible-galaxy. В сложных случаях более гибким вариантом может быть git clone репозиторий в правильную файловую структуру каталога установки коллекции.

Репозиторий должен содержать файл galaxy.yml или MANIFEST.json. Этот файл предоставляет метаданные, такие как номер версии и пространство имён коллекции.

# 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_name.git

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

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

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

namespace/
├── collectionA/
|   ├── docs/
|   ├── galaxy.yml
|   ├── plugins/
|   │   ├── README.md
|   │   └── modules/
|   ├── README.md
|   └── roles/
└── collectionB/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    │   ├── connection/
    │   └── modules/
    ├── README.md
    └── roles/

# Install all collections in the 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/collectionA/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5

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

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

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

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

Для настройки списка серверов Galaxy в ansible.cfg:

1. Добавьте параметр server_list в раздел [galaxy] для одного или нескольких имен серверов.
2. Создайте новый раздел для каждого имени сервера.
3. Установите параметр url для каждого имени сервера.
4. Необязательно, установите токен API для каждого имени сервера. Перейдите на https://galaxy.ansible.com/me/preferences и нажмите Показать ключ API.

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

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

[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_server.my_galaxy_ng]
url=http://my_galaxy_ng:8000/api/automation-hub/
auth_url=http://my_keycloak:8080/auth/realms/myco/protocol/openid-connect/token
client_id=galaxy-ng
token=my_keycloak_access_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-аутентификация (например, galaxyNG). Взаимоисключающий с username. Требует token.
• validate_certs: Требуется ли проверка сертификатов TLS для сервера Galaxy. По умолчанию значение True, если не указан параметр --ignore-certs или параметр GALAXY_IGNORE_CERTS не равен True.
• client_id: client_id токена Keycloak для использования в аутентификации. Требует auth_url и token. По умолчанию client_id - cloud-services для работы с Red Hat SSO.
• timeout: Максимальное время ожидания ответа от сервера Galaxy в секундах.

Помимо определения этих параметров сервера в файле 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.