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-файлом окружения:
Образы тянутся анонимно
Публичные образы 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
её не удаляет и не защищает — дампы и политика хранения на вашей стороне.
Полная резервная копия — дамп базы и все тома: данных, двоичных объектов (если
вынесены в отдельный PVC) и synth-workspace (если включён split-режим).
Версия чарта синхронизирована с версией платформы.
Что дальше¶
- Гибридный режим — корпоративный сервер + локальные машины.
- Аутентификация и роли — роли и доступ.
- Конфигурация — настройки инстанса.
- Безопасность — политики и аудит.