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

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-файлом окружения:

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-режима
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) сохраняются.

Проверка после установки

  1. GET /health сервера отвечает 200, GET /ready — ready; в split-режиме дополнительно проверьте /health исполнителя.
  2. В разделе Настройки → Исполнение видны профили и пулы; у работающего пула состояние ready, у настроенного, но ещё не созданного — configured.
  3. Выполните в сессии простую команду: она должна отработать на исполнителе, а не в процессе сервера.
  4. Если пул не появляется, проверьте журнал 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 её не удаляет и не защищает — дампы и политика хранения на вашей стороне.

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

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

Что дальше