Развёртывание в Kubernetes

Платформа поставляется четырьмя Helm-чартами. Внешних зависимостей у чартов нет: PostgreSQL, Redis и ClickHouse разворачиваются внутри чарта starguard-base как StatefulSet на официальных образах либо подключаются как внешние экземпляры.

Чарт Состав Публикация

Чарт	Состав	Публикация
`starguard-base`	Core, User State, Frontend, Analytics, Meta Saver (Vector), PostgreSQL, Redis, ClickHouse	Ingress или Gateway API HTTPRoute
`starguard-gate`	vLLM, Gate (reverse), File Recognizer, User Portal (backend и frontend), Redis	Ingress или Gateway API HTTPRoute
`starguard-gate-forward`	Gate (forward)	Service типа NodePort
`starguard-scanner`	Scanner	не публикуется (открытого порта нет)

starguard-base

Core, User State, Frontend, Analytics, Meta Saver (Vector), PostgreSQL, Redis, ClickHouse

Ingress или Gateway API HTTPRoute

starguard-gate

vLLM, Gate (reverse), File Recognizer, User Portal (backend и frontend), Redis

Ingress или Gateway API HTTPRoute

starguard-gate-forward

Gate (forward)

Service типа NodePort

starguard-scanner

Scanner

не публикуется (открытого порта нет)

Каждый компонент включается и выключается независимо параметром <компонент>.enabled.

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

Kubernetes 1.26+ и настроенный доступ к кластеру (kubectl).
Helm 3.10+ — поддержка OCI-реестров обязательна.
Учётные данные для реестра docker.starguard-ai.ru (выдаются поставщиком).
Установленный в кластере NVIDIA gpu-operator — для чарта starguard-gate.
Ingress-контроллер или реализация Gateway API — для публикации Base и Gate.

2. Получение чартов

Чарты публикуются в OCI-реестр docker.starguard-ai.ru/starguard — отдельный репозиторий Helm подключать не нужно. Полные ссылки на чарты приведены ниже.

Чарт Ссылка

Чарт	Ссылка
`starguard-base`	`oci://docker.starguard-ai.ru/starguard/starguard-base`
`starguard-gate`	`oci://docker.starguard-ai.ru/starguard/starguard-gate`
`starguard-gate-forward`	`oci://docker.starguard-ai.ru/starguard/starguard-gate-forward`
`starguard-scanner`	`oci://docker.starguard-ai.ru/starguard/starguard-scanner`

starguard-base

oci://docker.starguard-ai.ru/starguard/starguard-base

starguard-gate

oci://docker.starguard-ai.ru/starguard/starguard-gate

starguard-gate-forward

oci://docker.starguard-ai.ru/starguard/starguard-gate-forward

starguard-scanner

oci://docker.starguard-ai.ru/starguard/starguard-scanner

Версия чарта указывается ключом --version и должна соответствовать версии поставляемого релиза платформы. В примерах ниже используется версия 1.2.0:

oci://docker.starguard-ai.ru/starguard/starguard-gate:1.2.0

Реестр закрытый, поэтому перед установкой необходимо выполнить вход:

helm registry login docker.starguard-ai.ru -u <пользователь>

Состав и параметры чарта можно посмотреть, не устанавливая его:

helm show values oci://docker.starguard-ai.ru/starguard/starguard-gate --version 1.2.0

3. Доступ к образам контейнеров: imagePullSecret

Образы контейнеров хранятся в том же закрытом реестре, поэтому в каждом namespace, куда устанавливается чарт, нужно заранее создать Secret с учётными данными реестра и передать его чарту. Без этого поды остаются в состоянии ImagePullBackOff.

Создайте namespace и Secret — по одному Secret’у на каждый используемый namespace:

kubectl create namespace starguard
kubectl create namespace starguard-gate

for NS in starguard starguard-gate; do
  kubectl -n $NS create secret docker-registry starguard-registry \
    --docker-server=docker.starguard-ai.ru \
    --docker-username=<пользователь> \
    --docker-password=<пароль> \
    --docker-email=<email>
done

Передайте его чарту параметром global.imagePullSecrets — списком объектов с полем name:
```
--set global.imagePullSecrets[0].name=starguard-registry
```
либо в файле значений:
```
global:
  imagePullSecrets:
    - name: starguard-registry
```

Параметр global.imagePullSecrets поддерживают все четыре чарта и применяют ко всем своим подам. Учётные данные реестра образов и учётные данные для helm registry login — как правило, одни и те же.

Namespace’ы разные — Secret’ов тоже несколько. В типовой установке Base и Scanner живут в namespace starguard, а Gate — в starguard-gate; Secret нужно создать в каждом из них. Namespace создаётся до Secret’а, поэтому ключ --create-namespace в примерах установки ниже фактически ничего не делает — он оставлен на случай установки в ещё не созданный namespace.

