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

При установке Datamart Platform Studio, по умолчанию происходит также установка и запуск системного экземпляра модуля Proxy API (настройка PROXY_API_STUDIO_ENABLE=true, в конфигурационном файле). Управление системным модулем происходит через настройки конфигурационного файла. При необходимости, в Datamart Platform Studio можно добавить дополнительные экземпляры модуля Proxy API, используя системный бандл модуля. Помимо этого, возможна конфигурация модулей Proxy API с отключением системного модуля (PROXY_API_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 в Datamart Platform Studio несколькими способами:

  • При конфигурации с включенным системным модулем, горизонтальное масштабирование модулей 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» рабочего пространства «Администрирование» и карточки услуги.

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

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

Раздел 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 аналогично меню «Управление» инсталляциями услуг. Для неустановленного на сервер компонента, доступны действия:

  • Установить

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

  • Удалить

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

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

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

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

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

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

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

Редактирование модуля Proxy API

Рисунок 9.5 Редактирование модуля Proxy API

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

9.3. Настройка правил ролевого доступа к эндпоинтам

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

В списке API интерфейсов услуги отображается пиктограмма с информацией о наличии ограничений для списка эндпоинтов каждого приложения (см. Рисунок 9.6), при нажатии на которую отображаются настройки доступа по ролям, указанные в бандле приложения. Дополнительная настройка ролей доступа к эндпоинтам выполняется в карточке инсталляции во вкладке «Правила API (Список правил ролевого доступа к API)».

Список доступных эндпоинтов с указанием ролей

Рисунок 9.6 Список доступных эндпоинтов с указанием ролей

Настройки ролей доступа к API по умолчанию могут быть указаны в бандле конкретного приложения:

Настройки доступа к эндпоинтам приложения

Рисунок 9.7 Настройки доступа к эндпоинтам приложения

, где:

  • deny - настройка общего доступа к Proxy API:

    • «none» - доступны все эндпоинты приложения, кроме указанных в списке endpoints;

    • «all» - недоступны все эндпоинты приложения, кроме указанных в списке endpoints;

  • endpoints - список эндпоинтов, доступных только пользователям с определенными ролями.

Изменить значение доступа по умолчанию можно в разделе «Правила API» выбрав действие «Настройка доступа» (см. Рисунок 9.8)

Настройка доступа по умолчанию к API компонента

Рисунок 9.8 Настройка доступа по умолчанию к API компонента

Примечание

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

Также в разделе «Правила API (Список правил ролевого доступа к API)» можно скорректировать роли доступа и добавить дополнительные эндпоинты и роли при необходимости:

Добавить роли доступа к эндпоинтам API компонента услуги

Рисунок 9.9 Добавить роли доступа к эндпоинтам API компонента услуги

9.3.1. Способы добавления правил для эндпоинтов компонента

Правила определяют доступ пользователям с определенной ролью к URL эндпоинтов, указанным в правиле. Правило задаётся строкой вида /users/*, где * — wildcard. Символ * может быть использован в конце или середине пути URL, используемого в правиле:

  • если символ * расположен в конце пути, доступ предоставляется ко всем методам, включающим указанный в правиле с любой дальнейшей вложенностью:

    • Например, правило /api/users/* предоставит доступ к URL /api/users/42/posts и /api/users/42/posts/5, но не позволит выполнить запрос api/users.

  • если символ * расположен в середине пути, он заменяет ровно один сегмент (одну часть между /):

    • Например, правило api/users/*/posts предоставит доступ к URL api/users/{id}/posts, но не позволит выполнить запрос api/users/{id}/posts/5.

  • если URL правила не содержит символ * , доступ предоставляется только к URL, указанному в правиле:

    • Например, правило api/users предоставит доступ только к URL api/users , но не позволит выполнить запрос api/users/42 или /api/users/42/posts/5.

Примечание

Правило /api/users/* не открывает доступ к /api/users (без дополнительной вложенности), только к /api/users/.... Чтобы открыть и сам /api/users, и вложенные — нужно два правила: /api/users и /api/users/*.

Примеры правил:

  • /api/*— доступ ко всему разделу /api и всем его подразделам;

  • /users/*/edit — доступ к редактированию любого пользователя по ID;

  • /dashboard — доступ только к конкретной странице, без вложенных.

9.4. Настройка таймаутов доступа к эндпоинтам

В .env файле Datamart Platform Studio указаны значения таймаутов доступа к API компонентов услуг через модуль Proxy API в параметрах:

# значения таймаутов в секундах:
 PROXY_API_CONNECT_TIMEOUT=10 - timeout соединения Angie с upstream (сек)
 PROXY_API_READ_TIMEOUT=10 - timeout чтения ответа upstream (сек)
 PROXY_API_SEND_TIMEOUT=10 - timeout отправки запроса upstream (сек)

При наличии выделенного модуля Proxy API для конкретной услуги, можно указать специфические таймауты для запросов:

Настройка таймаутов доступа к эндпоинтам Proxy API выделенного модуля Proxy API

Рисунок 9.10 Настройка таймаутов доступа к эндпоинтам Proxy API отдельной услуги

9.5. Логирование в модуле Proxy API

В .env файле переменных окружения модуля Proxy API можно указать формат логов, а также формат их вывода:

# формат логов модуля Proxy API:
PROXY_API_LOG_FORMAT=plaintext
# способ вывода логов модуля Proxy API:
PROXY_API_LOGS_OUTPUT=stdout

переменная окружения PROXY_API_LOG_FORMAT, может принимать значения:

  • plaintext (по умолчанию) – записи формируются в текстовом формате;

  • json – записи формируются в формате json

переменная окружения PROXY_API_LOGS_OUTPUT, может принимать значения:

  • stdout (по умолчанию);

  • file – файл log/proxy-api.log

9.6. События аудита модуля Proxy API

В процессе работы модуля Proxy API каждый экземпляр регистрирует следующие типы событий аудита:

  • выполнение успешного запроса пользователем (proxy_api_request)

  • выполнение неуспешного запроса пользователем (proxy_api_request_error)

Примечание

Формат событий соответствует формату событий Datamart Platform Studio (см. Раздел 8.4 События аудита).

Настройка отправки событий аудита конфигурируется параметрами:

# включение/выключение отправки событий аудита модуля Proxy API:
SEND_AUDIT_EVENTS=false
# тип регистрируемых событий:
AUDIT_SERVICE_LEVEL=ERROR
# адрес отправки событий аудита:
AUDIT_SERVICE_HOST=http://example.com/audit
# путь для загрузки метамодели:
AUDIT_SERVICE_METAMODEL_ENDPOINT=v2/metamodel
# Путь определения событий аудита:
AUDIT_SERVICE_EVENT_ENDPOINT=v2/event

переменная окружения SEND_AUDIT_EVENTS, может принимать значения:

  • false (по умолчанию) – отправка событий аудита отключена;

  • true – отправка событий аудита включена

переменная окружения AUDIT_SERVICE_LEVEL, может принимать значения:

  • ERROR (по умолчанию) - регистрация только событий о запросах, завершившихся ошибкой ;

  • ALL – регистрация событий как об успешных, так и неуспешных запросах.

Для выполнения отправки событий аудита по mTLS модуль Proxy API будет учитывать наличие сертификата по пути volumes/audit/mtls.pem и при его наличии отправка событий аудита будет осуществляться по mTLS с использованием данного сертификата (Раздел 8.4.2 Настройка сбора и отправки событий аудита).

9.7. Метрики модуля Proxy API

Метрики модуля Proxy API можно получить с использованием эндпоинта GET /metrics в формате Prometheus.

Список метрик модуля Proxy API:

  • proxy_api_request_total - число выполняемых запросов в секунду;

  • proxy_api_request_time_seconds_sum - время выполнения запроса;

  • proxy_api_request_err_total - количество ошибок в единицу времени.

9.8. Конфигурационные параметры модуля 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_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 — все события

AUDIT_SERVICE_HOST

//example.com/audit

Хост для отправки событий аудита

AUDIT_SERVICE_EVENT_ENDPOINT

v2/event

Путь определения событий аудита

AUDIT_SERVICE_METAMODEL_ENDPOINT

v2/metamodel

Путь для загрузки метамодели

AUDIT_SERVICE_OPEN_TIMEOUT_SECONDS

2

Время ожидания установления соединения с аудит-сервисом

AUDIT_SERVICE_READ_TIMEOUT_SECONDS

5

Время ожидания отправки запроса

9.9. Типичные ответы и диагностика модуля 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