9. Конфигурирование модулей Proxy API

При установке Datamart Platform Studio, по умолчанию происходит также установка и запуск системного экземпляра модуля Proxy API (настройка PROXYAPI_STUDIO_ENABLE=true, в конфигурационном файле). Управление системным модулем происходит через настройки конфигурационного файла.При необходимости, в Datamart Platform Studio можно добаавить дополнительные экземпляры модуля Proxy API, используя системный бандл модуля. Помимо этого, возможна конфигурация модулей Proxy API с отключением системного модуля (PROXYAPI_STUDIO_ENABLE=false), в этом случае системный модуль, после перезапуска Datamart Platform Studio с указанной настройкой, будет выключен. В данной конфигурации возможно развертывание отдельных модулей Proxy API для каждой из услуг Datamart Platform Studio.

Примечание

Системный модуль Proxy API всегда сконфигурирован для работы со всеми услугами, входящими в экземпляр Datamart Platform Studio и не может быть сконфигурирован под конкретную услугу.

Примечание

Сервисы proxy_api и proxy_api_angie собраны в compose-профиль studio-proxy-api. Этот профиль (и сами сервисы) запускается только при PROXY_API_STUDIO_ENABLE=true. При любом другом значении профиль отключён и модуль Proxy API не поднимается. Дефолт в env_datamart.example/env_gostech.example — true. Отдельно запустить контур Proxy API можно из корня репозитория:

В интерфейсе Datamart Platform Studio реализована возможность горизонтального масштабирования числа модулей Proxy API из системного бандла как на уровне Datamart Platform Studio, так и на уровне услуг студии. Предлагается конфигурировать работу proxy api несколькими способовами:

• При конфигурации с включенным системным модулем, горизонтальное масштабирование модулей Proxy API осуществляется также на уровне Datamart Platform Studio;

• При конфигурации с выключенным системным модулем, горизонтальное масштабирование модулей Proxy API осуществляется на уровне услуг студии.

Примечание

При любой конфигурации ограничений на количество выделенных модулей нет.

9.1. Описание модуля

Proxy API позволяет клиентам обращаться к API приложений через единый внешний вход, не открывая прямой доступ к внутренним адресам инсталляций и кластеров.

Сервис:

• принимает HTTP/gRPC-запросы через отдельный Angie-прокси;

• проверяет Bearer JWT через Keycloak/IAM;

• находит пользователя, роли, организации, целевой ресурс и интерфейс в данных Studio;

• проверяет правила доступа к HTTP endpoint-ам;

• при успехе сообщает Angie upstream-адрес целевого API; Angie проксирует запрос и возвращает клиенту ответ upstream-сервиса;

• пишет application logs и, если включено, отправляет события во внешний Audit-сервис.

Proxy API выступает как слой авторизации и маршрутизации: он читает конфигурацию из Studio через read-only подключение к базе и не изменяет данные платформы.

Модуль Proxy API состоит из следующих компонентов:

Публичным входом для клиентов является proxy_api_angie.

9.1.1. Публичные методы модуля Proxy API

Модуль Proxy API предоставляет следующие публичные методы:

Таблица 9.1 Публичные методы Proxy API

Endpoint	Description
GET /liveness	Метод проверки состояния модуля. Сервис успешно отвечает на метод /liveness, если он запущен
GET /readiness	Метод проверки состояния модуля. Сервис успешно отвечает на метод /readiness, если модуль обладает необходимыми метаданными для выполнения запросов пользователей
GET /metrics	Метод, возвращающий информацию о Prometheus-метриках модуля
GET /v1/proxy_api/info	Метод, возвращающий информацию о модуле с информацией об идентификаторе модуля, связанной услуги и версии и сборке Datamart Platform Studio, связанной с модулем

9.2. Управление модулями Proxy API в интерфейса Datamart Platform Studio

Управление дополнительными модулями Proxy API осуществляется из раздела «Модули ProxyAPI» рабочего пространства «Администрирование» и в одноименном разделе любой из Услуг.