Зеркалирование реестра. Если образы перекладываются во внутренний реестр организации, укажите его в global.imageRegistry — значение подставляется перед image.repository. В этом случае image.repository должен быть задан без имени хоста (например, starguard/gate, а не полным адресом).

4. Чарт starguard-base

Пример установки:

helm install starguard oci://docker.starguard-ai.ru/starguard/starguard-base \
  --version 1.2.0 \
  --namespace starguard --create-namespace \
  --set global.imagePullSecrets[0].name=starguard-registry \
  --set domain=starguard.example.com \
  --set userState.host=ustate.starguard.example.com \
  --set vector.host=meta.starguard.example.com \
  --set auth.secretKey=$(openssl rand -hex 32) \
  --set auth.initAdminPassword=$(openssl rand -base64 24) \
  --set postgresql.auth.password=$(openssl rand -base64 24) \
  --set redis.auth.password=$(openssl rand -base64 24) \
  --set clickhouse.auth.password=$(openssl rand -base64 24)

Ключевые параметры приведены ниже.

Параметр Описание

Параметр	Описание
`domain`	Внешнее имя интерфейса администратора и Core API (`/api`)
`userState.host`	Внешнее имя сервиса User State
`vector.host`	Внешнее имя приёмника событий Meta Saver
`auth.secretKey`	Секретный ключ платформы (аналог `SECRET_KEY`)
`auth.initAdminPassword`	Пароль учётной записи `admin` при первом запуске
`auth.existingSecret`	Имя заранее созданного Secret вместо создаваемого чартом
`core.env.SCANNER_SERVICE_TOKEN`	Общий секрет с сервисом Scanner
`core.oidc.*`	Параметры входа администраторов через корпоративный OIDC (`enabled`, `issuer`, `clientId`, `clientSecret`, `wellKnownUrl`, `redirectUri`)
`analytics.enabled`, `analytics.clickhouseAnalyticsDatabase`	Включение сервиса аналитики и имя его базы в ClickHouse
`postgresql.enabled` / `externalPostgresql.*`	Встроенный PostgreSQL либо подключение к внешнему экземпляру
`redis.enabled` / `externalRedis.*`	Встроенный Redis либо внешний экземпляр
`clickhouse.enabled` / `externalClickhouse.*`	Встроенный ClickHouse либо внешний экземпляр
`global.storageClass`, `<компонент>.persistence.storageClass`	StorageClass для всех PVC и его переопределение по компонентам
`ingress.enabled` / `httpRoute.enabled`	Способ публикации. Включать нужно ровно один

domain

Внешнее имя интерфейса администратора и Core API (/api)

userState.host

Внешнее имя сервиса User State

vector.host

Внешнее имя приёмника событий Meta Saver

auth.secretKey

Секретный ключ платформы (аналог SECRET_KEY)

auth.initAdminPassword

Пароль учётной записи admin при первом запуске

auth.existingSecret

Имя заранее созданного Secret вместо создаваемого чартом

core.env.SCANNER_SERVICE_TOKEN

Общий секрет с сервисом Scanner

core.oidc.*

Параметры входа администраторов через корпоративный OIDC (enabled, issuer, clientId, clientSecret, wellKnownUrl, redirectUri)

analytics.enabled, analytics.clickhouseAnalyticsDatabase

Включение сервиса аналитики и имя его базы в ClickHouse

postgresql.enabled / externalPostgresql.*

Встроенный PostgreSQL либо подключение к внешнему экземпляру

redis.enabled / externalRedis.*

Встроенный Redis либо внешний экземпляр

clickhouse.enabled / externalClickhouse.*

Встроенный ClickHouse либо внешний экземпляр

global.storageClass, <компонент>.persistence.storageClass

StorageClass для всех PVC и его переопределение по компонентам

ingress.enabled / httpRoute.enabled

Способ публикации. Включать нужно ровно один

Маршрутизация внешних имён приведена ниже.

Имя и путь Целевой сервис

Имя и путь	Целевой сервис
`<domain>/`	Frontend
`<domain>/api`	Core
`<domain>/api/v1/analytics`	Analytics
`<vector.host>/`	Meta Saver (Vector)
`<userState.host>/`	User State

<domain>/

Frontend

<domain>/api

Core

<domain>/api/v1/analytics

Analytics

<vector.host>/

Meta Saver (Vector)

<userState.host>/

User State

