Admin API и управление

OSA Proxy предоставляет выделенный административный интерфейс (Admin API) для решения задач эксплуатации: просмотра интерактивной документации Swagger UI, оперативной очистки кэша проверок, мониторинга состояния реплик и централизованного управления конфигурацией.

По умолчанию Admin API отключен и работает на отдельном сетевом адресе (по умолчанию 127.0.0.1:8081). Это позволяет изолировать административные функции от пользовательского трафика загрузки пакетов.

Включение Admin API

Для включения Admin API задайте секцию admin в osa-proxy.yml:

admin:
  enabled: true
  address: 127.0.0.1:8081
  write-timeout: 2m
  token-hash: "<sha256-хэш-токена>"

Настройка токена администратора

Все административные методы /api/v1/... защищены Bearer-токеном. В конфигурации хранится только SHA-256 хэш токена в нижнем регистре, а сам секретный токен передается клиентом в заголовке запроса.

Чтобы сгенерировать хэш для выбранного секрета (например, my-admin-secret-token):

echo -n "my-admin-secret-token" | sha256sum

Полученную строку укажите в admin.token-hash. Чтобы передать её через переменную окружения OSA_PROXY_ADMIN_TOKEN_HASH, добавьте ссылку на неё в YAML:

admin:
  token-hash: ${OSA_PROXY_ADMIN_TOKEN_HASH:}

Безопасность listener'а

Admin API использует обычный HTTP. В production-окружении не публикуйте порт 8081 наружу напрямую. Используйте внутреннюю сеть, NetworkPolicy в Kubernetes или терминируйте TLS на доверенном reverse proxy с ограничением доступа по IP.

Swagger UI и спецификация OpenAPI

При включенном admin.enabled: true на адресе административного сервера доступны:

GET /swagger/ — веб-интерфейс Swagger UI для интерактивного тестирования запросов. В интерфейсе можно нажать кнопку Authorize и ввести ваш Bearer-токен;
GET /openapi.json — полная спецификация OpenAPI 3 в формате JSON;
GET /healthz — проверка работоспособности административного сервера.

Эти три endpoint не требуют авторизации для базового просмотра, но вызовы методов API внутри Swagger UI требуют ввода Bearer-токена.

Очистка кэша вердиктов

Если для пакета изменился статус в CodeScoring или требуется принудительно повторить проверку, записи можно удалить из Redis-кэша без перезапуска сервиса.

Для вызова этих методов передайте токен в заголовке Authorization: Bearer <токен>:

Удаление конкретных PURL

Метод DELETE /api/v1/cache/purls удаляет вердикты для перечисленных Package URL (PURL):

curl -X DELETE http://127.0.0.1:8081/api/v1/cache/purls \
  -H "Authorization: Bearer my-admin-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "purls": [
      "pkg:npm/lodash@4.17.21",
      "pkg:pypi/requests@2.31.0"
    ]
  }'

Пример успешного ответа:

{
  "deleted": 2
}

Удаление по типу пакета и имени

Метод DELETE /api/v1/cache/packages/{packageType} позволяет удалить все записи кэша для экосистемы или конкретной библиотеки:

curl -X DELETE "http://127.0.0.1:8081/api/v1/cache/packages/npm?packageName=lodash" \
  -H "Authorization: Bearer my-admin-secret-token"

Дополнительно поддерживается фильтрация по параметрам repositoryName и repositoryManagerUrl для точечной очистки в контексте Artifactory или Nexus (должны передаваться оба параметра одновременно).

Мониторинг состояния и маршрутов

Admin API позволяет проверить текущий статус реплик и список активных репозиториев:

Статус сервиса

Запрос GET /api/v1/status возвращает состояние хранилища конфигураций, активность реплик и номер текущей ревизии:

curl -s http://127.0.0.1:8081/api/v1/status \
  -H "Authorization: Bearer my-admin-secret-token"

Список активных репозиториев

Запрос GET /api/v1/runtime/repositories возвращает полный список маршрутов, которые обслуживает данный инстанс OSA Proxy (включая статические из YAML и динамические, найденные через Artifactory или Nexus discovery).

Поддерживаются параметры фильтрации:

source — фильтр по источнику (yaml, managed, artifactory, nexus);
package_type — тип пакета (например, npm, maven, pypi, docker);
state — статус маршрута (desired, active, observed, skipped, unsupported, conflicting, failed, stale, inactive);
text — поиск по подстроке в имени репозитория или upstream URL.

curl -s "http://127.0.0.1:8081/api/v1/runtime/repositories?package_type=npm&state=active" \
  -H "Authorization: Bearer my-admin-secret-token"

Централизованное хранилище конфигурации (Configuration Store)

По умолчанию OSA Proxy читает настройки из файла osa-proxy.yml на диске. При необходимости изменять параметры репозиториев, webhooks и поведение CodeScoring «на лету» без перезапуска подов можно включить централизованное хранилище в Redis.

Настройка Configuration Store