Управление выделенным модулем осуществляется в таблице по кнопке «Управление». Набор действий в меню «Управление» зависит от статуса модуля и аналогичен меню «Управление» инсталляциями Услуг.

9.2.1. Настройка системного модуля Proxy API

Настройка системного модуля осуществляется в .env файле (см. разделы: Раздел 10.3 Настройка параметров в файле конфигурации) в разделе «Настройки модуля proxy api». По умолчанию модуль устанавливается на тот же сервер что и Datamart Platform Studio и включается после установки. Для применения измененных настроек системного модуля необходимо внести изменения в конфигурационный файл Datamart Platform Studio и перезапустить ее.

9.2.2. Настройка дополнительных модулей Proxy API

Настройка выделенных proxy API осуществляется из раздела «ProxyAPI» рабочего пространства «Администрирование» и карточки услуги.

Рисунок 9.1 Раздел ProxyAPI в рабочем пространстве Администрирование

Рисунок 9.2 Раздел ProxyAPI в карточке услуги

Для добавления модуля в разделе «ProxyAPI» необходимо выбрать действие «Добавить модуль». Модальное окно добавления содержит следующие поля:

• Версия компонента

• Сервер

• Услуга

• Наименование

Рисунок 9.3 Добавление модуля Proxy API

Поле «Версия компонента» всегда заполнено совместимой с текущей версией Datamart Platform Studio версией модуля. При выборе сервера доступен множественный выбор для установки сразу нескольких модулей Proxy API на разные сервера. При выборе услуги из выпадающего списка можно выбрать услугу или значение «Все услуги». При выборе значения «Все услуги» модуль Proxy API будет сконфигурирован для работы со всеми услугами Datamart Platform Studio. При выборе конкретной услуги, модуль Proxy API будет взаимодействовать только с указанной услугой, при попытке выполнить запрос к любой другой услуге Datamart Platform Studio с использованием этого экземпляра модуля, он вернет ошибку.

При добавлении модуля из карточки услуги поле «Услуга» будет предзаполнено соответствующей услугой. То есть добавить выделенный модуль можно только для услуги.

Рисунок 9.4 Добавление модуля из карточки услуги

Меню «Управление» модулем Proxy API аналогично меню «Управление» инсталляциями услуг. Для неустановленного на сервер компонента, доступны действия:

• Установить

• Редактировать

• Удалить

Для установленного на сервер компонента, доступны действия:

• Переустановить

• Деинсталлировать

• Показать изменения

• Действия (список доступных модулю плейбуков)

• Обновить приложение

• Редактировать

Рисунок 9.5 Управление модуля

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

9.3. Конфигурационные параметры модуля Proxy API

Базовые переменные описаны в .env.example и подключаются через docker-compose.datamart.yaml.

Таблица 9.2 Переменные Proxy API