При подключении внешних СУБД учётные данные можно передать заранее созданным Secret’ом (externalPostgresql.existingSecret и аналогичные). Ожидаемые ключи: POSTGRES_USER/POSTGRES_PASSWORD, REDIS_PASSWORD, CLICKHOUSE_USER/CLICKHOUSE_PASSWORD.

Инициализация схемы ClickHouse выполняется отдельным Job’ом после установки и обновления чарта.

5. Чарт starguard-gate

Пример установки:

helm install starguard-gate oci://docker.starguard-ai.ru/starguard/starguard-gate \
  --version 1.2.0 \
  --namespace starguard-gate --create-namespace \
  --set global.imagePullSecrets[0].name=starguard-registry \
  --set domain=gate.starguard.example.com \
  --set auth.coreUrl=https://starguard.example.com \
  --set auth.userStateUrl=https://ustate.starguard.example.com \
  --set auth.coreToken=$GATE_UUID \
  --set auth.coreApiKey=$CORE_API_KEY \
  --set auth.portalSecretKey=$(openssl rand -hex 32) \
  --set redis.auth.password=$(openssl rand -base64 24)

Ключевые параметры приведены ниже.

Параметр Описание

Параметр	Описание
`domain`	Внешнее имя, на которое публикуются портал, его API, File Recognizer и Gate
`auth.coreUrl`, `auth.userStateUrl`	Внешне доступные адреса Core и User State контура Base
`auth.coreToken`, `auth.coreApiKey`	UUID шлюза и API-токен из интерфейса Base
`auth.portalSecretKey`	Секретный ключ сессий портала
`vllm.enabled`, `vllm.extraArgs`	Включение Guard LLM Inference и дополнительные аргументы запуска vLLM
`gate.vllmUrl`	Адрес внешнего сервиса инференса; задаётся обязательно, если `vllm.enabled=false`
`vllm.gpu.count`, `gate.gpu.count`, `fileRecognizer.gpu.count`	Количество запрашиваемых GPU по компонентам
`redis.enabled` / `externalRedis.*`	Встроенный Redis либо внешний экземпляр
`ingress.enabled` / `httpRoute.enabled`	Способ публикации. Включать нужно ровно один

domain

Внешнее имя, на которое публикуются портал, его API, File Recognizer и Gate

auth.coreUrl, auth.userStateUrl

Внешне доступные адреса Core и User State контура Base

auth.coreToken, auth.coreApiKey

UUID шлюза и API-токен из интерфейса Base

auth.portalSecretKey

Секретный ключ сессий портала

vllm.enabled, vllm.extraArgs

Включение Guard LLM Inference и дополнительные аргументы запуска vLLM

gate.vllmUrl

Адрес внешнего сервиса инференса; задаётся обязательно, если vllm.enabled=false

vllm.gpu.count, gate.gpu.count, fileRecognizer.gpu.count

Количество запрашиваемых GPU по компонентам

redis.enabled / externalRedis.*

Встроенный Redis либо внешний экземпляр

ingress.enabled / httpRoute.enabled

Способ публикации. Включать нужно ровно один

Маршрутизация в пределах домена: / — портал, /api/ — серверная часть портала, /file_rec/ — File Recognizer, /gate/ — сам шлюз (префикс /gate отбрасывается при проксировании).

Чарт рассчитан на кластер с установленным NVIDIA gpu-operator.

6. Чарт starguard-gate-forward

Пример установки:

helm install gate-forward oci://docker.starguard-ai.ru/starguard/starguard-gate-forward \
  --version 1.2.0 \
  --namespace starguard-gate --create-namespace \
  --set global.imagePullSecrets[0].name=starguard-registry \
  --set auth.coreUrl=https://starguard.example.com \
  --set auth.coreToken=$GATE_UUID \
  --set auth.coreApiKey=$CORE_API_KEY \
  --set service.nodePort=30080

Ключевые параметры приведены ниже.

Параметр Описание

Параметр	Описание
`auth.coreUrl`, `auth.coreToken`, `auth.coreApiKey`	Подключение к Core: адрес, UUID шлюза, API-токен
`listenPort`	Порт, который слушает прокси внутри контейнера
`service.type`, `service.port`, `service.nodePort`	Параметры публикации. По умолчанию — NodePort; допустим LoadBalancer
`service.externalTrafficPolicy`	`Local` сохраняет реальный IP клиента в журнале прокси
`fileRecognizer.url`	Адрес уже развёрнутого сервиса File Recognizer (чарт его не разворачивает)
`env.FORWARD_CONFDIR`	Каталог, в который записывается CA-сертификат перехвата
`env.JWKS_VERIFY_X509_STRICT`	Строгая проверка сертификата JWKS-эндпоинта
`extraVolumes`, `extraVolumeMounts`	Монтирование корпоративного корневого сертификата; путь к нему указывается переменной `SSL_CERT_FILE`

