Перейти к содержанию

Kubernetes / Helm

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

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

Сотрудники ←→ Ingress ←→ synth-ui (nginx :8080) ←→ synth-backend (:5000)
                                                          │
                                      ┌───────────────────┴───────────────────┐
                                PostgreSQL / PVC                        synth-executor
                                (состояние, блоки)                      (split, опционально)
Сервис Роль
synth-ui React SPA под nginx. Проксирует /api, /ws, /auth, /admin, /health на backend
synth-backend API Hub: OIDC + RBAC + встроенный движок; состояние — PostgreSQL или файлы на PVC
synth-executor Опциональный пул исполнителей: shell, git и поиск в split-режиме

Одна реплика backend по умолчанию

Чарт разворачивает backend в одной реплике: файловое хранилище не масштабируется горизонтально. Несколько реплик возможны только с PostgreSQL, общим томом двоичных объектов и привязкой клиента к поду — см. раздел «Хранилище: файлы или PostgreSQL». Сам backend самодостаточен: исполнитель нужен только для изоляции инструментов.

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

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


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

  • Роли и вход


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

  • История и сессии


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

  • Аудит


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

Требования

  • Kubernetes >= 1.24, Helm 3.
  • StorageClass для PVC backend (по умолчанию — класс кластера).
  • Для PostgreSQL — доступный сервер БД: чарт разворачивает только Synth, но не саму базу. Нужны права на создание таблиц в схеме.
  • Для split-режима — StorageClass с поддержкой ReadWriteMany под общий рабочий том (или заранее созданный claim) и образ исполнителя.
  • 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)
backend.blobs.* Отдельный PVC для двоичных объектов (по умолчанию выключен; нужен при нескольких репликах)
storage.backend file (по умолчанию), memory или postgres
storage.postgres.* Подключение к БД: хост, порт, база, пользователь, схема, TLS, пул
execution.mode inline (по умолчанию) или remote — топология исполнения команд
executor.enabled Пул исполнителей для split-режима
ui.image.repository / tag Образ UI и его тег
ingress.enabled / controller / hosts / tls Ingress, TLS и редирект
secrets.existingSecret Имя Secret с секретами (по умолчанию synth-secrets)
caCert PEM внутреннего CA, если провайдеры и IdP подписаны своим удостоверяющим центром

Полный список значений — в документации Helm-чарта.

Хранилище: файлы или PostgreSQL

По умолчанию состояние лежит в файлах на PVC. Для большой истории или нескольких реплик управляющего слоя переведите его в PostgreSQL:

storage:
  backend: postgres
  postgres:
    host: postgres.example.com
    port: 5432
    database: synth
    user: synth
    schema: synth
    ssl: true
    poolMax: 10
  degradedMode: halt

Пароль задаётся только через Secret в ключе SYNTH_POSTGRES_PASSWORD; в values его нет. Строка подключения целиком (DSN) в values не поддерживается — параметры перечислены отдельными полями, чтобы секрет не попал в ConfigMap. Схему драйвер приводит в порядок при старте: отдельная инициализация не нужна, но у пользователя БД должны быть права на создание таблиц.

Деградация

Для базы рекомендуется storage.degradedMode: halt: при недоступной БД инстанс не стартует, а не переходит молча на файловый фоллбек. Режим fallback-file поднимает сервер только для чтения и диагностики.

Несколько реплик — только с PostgreSQL

Файловое хранилище не масштабируется. Если реплик backend больше одной, нужны одновременно: PostgreSQL, отдельный PVC для двоичных объектов с доступом ReadWriteMany (backend.blobs.enabled: true) и привязка клиента к поду (backend.service.sessionAffinity: ClientIP). Для UI в этом случае так же задаётся ui.service.sessionAffinity: ClientIP, иначе цепочка «клиент → UI → backend» будет рваться. По умолчанию чарт разворачивает одну реплику и HA не настраивает.

Раздельное исполнение (исполнитель)