Наименование	Значение по умолчанию	Описание
PROXY_API_PORT	9292	Внутренний порт Ruby-приложения
PROXY_API_HTTP_PROXY_PORT	9293	Внешний HTTP-порт Angie
STUDIO_GRPC_PROXY_PORT_MIN	30000	Начало диапазона gRPC-портов
STUDIO_GRPC_PROXY_PORT_MAX	30099	Конец диапазона gRPC-портов
PROXY_API_MAX_THREADS	5	Число Puma threads
PROXY_API_WEB_CONCURRENCY	0	Число Puma workers; 0 означает один процесс
PROXY_API_DB_POOL_SIZE	5	Размер пула подключений к PostgreSQL
PROXY_API_DB_POOL_TIMEOUT	1	Ожидание свободного подключения в секундах
PROXY_API_DB_USER	proxy_api_readonly	Read-only пользователь PostgreSQL для Proxy API
PROXY_API_DB_PASS		Пароль read-only пользователя
DB_HOST, DB_PORT, DB_NAME		Параметры подключения к базе Studio
PROXY_API_LOG_FORMAT	plaintext	Формат логов: plaintext или json
PROXY_API_LOGS_OUTPUT	file	Цель вывода логов: stdout или file (файл log/proxy-api.log); некорректное значение переходит в file
PROXY_API_DATA_DIR	data	Директория файлового кэша метаданных
PROXY_API_METADATA_TOKEN		Общий секрет для X-API-Key на metadata endpoints; если не задан, сервис стартует, но /v1/proxy_api/metadata/refresh всегда возвращает 401
PROXY_API_SERVICE_ID		ID услуги (datamart); если задано, запросы к БД ограничиваются datamarts.id = <значение>. Пусто — фильтр отключён
PROXY_API_SERVICE_MNEMONIC		Мнемоника datamart; сохранена как настройка, в фильтрации запросов к БД не участвует
PROXY_API_ID	Proxy_API_DatamartStudio	Идентификатор модуля: поле id в GET /v1/proxy_api/info, moduleId в каждой строке лога и имя модуля в audit-событиях
DTMS_VERSION		Версия сборки Studio; возвращается в GET /v1/proxy_api/info как version
DTMS_VERSION_COMMIT		SHA коммита сборки Studio; возвращается как commit; при отсутствии читается файл .commit_sha
PROXY_API_SESSION_TTL_SECONDS	300	TTL кэша сессий Keycloak, секунд; повторные запросы с тем же токеном не обращаются к userinfo в течение этого времени
PROXY_API_METADATA_INTERVAL_SECONDS	300	Интервал фоновой синхронизации кэша из БД, секунд; 0 — отключает синхронизацию
PROXY_API_REFRESH_THROTTLE_SECONDS	1	Минимальный интервал между refresh’ами кэша по запросу Studio, секунд; 0 — отключает throttle
PROXY_API_CONNECT_TIMEOUT	10	Timeout соединения Angie с upstream в секундах
PROXY_API_READ_TIMEOUT	10	Timeout чтения ответа upstream в секундах
PROXY_API_SEND_TIMEOUT	10	Timeout отправки запроса upstream в секундах
SEND_AUDIT_EVENTS	false	Включает отправку audit-событий
AUDIT_SERVICE_LEVEL	ERROR	ERROR — только ошибки, ALL — все события

9.4. Типичные ответы и диагностика модуля Proxy API

Таблица 9.3 Ошибки и причины в Proxy API при выполнении REST запросов

Код ошибки	Возможная причина	Что проверить
401 Unauthorized + missing_api_key + invalid_api_key	запрос на /v1/proxy_api/metadata/refresh без X-API-Key или с неверным ключом	заголовок X-API-Key, общее значение PROXY_API_METADATA_TOKEN на Proxy API и Studio
401 Unauthorized	нет токена, токен не читается, Keycloak userinfo отклонил токен	Authorization: Bearer …, issuer, срок действия токена, доступность Keycloak
403 Forbidden + policy_denied	HTTP endpoint запрещен правилами	роль proxy_api, endpoint-роли, proxy_api_permissions на ресурсе
403 Forbidden + organization_access_denied	пользователь не состоит в организации ресурса	организации пользователя и ресурса
403 Forbidden + auth_service_access_denied	auth service токена не разрешен для datamart	настройки auth services в Studio
403 Forbidden + target_not_found	ресурс или интерфейс не найден	X-Id, X-Object-Type, active/api-флаги интерфейса
403 Forbidden + installation_name_mismatch	только HTTP v1: имя инсталляции в URL не совпало с записью в БД	URL v1 или имя инсталляции
403 Forbidden + grpc_interface_not_found	gRPC-порт не привязан к активному интерфейсу	proxy_api_port, диапазон портов, состояние интерфейса
502 Bad Gateway	upstream недоступен или вернул ошибку	host/port целевого интерфейса, сеть, состояние приложения
504 Gateway Timeout	upstream не ответил вовремя	PROXY_API_*_TIMEOUT, скорость целевого API
/readiness = 503	нет подключения к БД и нет загруженного кэша	переменные БД, read-only роль, доступность PostgreSQL

Для gRPC Angie преобразует результаты авторизации в gRPC-статусы:

Таблица 9.4 Ошибки в Proxy API для gRPC запросов

Код ошибки	gRPC статус	Сообщение
401	16	Unauthenticated
403	5	Not found
5xx	13	Internal error