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://git.itphx.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-режима |
provisioner.enabled |
Отдельный сервис, создающий пулы исполнителей по требованию |
executor.networkClass |
Сетевой класс статического пула: none, restricted, full |
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 — иначе последовательные вызовы одной сессии попадут
на разные поды.
Provisioner пулов¶
Статический пул — это заранее поднятый Deployment исполнителя. Если окружений нужно много и они должны появляться по требованию, рядом с сервером разворачивается provisioner — отдельный процесс, который создаёт поды пулов в кластере и выдаёт им адрес и токен.
execution:
mode: remote
remote:
provider: http # пулы запрашиваются у provisioner'а
pooling: project # отдельный пул на проект
provisioner:
url: http://synth-provisioner:5200
tokenSecret: /etc/synth/provisioner-token/token # путь, не значение
provisioner:
enabled: true
provider: kubernetes
kubernetes:
workspacePvc: synth-workspace # тот же том, что у сервера
Что разворачивает чарт при provisioner.enabled: true:
| Объект | Назначение |
|---|---|
| Deployment (1 реплика) | Сам сервис: не исполняет команды, только создаёт и снимает пулы |
Service (порт 5200) |
Точка запросов от сервера |
| ServiceAccount + Role/RoleBinding | Права на поды, секреты, а для прогрева образов — на DaemonSet'ы |
| NetworkPolicy (опционально) | Входящий трафик только от сервера, исходящий — DNS и API кластера |
Токен доверия между сервером и provisioner'ом — один Secret на обе стороны; сервер получает его файлом, значение в values не хранится.
| Ключ | По умолчанию | Назначение |
|---|---|---|
provisioner.provider |
static |
static — адреса из статического списка, kubernetes — поды по требованию |
provisioner.profiles |
{} |
Каталог профилей provisioner'а: образ, сеть, ресурсы, размещение |
provisioner.staticPools |
{} |
Точные адреса пулов для static |
provisioner.kubernetes.workspacePvc |
"" |
PVC с рабочими каталогами проектов (обязателен для kubernetes) |
provisioner.kubernetes.workspaceMount |
/var/synth/data/workspaces |
Точка монтирования тома в поде пула |
provisioner.kubernetes.fsGroup |
1000 |
Дополнительная группа подов пулов; на NFS — null |
provisioner.maxPools |
50 |
Лимит одновременно живых пулов |
provisioner.idleTimeoutMs / sessionIdleTimeoutMs |
15 мин / 5 мин | Снятие простаивающих пулов |
provisioner.maxLifetimeMs |
12 ч | Предельное время жизни пула |
provisioner.networkPolicy.apiServerCidrs |
[] |
CIDR'ы API кластера: без них политика с provider: kubernetes не рендерится |
Сначала provisioner, потом сервер
Обновляйте provisioner раньше сервера: сервер новой версии передаёт описание профиля, которого старый provisioner не понимает, и получит отказ на новых профилях. Обратный порядок ломает выдачу пулов.
Общий том workspace и подкаталог проекта¶
Сервер и все исполнители видят один и тот же каталог проектов, поэтому том
обязан поддерживать ReadWriteMany. В под пула монтируется не весь том, а
каталог проекта через subPath: соседние проекты и их файлы в под не
попадают.
executor.workspace.mountPathиprovisioner.kubernetes.workspaceMountдолжны совпадать с корнем рабочих каталогов сервера (storage.workspacesRoot).- Проект должен находиться внутри этого корня: при политике, запрещающей workspace вне корня, под без подкаталога смонтировал бы весь том.
- Для рабочей копии репозитория подкаталог указывает на её каталог, а не на основной checkout проекта.
Сетевые классы пулов¶
Класс сети — часть профиля, а не адрес: каждый пул несёт метку класса, а чарт рендерит на каждый класс отдельную сетевую политику. Ограничения одинаковы для статического и динамического пулов.
| Класс | Исходящий трафик |
|---|---|
none |
запрещён полностью, включая DNS |
restricted |
DNS и явно разрешённые адреса (networkClasses.restrictedEgress) |
full |
не ограничивается |
executor:
networkClass: restricted # класс статического пула
networkClasses:
enabled: true # рендерить политики классов
restrictedEgress:
- to: [{ ipBlock: { cidr: 203.0.113.0/24 } }]
ports: [{ protocol: TCP, port: 443 }]
- Политики живут в namespace релиза; поды динамических пулов создаются там же. Provisioner из другого namespace под них не попадёт.
- Сетевой плагин кластера должен поддерживать сетевые политики — иначе объекты есть, а ограничения не применяются.
- При включённых классах прежняя одиночная политика исполнителя не
рендерится: объединение правил ослабило бы
noneиrestricted. - Класс профиля по умолчанию для динамических пулов —
full: изолированные окружения должны указывать класс явно.
Прогрев образов¶
Первый пул с новым образом ждёт загрузки образа на узел. Прогрев убирает эту
задержку: администратор запускает его из раздела Настройки → Исполнение,
сервис поднимает временную нагрузку на узлы, дожидается готовности и удаляет
её. Для прогрева нужны права на DaemonSet'ы; доступен только при
provisioner.provider: kubernetes.
Изоляция и права¶
- Non-root. Процессы работают от uid 1000, без повышения привилегий и с
отброшенными возможностями; профиль безопасности —
RuntimeDefault. - Только чтение. Корневая файловая система контейнеров доступна на
чтение; записываемые каталоги выдаются отдельно:
emptyDirдля/tmpи домашнего каталога ($HOME), где живут кэши пакетов и временные файлы инструментов. - UI на порту 8080. Образ интерфейса — nginx на непривилегированном порту; входящий трафик приходит через Ingress.
- Права на каталог данных. На томах, где
fsGroupне действует (hostPath, NFS), включается init-контейнер, который выставляет владельца каталога данных (backend.ownershipInitContainer,executor.ownershipInitContainer). На NFS это разовая операция на десятки тысяч файлов — первый старт будет долгим. fsGroupдля NFS. Для подов пуловfsGroupпо умолчанию1000; на NFS-томе kubelet при старте рекурсивно меняет владельца всех файлов тома и под не запускается — в этом случаеprovisioner.kubernetes.fsGroupзадают какnull. Остальные ограничения (non-root, read-only, capabilities) сохраняются.
Проверка после установки¶
GET /healthсервера отвечает200,GET /ready—ready; в split-режиме дополнительно проверьте/healthисполнителя.- В разделе Настройки → Исполнение видны профили и пулы; у работающего
пула состояние
ready, у настроенного, но ещё не созданного —configured. - Выполните в сессии простую команду: она должна отработать на исполнителе, а не в процессе сервера.
- Если пул не появляется, проверьте журнал provisioner'а и права его ServiceAccount: чаще всего причина — лимит пулов, недоступный PVC или отсутствие CIDR'ов API кластера в сетевой политике.
Секреты¶
Чарт не создаёт 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-режим).
Версия чарта синхронизирована с версией платформы.
Что дальше¶
- Гибридный режим — корпоративный сервер + локальные машины.
- Исполнение: профили и пулы — профили, пулы и изоляция команд.
- Аутентификация и роли — роли и доступ.
- Конфигурация — настройки инстанса.
- Безопасность — политики и аудит.