В обычном режиме (inline) команды агента исполняются в процессе backend. Если инструменты и их зависимости нужно изолировать, включите пул исполнителей — сервер останется тонким управляющим слоем:

execution:
  mode: remote
  remote:
    url: []            # пусто → адрес Service пула
    timeoutMs: 30000
    failMode: fail     # fail-closed: без исполнителя команда не выполняется
executor:
  enabled: true
  replicaCount: 1
  workspace:
    accessMode: ReadWriteMany

Токен доверия один на обе стороны и хранится в Secret (ключ SYNTH_EXECUTION_TOKEN): backend читает его из файла, исполнитель — из переменной окружения. Значение в values не попадает.

Ключ По умолчанию Назначение
executor.enabled false Включить пул исполнителей
executor.replicaCount 1 Число реплик пула
executor.image.repository / tag образ исполнителя / версия чарта Образ исполнителя
executor.service.port 5100 Порт API исполнителя
executor.service.sessionAffinity None ClientIP при нескольких репликах: браузерные MCP-сессии живут внутри пода
executor.limits.maxConcurrency 4 Одновременных команд в одном исполнителе
executor.limits.maxTimeoutMs 120000 Потолок таймаута команды, мс
executor.limits.maxOutputBytes 10485760 Потолок вывода, байт
executor.metrics.enabled false Собственный /metrics исполнителя
executor.mcp.enabled true MCP-серверы внутри исполнителя
executor.workspace.accessMode ReadWriteMany Режим доступа общего тома
executor.workspace.existingClaim "" Свой claim, если нет RWX-класса
executor.workspace.mountPath /var/synth/data/workspaces Один и тот же путь в backend и исполнителе
executor.networkPolicy.enabled false Сетевая изоляция пула
executor.token.existingSecret "" Secret с токеном; пусто → общий Secret релиза

Требуется RWX-том

Общий рабочий том видят и backend, и все реплики исполнителя, поэтому он обязан поддерживать ReadWriteMany — подойдут NFS/CephFS-подобные классы, но не local-path и не ReadWriteOnce. Если RWX-класса в кластере нет, создайте claim заранее и передайте его в executor.workspace.existingClaim.

Сеть исполнителя

При executor.networkPolicy.enabled: true входящий трафик разрешён только от управляющего слоя, а исходящий — только DNS. Доступ к внешнему git или API добавляется явно через executor.networkPolicy.allowedEgress.

Несколько реплик исполнителя

Балансировку между репликами делает Service. Для браузерных MCP-сессий, которые живут внутри пода, задайте executor.service.sessionAffinity со значением ClientIP — иначе последовательные вызовы одной сессии попадут на разные поды.

Секреты

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

Ключ Когда нужен
SYNTH_OIDC_CLIENT_SECRET при backend.oidc.enabled: true
SYNTH_PROVIDER_<NAME>_API_KEY для каждого провайдера с apiKey: true
SYNTH_POSTGRES_PASSWORD при storage.backend: postgres
SYNTH_EXECUTION_TOKEN при execution.mode: remote — токен доверия исполнителя
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: "qwen3.8:27b"
      apiKey: false

Для type: ollama URL указывайте нативным — http://ollama.internal:11434 (без /v1): так работают num_ctx, think и инструменты. Старый URL с суффиксом /v1 будет автоматически приведён к нативному /api/chat (с предупреждением в лог); OpenAI-совместимый путь — отдельный провайдер type: openai/generic.

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.

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

По умолчанию состояние хранится на PVC (backend.persistence, 10Gi) и переживает обновления. При storage.backend: postgres состояние уходит в базу, а на PVC остаются секреты, служебные метаданные и двоичные объекты (вложения, артефакты, логи процессов). База живёт вне чарта: helm uninstall её не удаляет и не защищает — дампы и политика хранения на вашей стороне.

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

Полная резервная копия — дамп базы и все тома: данных, двоичных объектов (если вынесены в отдельный PVC) и synth-workspace (если включён split-режим). Версия чарта синхронизирована с версией платформы.

Что дальше