Kubernetes / Helm¶

Для командной работы Synth разворачивается в Kubernetes: интерфейс и backend работают в кластере, история, ключи и аудит централизованы. Установка — публикуемым Helm-чартом, все параметры окружения задаются через values.

Архитектура managed-развёртывания¶

Сотрудники ←→ Ingress ←→ synth-ui (nginx :8080) ←→ synth-backend (:5000)
                                                          │
                                                    PVC: JSON-данные

Сервис	Роль
synth-ui	React SPA под nginx. Проксирует `/api`, `/ws`, `/auth`, `/admin`, `/health` на backend
synth-backend	API Hub: OIDC + RBAC + встроенный движок; JSON-хранилище на PVC

Одна реплика backend

Хранилище JSON не масштабируется горизонтально, поэтому backend всегда работает в одной реплике. Сам backend самодостаточен — отдельный раннер не разворачивается.

Что централизуется¶

Ключи провайдеров

API-ключи моделей хранятся только на сервере и не покидают кластер.
Роли и вход

Единый вход через OIDC (Keycloak), роли ADMIN / USER / LEAD / AUDITOR.
История и сессии

Общая история и состояние сессий — перезапуск и переподключение их не теряют.
Аудит

Каждый LLM-запрос логируется: кто, когда, какая модель, сколько токенов.

Требования¶

Kubernetes >= 1.24, Helm 3.
StorageClass для PVC backend (по умолчанию — класс кластера).
Secret с секретами в namespace релиза (см. ниже).
Опционально — Ingress-контроллер: nginx (по умолчанию) или Traefik, для авто-редиректа HTTP→HTTPS. Без контроллера чарт тоже работает.

Установка¶

helm repo add synth https://gitverse.ru/api/packages/itphx/helm
helm repo update

# Минимальная установка (публичные образы, ingress выключен)
helm install synth synth/synth --namespace synth --create-namespace

С values-файлом окружения:

helm install synth synth/synth -f my-values.yaml --namespace synth --create-namespace

Образы тянутся анонимно

Публичные образы backend и UI доступны без imagePullSecret. Для приватного реестра задайте backend.imagePullSecrets / ui.imagePullSecrets.

Ключевые значения¶

Ключ	Назначение
`backend.image.repository` / `tag`	Образ backend и его тег
`backend.oidc.enabled`	Включить вход через OIDC
`backend.oidc.issuer` / `clientId` / `redirectUri`	Параметры клиента IdP
`backend.providers`	Список LLM-провайдеров
`backend.persistence.*`	PVC для данных (по умолчанию `enabled: true`, `10Gi`)
`ui.image.repository` / `tag`	Образ UI и его тег
`ingress.enabled` / `controller` / `hosts` / `tls`	Ingress, TLS и редирект
`secrets.existingSecret`	Имя Secret с секретами (по умолчанию `synth-secrets`)
`caCert`	PEM внутреннего CA, если провайдеры и IdP подписаны своим удостоверяющим центром

Полный пример — в charts/synth/values.example.yaml репозитория.

Секреты¶

Чарт не создаёт Secret — он должен существовать в namespace релиза под именем secrets.existingSecret (по умолчанию synth-secrets).

Ключ	Когда нужен
`SYNTH_OIDC_CLIENT_SECRET`	при `backend.oidc.enabled: true`
`SYNTH_PROVIDER_<NAME>_API_KEY`	для каждого провайдера с `apiKey: true`

kubectl create secret generic synth-secrets \
  --namespace synth \
  --from-literal=SYNTH_OIDC_CLIENT_SECRET='<client-secret>' \
  --from-literal=SYNTH_PROVIDER_OPENAI_API_KEY='<api-key>'

Секреты хранятся вне чарта

Заводите Secret вручную, через External Secrets Operator, sealed-secrets или другим принятым в компании способом. Зашифрованных секретов в чарте нет.

OIDC и SSO¶

Включите вход через Identity Provider и задайте параметры клиента:

backend:
  oidc:
    enabled: true
    issuer: https://idp.example.com/realms/synth
    clientId: synth
    redirectUri: https://synth.example.com/auth/callback

Роли пользователя берутся из утверждений IdP и маппятся на встроенные роли Synth. Подробности настройки — в разделах Аутентификация и роли и SSO / Keycloak.

Провайдеры LLM¶

Список задаётся в values; backend подхватывает провайдеров при старте. Ключ (если apiKey не false) читается из Secret.

backend:
  providers:
    - name: openai
      type: openai
      url: "https://api.openai.com/v1/"
      model: "gpt-4o-mini"
      apiKey: true
    - name: local
      type: ollama
      url: "http://ollama.internal:11434"
      model: "qwen2.5:14b"
      apiKey: false

Ingress и TLS¶

ingress.enabled: true создаёт обычный Ingress (/ → UI-сервис). Способ редиректа HTTP→HTTPS задаётся ingress.controller:

`ingress.controller`	HTTP→HTTPS
`nginx` (по умолчанию)	на nginx-контроллере
`traefik`	на Traefik (CRD `Middleware` + `IngressRoute`)
`none`	не управляется чартом

Заполните ingress.hosts и ingress.tls (имя Secret с сертификатом) — для nginx-редиректа нужен настроенный TLS. Произвольные аннотации, например для cert-manager, задаются в ingress.annotations.

Данные и обновление¶

Данные backend хранятся на PVC (backend.persistence, по умолчанию 10Gi) и переживают обновления. Версия чарта синхронизирована с версией платформы.

helm upgrade synth synth/synth -f my-values.yaml --namespace synth

Что дальше¶

Гибридный режим — корпоративный сервер + локальные машины.
Аутентификация и роли — роли и доступ.
Конфигурация — настройки инстанса.
Безопасность — политики и аудит.