configuration-store:
  enabled: true
  backend: redis
  deployment-identity: "production-cluster"
  replica-identity: "osa-proxy-1"
  accept-unsafe-durability: false
  poll-interval: 30s
  operation-timeout: 5s
  history-limit: 20
  redis:
    address: redis:6379
    password: ${CONFIGURATION_STORE_REDIS_PASSWORD:}
    db: 1

Если блок redis внутри configuration-store не задан, сервис переиспользует подключение из секции cache.redis. При необходимости можно задать только redis-db: 1 для использования отдельной базы в том же инстансе Redis.

replica-identity идентифицирует heartbeat и lease-записи. Если параметр не задан, OSA Proxy использует hostname, а при его недоступности — сгенерированный process identity. Helm chart передаёт имя pod через OSA_PROXY_REPLICA_IDENTITY.

Требования к надежности Redis (

accept-unsafe-durability) OSA Proxy при запуске проверяет, что Redis настроен для персистентного хранения без потери данных: директива maxmemory-policy должна иметь значение noeviction, а также включено сохранение на диск (appendonly yes или RDB snapshots через save). Если Redis не удовлетворяет этим требованиям, сервис завершится с ошибкой надежности. Чтобы разрешить запуск с ненадежной конфигурацией Redis (например, в тестовых окружениях), укажите accept-unsafe-durability: true.

При первом запуске с пустым хранилищем OSA Proxy автоматически импортирует начальные параметры из локального osa-proxy.yml и создаёт ревизию 1. После этого хранилище становится приоритетным источником конфигурации.

Чтение и изменение настроек через API

GET /api/v1/configuration — получение полного снимка текущей целевой конфигурации (в формате JSON) со сводным заголовком ETag (формат "revision-<N>:sha256:...");
/api/v1/configuration/repositories/{package_type} — репозитории выбранного типа пакета (npm, maven, ivy, nuget, pypi, composer, ruby, cocoapods, swift, conan, go, hex, r, debian, alpine, rpm, docker);
/api/v1/configuration/codescoring — параметры интеграции с CodeScoring (режим работы, блокировка, сообщения);
/api/v1/configuration/layouts — шаблоны путей для репозиториев;
/api/v1/configuration/discovery/artifactory и /discovery/nexus — настройки автоматического обнаружения репозиториев;
/api/v1/configuration/webhooks — подписки на события webhooks (подробнее см. в Настройка webhooks).

Защита от конфликтов через ETag

Все операции изменения конфигурации используют заголовок If-Match. Это исключает ситуацию, когда два администратора случайно перезаписывают изменения друг друга:

Выполните GET-запрос нужной секции и сохраните заголовок ETag из ответа:
```
curl -i http://127.0.0.1:8081/api/v1/configuration/codescoring \
  -H "Authorization: Bearer my-admin-secret-token"
```

Отправьте PUT-запрос с обновленным телом, передав точное значение ETag в заголовке If-Match:

curl -X PUT http://127.0.0.1:8081/api/v1/configuration/codescoring \
  -H "Authorization: Bearer my-admin-secret-token" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "section-codescoring-1:sha256:abc..."' \
  -d '{
    "enable_status_line": true,
    "work_mode": "strict_wait",
    "osa_proxy_url": "https://osa-proxy.example.com",
    "block_on_codescoring_errors": true,
    "stage": "proxy",
    "block_status_code": 403,
    "block_message": "Component blocked by policy",
    "append_block_url_to_message": true
  }'

Если за время между запросами конфигурация была изменена кем-то другим, сервер вернет статус 409 Conflict. В этом случае повторите чтение, проверьте изменения и отправьте запрос заново.

История изменений и откат

Каждое изменение создаёт новую ревизию. Вы можете просмотреть историю ревизий и при необходимости мгновенно откатить настройки:

GET /api/v1/configuration/revisions — список сохраненных ревизий;
GET /api/v1/configuration/revisions/{revision} — просмотр отдельной сохраненной ревизии;
POST /api/v1/configuration/revisions/{revision}/rollback — откат к указанной ревизии. Запрос требует передачи заголовка If-Match с текущим сводным ETag всей конфигурации (из GET /api/v1/configuration):
```
curl -X POST http://127.0.0.1:8081/api/v1/configuration/revisions/2/rollback \
  -H "Authorization: Bearer my-admin-secret-token" \
  -H 'If-Match: "revision-3:sha256:..."'
```
GET /api/v1/configuration/export — экспорт всей текущей конфигурации в формате YAML (секреты автоматически заменяются на переменные окружения). Выгруженный файл можно использовать как основу для osa-proxy.yml.

Страница была полезна?

#Admin API и управление

#Включение Admin API

#Настройка токена администратора

#Swagger UI и спецификация OpenAPI

#Очистка кэша вердиктов

#Удаление конкретных PURL

#Удаление по типу пакета и имени

#Мониторинг состояния и маршрутов

#Статус сервиса

#Список активных репозиториев

#Централизованное хранилище конфигурации (Configuration Store)

#Настройка Configuration Store

#Чтение и изменение настроек через API

#Защита от конфликтов через ETag

#История изменений и откат