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

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

Работа с контентом Private Automation Hub через API необходима для автоматизации типовых операций без обращения к графической консоли – просмотра, загрузки и выгрузки коллекций Ansible, а также управления образами среды исполнения. Примеры используют утилиты curl и jq.

Предварительные требования#

Для выполнения примеров необходимы следующие привилегии и роли (см. справочник ролей и привилегий):

  • загрузка коллекции – привилегия galaxy.upload_to_namespace в целевом пространстве имен, которая входит в роли galaxy.collection_namespace_owner и galaxy.collection_publisher;

  • создание пространства имен, если оно еще не существует, – привилегия galaxy.add_namespace, которая входит, например, в роль galaxy.collection_publisher;

  • согласование версий коллекций – роль galaxy.collection_curator.

Для работы с примерами выполните следующие действия:

  1. Чтобы улучшить формат вывода JSON, установите утилиту jq:

    sudo apt install jq

  2. Получите токен доступа к API Private Automation Hub. Токен можно создать в графической консоли (см. описание окна подключения к Private Automation Hub) или запросом к точке доступа /api/galaxy/v3/auth/token/ с базовой аутентификацией:

    curl -k -X POST -u '<username>:<password>' \
   https://<address>/api/galaxy/v3/auth/token/ | jq .

    Здесь:

    • <username> и <password> – учетные данные пользователя платформы;

    • <address> – FQDN или IP-адрес шлюза платформы.

    Ожидаемый результат:

    {
  "token": "f2c4a1446b2dec1a1272b016********"
}

    Примечание

    Аргумент -k отключает проверку сертификата TLS и допустим только при использовании самозаверенных сертификатов в демонстрационных и тестовых средах.

Полученный токен не имеет срока действия; при повторном запросе выдается новый токен, а прежний отзывается. Во всех последующих примерах токен передается в заголовке Authorization со схемой token:

Authorization: token <token>

Просмотр коллекций#

Список версий коллекций во всех репозиториях возвращает точка доступа поиска:

curl -k -H 'Authorization: token <token>' \
   'https://<address>/api/galaxy/v3/plugin/ansible/search/collection-versions/?limit=2' | jq .

Сокращенный пример ответа:

{
  "meta": {
    "count": 1259
  },
  "data": [
    {
      "repository": {
        "name": "aa-certified"
      },
      "collection_version": {
        "namespace": "astra",
        "name": "ald_pro",
        "version": "1.0.0"
      }
    }
  ]
}

Для уточнения поиска добавьте параметры запроса, например:

  • namespace – пространство имен;

  • name – название коллекции;

  • repository_name – название репозитория, например published или aa-certified;

  • keywords – поиск по ключевым словам.

Подробные сведения о конкретной версии коллекции возвращает точка доступа вида /api/galaxy/v3/plugin/ansible/content/<repository>/collections/index/<namespace>/<collection>/versions/<version>/:

curl -k -H 'Authorization: token <token>' \
   https://<address>/api/galaxy/v3/plugin/ansible/content/aa-certified/collections/index/astra/ald_pro/versions/1.0.2/ | jq .

Здесь:

  • <repository> – название репозитория (в примере – aa-certified);

  • <namespace> – пространство имен (в примере – astra);

  • <collection> – название коллекции (в примере – ald_pro);

  • <version> – версия коллекции (в примере – 1.0.2).

Сокращенный пример ответа:

{
  "version": "1.0.2",
  "namespace": "astra",
  "name": "ald_pro",
  "download_url": "https://<address>/api/galaxy/v3/plugin/ansible/content/aa-certified/collections/artifacts/astra-ald_pro-1.0.2.tar.gz",
  "artifact": {
    "filename": "astra-ald_pro-1.0.2.tar.gz",
    "sha256": "dea0faa921a2e050...",
    "size": 37569
  }
}

Значения полей download_url и artifact.sha256 используются при выгрузке коллекции.

Загрузка коллекции#

