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

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

Установка коллекций с помощью ansible-galaxy

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

Если вы используете другой сервер Galaxy, например Red Hat Automation Hub, см. раздел Настройка клиента ansible-galaxy.

Чтобы установить коллекцию, размещённую в 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-armored, отделённые от содержимого, чтобы проверить подлинность 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

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

По умолчанию проверка считается успешной, если коллекцию успешно проверила хотя бы одна подпись. Количество обязательных подписей можно настроить с помощью --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, содержащие отделённую подпись. Если указаны подписи, необходимо передать параметр CLI --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 устанавливают только коллекции и только роли соответственно.

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

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

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

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

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

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

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

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

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

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

Подробные сведения о структуре каталогов коллекций см. в разделе Структура коллекции.

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

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

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

  # directory containing a namespace, with collections as subdirectories
  - name: ./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 позволяет проверить коллекцию до создания tarball и её публикации. Пользователь может установить из репозитория Git коллекции или версии, которых ещё нет в Galaxy или Automation Hub. Эта возможность предназначена как простой способ для разработчиков контента, описанный выше; репозитории Git могут не поддерживать полный набор функций CLI 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-адрес «token_endpoint» сервера Keycloak для аутентификации 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.