auth.coreUrl, auth.coreToken, auth.coreApiKey

Подключение к Core: адрес, UUID шлюза, API-токен

listenPort

Порт, который слушает прокси внутри контейнера

service.type, service.port, service.nodePort

Параметры публикации. По умолчанию — NodePort; допустим LoadBalancer

service.externalTrafficPolicy

Local сохраняет реальный IP клиента в журнале прокси

fileRecognizer.url

Адрес уже развёрнутого сервиса File Recognizer (чарт его не разворачивает)

env.FORWARD_CONFDIR

Каталог, в который записывается CA-сертификат перехвата

env.JWKS_VERIFY_X509_STRICT

Строгая проверка сертификата JWKS-эндпоинта

extraVolumes, extraVolumeMounts

Монтирование корпоративного корневого сертификата; путь к нему указывается переменной SSL_CERT_FILE

Публикация только через NodePort или LoadBalancer. HTTP-прокси работает туннелями CONNECT и запросами в абсолютной форме, поэтому Ingress-контроллер для него не подходит — он терминирует и переписывает ровно тот трафик, который должен пройти нетронутым. Шаблонов Ingress и HTTPRoute в чарте нет.

7. Чарт starguard-scanner

Пример установки:

helm install starguard-scanner oci://docker.starguard-ai.ru/starguard/starguard-scanner \
  --version 1.2.0 \
  --namespace starguard --create-namespace \
  --set global.imagePullSecrets[0].name=starguard-registry \
  --set core.baseUrl=http://starguard-starguard-base-core:44000 \
  --set core.serviceToken=$SCANNER_SERVICE_TOKEN \
  --set metaSaver.url=http://starguard-starguard-base-vector:8686 \
  --set judge.baseUrl=http://starguard-gate-vllm.starguard-gate.svc:8000/v1 \
  --set judge.model=openai/gpt-oss-safeguard-20b

Ключевые параметры приведены ниже.

Параметр Описание

Параметр	Описание
`core.baseUrl`	Внутренний адрес сервиса Core
`core.serviceToken`	Общий секрет с Core. Должен совпадать с `SCANNER_SERVICE_TOKEN` в чарте `starguard-base`
`metaSaver.url`	Адрес приёмника Vector, куда записываются найденные уязвимости
`judge.baseUrl`, `judge.model`, `judge.apiKey`	Локальная модель, играющая роли атакующего и судьи в security-сканах LLM. Задаётся только здесь и не переопределяется из карточки скана
`scheduler.maxWorkers`	Количество одновременно выполняемых прогонов на один экземпляр
`scheduler.pollIntervalSeconds`	Периодичность опроса Core на наличие запущенных сканов
`tools.clamavDatabaseUpdateOnStartup`	Обновление антивирусных баз при старте. В изолированном контуре установите `false`
`persistence.enabled`	Постоянный том для антивирусных баз. По умолчанию выключен — используются базы из образа
`existingSecret`	Имя заранее созданного Secret с ключами `CORE_SERVICE_TOKEN` и `LLM_JUDGE_API_KEY`

core.baseUrl

Внутренний адрес сервиса Core

core.serviceToken

Общий секрет с Core. Должен совпадать с SCANNER_SERVICE_TOKEN в чарте starguard-base

metaSaver.url

Адрес приёмника Vector, куда записываются найденные уязвимости

judge.baseUrl, judge.model, judge.apiKey

Локальная модель, играющая роли атакующего и судьи в security-сканах LLM. Задаётся только здесь и не переопределяется из карточки скана

scheduler.maxWorkers

Количество одновременно выполняемых прогонов на один экземпляр

scheduler.pollIntervalSeconds

Периодичность опроса Core на наличие запущенных сканов

tools.clamavDatabaseUpdateOnStartup

Обновление антивирусных баз при старте. В изолированном контуре установите false

persistence.enabled

Постоянный том для антивирусных баз. По умолчанию выключен — используются базы из образа

existingSecret

Имя заранее созданного Secret с ключами CORE_SERVICE_TOKEN и LLM_JUDGE_API_KEY

Первые пять параметров (core.baseUrl, core.serviceToken, metaSaver.url, judge.baseUrl, judge.model) обязательны — без них чарт не устанавливается.

У сервиса нет HTTP-API и открытого порта, поэтому его состояние читается из журнала:

kubectl -n starguard logs -f deploy/starguard-scanner

При старте выводится строка scanner_tool_diagnostics с доступностью движков анализа. Недоступный движок не мешает запуску: соответствующие прогоны завершатся с ошибкой, видимой в карточке скана.