Для загрузки версии коллекции в Private Automation Hub выполните следующие действия:

  1. Убедитесь, что архив коллекции содержит файл meta/runtime.yml с параметром requires_ansible, например:

    requires_ansible: ">=2.15.0"

    Если файл отсутствует, импорт завершится ошибкой 'requires_ansible' in meta/runtime.yml is mandatory, but no meta/runtime.yml found.

  2. Убедитесь, что в Private Automation Hub существует пространство имен, совпадающее с пространством имен коллекции. При необходимости создайте его:

    curl -k -X POST \
   -H 'Authorization: token <token>' \
   -H 'Content-Type: application/json' \
   -d '{"name": "<namespace>", "groups": []}' \
   https://<address>/api/galaxy/v3/namespaces/ | jq .

  3. Загрузите архив коллекции:

    curl -k -X POST \
   -H 'Authorization: token <token>' \
   -F 'file=@<namespace>-<collection>-<version>.tar.gz' \
   https://<address>/api/galaxy/v3/artifacts/collections/ | jq .

    Ожидаемый результат:

    {
  "task": "/api/galaxy/content/staging/v3/plugin/ansible/imports/collections/019f6f58-64c2-7e89-9cc7-58a757bd8c8a/"
}

  4. Проверьте состояние импорта по значению поля task из предыдущего ответа:

    curl -k -H 'Authorization: token <token>' \
   https://<address><task> | jq '.state'

    Здесь <task> – значение поля task.

    Ожидаемый результат: "completed". Пока импорт выполняется, запрос возвращает "waiting" или "running", поэтому повторите его через несколько секунд. Если состояние – "failed", причина указана в поле error.description ответа.

  5. Если версия загружена в репозиторий с конвейером задач Промежуточный (Staging), выполните согласование. Согласуйте версию в графической консоли (см. инструкцию по согласованию) или запросом к API:

    curl -k -X POST \
   -H 'Authorization: token <token>' \
   https://<address>/api/galaxy/v3/collections/<namespace>/<collection>/versions/<version>/move/<source_repo>/<dest_repo>/ | jq .

    Здесь:

    • <source_repo> – репозиторий-источник (например, staging);

    • <dest_repo> – репозиторий-назначение (например, published).

    Если версия загружена в репозиторий с конвейером Пусто (None), согласование не требуется – коллекция доступна пользователям сразу.

  6. Убедитесь, что версия коллекции доступна в целевом репозитории:

    curl -k -H 'Authorization: token <token>' \
   'https://<address>/api/galaxy/v3/plugin/ansible/search/collection-versions/?namespace=<namespace>&repository_name=<dest_repo>' | jq .

Примечание

Загрузку коллекции также можно выполнить командой ansible-galaxy collection publish или через графическую консоль – см. описание размещения коллекций.

Выгрузка коллекции#

Для выгрузки версии коллекции из Private Automation Hub выполните следующие действия:

  1. Получите URL артефакта из сведений о версии коллекции:

    curl -k -H 'Authorization: token <token>' \
   https://<address>/api/galaxy/v3/plugin/ansible/content/<repository>/collections/index/<namespace>/<collection>/versions/<version>/ | jq -r '.download_url'

  2. Выгрузите артефакт по полученному URL:

    curl -k -L -H 'Authorization: token <token>' \
   -o <namespace>-<collection>-<version>.tar.gz \
   '<download_url>'

    Здесь <download_url> – URL, полученный на предыдущем шаге.

    Важно

    Точка доступа отвечает перенаправлением, поэтому аргумент -L обязателен: без него будет создан пустой файл.

  3. Проверьте целостность полученного артефакта, сравнив его контрольную сумму со значением поля artifact.sha256 из сведений о версии:

    sha256sum <namespace>-<collection>-<version>.tar.gz

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

Список репозиториев образов возвращает следующая точка доступа:

curl -k -H 'Authorization: token <token>' \
   'https://<address>/api/galaxy/v3/plugin/execution-environments/repositories/?limit=3' | jq .

Сокращенный пример ответа:

{
  "meta": {
    "count": 9
  },
  "data": [
    {
      "name": "aa-2.0/aa-minimal-ee",
      "pulp": {
        "repository": {
          "pulp_type": "container.container"
        }
      }
    }
  ]
}

Загрузка и выгрузка образов#

Реестр образов Private Automation Hub реализует Docker Registry HTTP API V2 и доступен через шлюз платформы: точка доступа реестра – https://<address>/v2/, токен для работы с реестром выдает точка доступа https://<address>/token/ по базовой аутентификации.

Процедура загрузки образов описана в соответствующей инструкции. Для выгрузки образа используйте команду podman pull (см. описание).