Обзор работы с программным интерфейсом

Обзор API, авторизация, структура путей, Swagger.

Платформа «Штурвал» предоставляет HTTP API (в спецификации OpenAPI 2.0 (Swagger)) Shturval Backend API с базовым путём /api/v1. Через API можно автоматизировать сценарии, которые в интерфейсе выполняются вручную: работа с кластерами, настройками платформы, мультитенантностью и т.д.

Раздел Описание
Авторизация и токен OAuth/OIDC, заголовок Authorization: Bearer, срок жизни токена
Структура API: пути и область cluster_id, разделы /clusters, /platform, /tenants, WebSocket
Swagger: справочник и сценарии Запуск документации из GUI, поиск endpoint’ов и требований к правам

Версия и справочник

  • В Swagger и в поставляемом файле swagger.json для текущей ветки backend указана версия API 2.14.0 (поле info.version в OpenAPI). Хост https://… задаётся вашим окружением; обращайтесь к URL установки платформы.
  • Детальное описание операций, моделей и кодов ответа — только в интерактивной спецификации (Swagger), а не на этой странице.

Обзор: доступ и разрешения

  • Во всех REST-вызовах, где требуется аутентификация, в заголовке передаётся Authorization: Bearer <token> (схема Bearer в securityDefinitions спецификации, ключ в заголовке Authorization).
  • Помимо валидного токена для операции с учётом контекста проверяются разрешения (permissions): в Swagger у методов с указанной политикой посмотрите требуемый идентификатор (например, platform.cluster.list, cluster.admin.edit, cluster.kubeconfig.get). Токен без нужного разрешения не позволит выполнить вызов — ожидайте ответы 401 / 403 в соответствии с правилами API.

Детали получения токена и пример curl — в разделе Авторизация и токен.

Совместимость и принципы работы

  • Платформа имеет в своей основе Kubernetes и расширяет набор операций «ванильного» Kubernetes API.
  • Принцип работы: backend обрабатывает запросы, при необходимости формирует и применяет изменения в кластерах в соответствии с ролями и разрешениями пользователя.
  • Протоколы: основные сценарии — HTTP/HTTPS (REST, schemes: http, https в спецификации). Для потоковых сценариев (например, логи пода) используются WebSocket-пути, см. Структура API.

Примеры REST-вызовов (кластеры)

Идентификатор кластера в путях API задаётся в формате namespace:clusterName. См. Структура API. Задайте переменные, получите токен по инструкции.

Метод Путь (относительно {backend}/api/v1) Описание
GET /clusters Список кластеров
GET /clusters/{cluster_id} Информация о кластере
GET /clusters/{cluster_id}/kubeconfig Временный kubeconfig по ID кластера

Ниже в примерах BACKENDPOINT — базовый URL API (см. Авторизация и токен). Подставьте реальные CLUSTER_ID и token.

Список кластеров

curl -k -s -L --request GET "$BACKENDPOINT/api/v1/clusters" \
  --header "Authorization: Bearer $token" | jq

Получение kubeconfig (для CLUSTER_ID используйте значение в формате namespace:clusterName):

export KUBECONFIG_PATH=/tmp/my-cluster.conf
export CLUSTER_ID="default:my-cluster"
curl -k -s "$BACKENDPOINT/api/v1/clusters/${CLUSTER_ID}/kubeconfig" \
  -H "Authorization: Bearer $token" \
  -H 'accept: application/json, text/plain, */*' > $KUBECONFIG_PATH

Создание кластеров, удаление и расширенные сценарии — в API для управления кластерами.

Получение токена

Пошаговая процедура (переменные, curl, срок токена) вынесена на страницу Авторизация и токен — для удобства копирования и сопровождения.

Swagger

Как открыть интерактивную спецификацию из GUI и как искать в ней endpoint’ы и требуемые разрешения — на странице Swagger: справочник и сценарии.

Дополнительная документация

← Графический интерфейс
Авторизация и токен →