Развёртывание платформы

Назначение документа

Инструкция описывает воспроизводимую установку компонентов Платформы ИИ в Kubernetes с использованием Garden (Garden-проект aip-deploy). Документ предназначен для администраторов и разработчиков, выполняющих развёртывание продукта.

Важно: Эта инструкция не включает описание процедуры развертывания общеплатформенных сервисов RAG и Memory.

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

Garden управляет сборкой образов, формированием Helm-конфигурации и установкой всех управляемых ресурсов платформы. Ручные команды helm upgrade, kubectl apply и docker-compose не являются поддерживаемым способом установки.

Структура развёртываемых компонентов

Состав компонентов платформы и их зависимостей приведён в отдельном документе: Состав компонентов платформы

Дополнительные руководства:

• Control Plane — руководство администратора

В текущей архитектуре (R2) компоненты разбиты на три группы:

• Прикладные компоненты — Agent Registry, Control Plane, LLM Gateway, Team Docs, Low-code Конструктор.
• Общие провайдеры — PostgreSQL, SpiceDB, Temporal, Valkey, Redpanda, OpenSearch, OpenTelemetry.
• Шлюзовая инфраструктура — Gateway API, agentgateway, общий Gateway aip-gateway, ListenerSets.

Пространства имён

Единая схема aip-<env> с суффиксами (задаётся composition.namespaces, charts/aip-environment/values.yaml):

Пример для qa: aip-qa, aip-qa-models, aip-qa-agents, aip-qa-infra, aip-qa-low-code-ide, aip-qa-services.

Решение (ADR-0010): CP/AR/Docs в aip-<env>, модельный Gateway в aip-<env>-models; сохраняются agents, low-code-ide, общий infra. RAG/Memory — aip-<env>-services, отдельные релизы. Product chart не содержит bundled providers — только endpoints и credential references.

Helm-релизы

Зонтичный релиз aip собирает в единое развёртывание Agent Registry (aip-agent-registry), Control Plane (aip-control-plane), LLM Gateway (aip-model-gateway, в aip-<env>-models) и Team Docs (aip-docs).

Образы сервисов подтягиваются из корпоративного реестра nexus.inno.tech:19108 по секрету aip-image-pull-secret. Политика подтягивания — Always (qa) / IfNotPresent (dev-local).

Секреты

Ключевые секреты, создаваемые при развёртывании:

Шлюзовая инфраструктура

Шлюз построен на Gateway API 1.5.0 и agentgateway 1.5.0. Общий немодельный Gateway aip-gateway в agentgateway-system принадлежит DevOps; allowedListeners выбирает aip-qa и aip-rc. В dev-local Gateway и оператор поднимает Garden.

Две границы:

• Platform API Gateway (api-gw) — management/discovery (Agent Registry + Control Plane + Keycloak);
• Platform Agent Gateway (agent-gw) — A2A-invocation опубликованных агентов.

Пять ListenerSets живут в aip-<env>. Маршруты A2A опубликованных агентов создаёт Publisher в aip-<env>-agents по стабильному /a2a/v1/agents/{agent_id} на agent-gw.*-listeners.

Публичные ListenerSets секции https (QA):

Модельный Gateway остаётся отдельным: model-gw-qa.ai-dev.inno.tech.

Control Plane

Отдельный блок в aip-<env> (релиз aip, компонент aip-control-plane): api, Temporal-воркеры (model-worker, key-worker, publisher-worker, recovery-worker), orchestration-starter и опциональный SPA-фронтенд. Управление и вызов разделены: Control Plane — единственный public API для platform-managed desired state, Agent Registry — read-only каталог.

Оркестрация — через общий провайдер aip-temporal в aip-<env>-infra. Публикация агентов идёт только в aip-<env>-agents.

Примечание: Control Plane отключён по умолчанию (controlPlane.enabled=false). Для его активации необходимо явное включение в Helm-значениях. Control Plane активируется совместно с LLM Gateway. Подробности см. Control Plane — руководство администратора.

LLM Gateway

Живёт в aip-<env>-models как отдельный Gateway aip-model-gateway с собственным proxy и RLS (rate-limit service) на Valkey Sentinel (aip-valkey, пароль в aip-valkey). Может быть отключён; активируется вместе с Control Plane.

Окружения

Канонические идентификаторы

Garden environments: dev-local и qa. Отдельно поддерживается среда rc (устанавливается DevOps через Helm, не Garden environment).

dev-local

dev-local — одноразовый локальный профиль: Gateway и его оператор поднимает Garden, фиксированные локальные порты 18080–18083.

qa

Примечание: qa — переименованная среда st. Общее пространство имён ap-st и релизы ap-* больше не используются.

rc

Устанавливается DevOps через Helm; не Garden environment. Поддерживает один неймспейс (single-namespace render); релизы и владельцы ресурсов остаются раздельными. Состав поставки — 14 charts + самостоятельный identity bootstrap + опубликованные digests.

Публичные адреса qa

Важно: наличие и условия внешних ListenerSets нужно заново подтвердить перед каждым развёртыванием. Внешняя инфраструктура может измениться независимо от composition.

Сборка образов

Сборка выполняется действиями Garden (Build actions). Полный список:

Все composition-owned Build действия получают одинаковый versioned BuildKit secret ap_build_ca_bundle_00a76a28 (Innotech Root + Issuing CA).

Исходные репозитории и версионирование

Коммит композиции является воспроизводимой совместимой связкой версий (deployment BOM). Текущие закреплённые исходные ссылки:

Граф зависимостей развёртывания

Порядок поднимает Garden по графу действий:

environment (namespaces, shared credentials)
  ├── shared-postgresql → shared-databases
  │     ├── shared-spicedb
  │     └── shared-temporal
  ├── shared-opensearch
  ├── shared-redpanda
  ├── shared-valkey
  └── shared-opentelemetry

identity-provider/keycloak (aip-keycloak)
  └── realm-base (Job)
        ├── agent-platform-identity (Job)
        │     └── aip (Helm release: runtime)
        │           ├── Agent Registry (api, reconciler, relay, indexer)
        │           ├── Control Plane (api, workers, frontend)
        │           ├── LLM Gateway (models ns) + RLS
        │           └── Team Docs
        │                 └── aip (Helm release: fixtures, opt-in)
        │                       └── low-code agent (published via CP)
        ├── langflow-identity (Job)
        │     └── aip-low-code-ide (Helm release)
        │           ├── backend
        │           └── frontend
        │                 └── langflow-fixtures (Job)
        └── identity-fixtures (Job)

Ключевая последовательность: shared providers → keycloak → identity Jobs → runtime releases → fixtures.

Цели развёртывания

Базовая команда (на примере qa):

garden deploy all --env qa --yes

Повторный запуск является штатным способом восстановления после частичного сбоя: reconcilers и релизы Helm идемпотентны.

Важно: fixture-цели включаются только при прямом выборе agent-platform-fixtures или через агрегат all-fixtures, чтобы обычный garden deploy не создавал тестовые данные.

Изменение в R2: low-code тестовый агент lowcode-linguist-v1 больше не является отдельным чартом с статическим Deployment и HTTPRoute ap-agent-linguist. Агент публикуется реально через Control Plane API (тот же путь, что и Studio «Publish») и доступен по стабильному /a2a/v1/agents/{agent_id} через Agent Gateway. Smoke-агент sdk-smoke-v1 отключён до принятия ADR-0009.

Сводная таблица команд

Предварительная подготовка

Необходимые компоненты

• Kubernetes: кластер с контекстом ai-dev (qa) и доступом к записи в пространства имён;
• StorageClass: longhorn (qa) или standard (dev-local);
• Docker: доступен текущему пользователю, для локальной и кросс-сборки образов;
• Garden: установлен (версия фиксируется в составе проекта aip-deploy);
• Helm: версия 3.x или новее;
• kubectl: для диагностики;
• Python 3: для вспомогательных скриптов;
• kubeconfig: ~/.kube/ai-dev (qa) или ~/.kube/aip-dev-local (dev-local);
• curl и jq: для проверок.

Provider использует explicit kubeconfig/context, а не текущий.

RBAC-проверки

Перед развёртыванием убедитесь, что учётная запись имеет необходимые права:

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create deployments -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create serviceaccounts -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create secrets -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create httproutes.gateway.networking.k8s.io -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i patch httproutes.gateway.networking.k8s.io -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i delete httproutes.gateway.networking.k8s.io -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create roles.rbac.authorization.k8s.io -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev auth can-i create rolebindings.rbac.authorization.k8s.io -n aip-qa
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev \
  -n aip-qa get listenersets.gateway.networking.k8s.io

Проверка внешних родителей (qa)

Оператор обязан заново подтвердить наличие, hostnames, разрешённые пространства имён и условия (conditions) внешних ListenerSets перед каждым развёртыванием:

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev \
  -n aip-qa get listenerset \
  api-gw-qa.ai-dev.inno.tech-listeners \
  cp-qa.ai-dev.inno.tech-listeners \
  ide-qa.ai-dev.inno.tech-listeners \
  docs-qa.ai-dev.inno.tech-listeners \
  agent-gw-qa.ai-dev.inno.tech-listeners -o yaml

Остановитесь, если любой родитель отсутствует, не имеет условий Accepted=True и Programmed=True, не принимает маршруты из aip-qa или обслуживает другой hostname.

Статические проверки

cd deploy

python3 scripts/check_source_pins.py
garden get linked-repos --env qa
garden validate --env qa --resolve '*'

Если garden get linked-repos показывает локальные ссылки, сначала уберите их из checkout оператора. Локальные ссылки, включая bridge remote, не являются путём доставки.

Пошаговая инструкция по развёртыванию

Шаг 1. Проверка конфигурации

Из корня репозитория выполните валидацию:

garden validate --env qa --resolve '*'

Проверка должна завершиться до сборки образов. Если ошибка не исправлена, развёртывание будет прервано. Возможные причины ошибок:

• неверное пространство имён;
• занят один из фиксированных портов 18080–18083 (dev-local);
• отсутствует файл kubeconfig;
• недоступен реестр образов.

Шаг 2. Аутентификация в реестре образов

Garden автоматически выполняет действие qa-image-registry-auth перед сборкой. Оно выполняет вход в реестр и создаёт или обновляет секрет aip-image-pull-secret в целевых пространствах имён.

Для qa Garden использует учётные данные из deploy/values/secrets/qa.yaml. Учётные данные реестра не выводятся в журналы. Ручная аутентификация не требуется.

Шаг 3. Развёртывание

Развёртывание среды выполнения без тестовых данных

garden deploy all --env qa --yes

Эта команда последовательно поднимает:

1. Сборку образов приложений (публикация в Nexus по immutable digest);
2. Shared identity provider (Keycloak aip-keycloak);
3. Realm-base;
4. Идентификацию Платформы ИИ;
5. Идентификацию Low-code Конструктора;
6. Runtime Платформы ИИ (релиз aip: Agent Registry, Control Plane, LLM Gateway, Team Docs);
7. Low-code Runtime (aip-low-code-ide).

Развёртывание только Платформы ИИ с тестовыми данными

garden deploy agent-platform-fixtures --env qa --yes

Этот target:

• Поднимает runtime (транзитивно);
• Согласует тестовых пользователей Keycloak;
• Публикует low-code агента через Control Plane API;
• Согласует тестовых агентов и разрешения SpiceDB.

Полное развёртывание тестового стенда

garden deploy all-fixtures --env qa --yes

Рекомендуемая полная выкатка тестового стенда, включая пользователей тестовых данных, разрешения Low-code Конструктора и low-code агента.

Сценарий развёртывания RC только через Helm

Среда rc не является Garden environment: она устанавливается DevOps штатным Helm, без Garden и без соседних Git checkout на стороне установки. Поставка — чарт-бандл, подготовленный командой разработки, в котором bom.json фиксирует source SHA, версии и SHA-256 каждого архива; зависимости уже лежат внутри архивов.

Важно: это чарт-бандл, а не квалифицированный релиз. Отдельно требуются опубликованные image digests, согласованные RC values и проверка установки. QA values и credentials в бандл автоматически не экспортируются. Версия чарта сама по себе не уникальна между сборками — при передаче сверяйте digest из BOM.

Состав поставки

Бандл собирается из чистого, закоммиченного deploy:

python3 scripts/package_rc_charts.py \
  --agent-platform ../ai-platform --langflow ../langflow \
  --output .artifacts/rc-charts

В комплект входят 14 чартов (12 инфраструктурных + agent-platform + langflow-sso), самостоятельный identity bootstrap в identity/ и проверочный скрипт check_rc_delivery.py. Изображения передаются отдельным published-images.json (source SHA, Garden tag, полный repository@sha256:...).

Порядок установки

Каждый пункт — отдельный Helm-релиз. При single-namespace render все области направляются в один неймспейс, но отдельные release names сохраняются.

При external provider его релиз пропускают и передают endpoints/Secret references потребителям; product chart 0.2.0 не содержит bundled infrastructure providers.

Пример команды (имя файла и версия берутся из bom.json):

helm upgrade --install aip-postgresql charts/aip-postgresql-0.1.0.tgz \
  --namespace aip-rc-infra --values values/postgresql.yaml \
  --wait --timeout 15m

Последовательность не атомарна: после ошибки исправьте причину и повторите соответствующий релиз. Helm rollback не отменяет изменения схем/данных — процедуры backup/restore принадлежат DevOps.

Identity bootstrap без Garden

Keycloak-сервер разворачивается отдельно (локальный start-dev/H2 не выбран как RC server contract). После его подготовки из identity/ выполняется последовательный reconcile realm и application clients через Admin REST:

python3 reconcile.py --manifest realm-base.json && \
python3 reconcile.py --manifest agent-platform.json && \
python3 reconcile.py --manifest langflow.json

Реализация — только стандартная библиотека Python. Повторный запуск исправляет drift в своём scope, но не выполняет full-realm import или prune.

Проверка конфигурации

Перед установкой составляется installation plan, и выполняется render-проверка через локальный helm template (SHA архивов, коллизии Kubernetes identities, digests всех Pod images):

python3 check_rc_delivery.py --bundle . --plan /path/to/rc/installation.yaml

Render-проверка не заменяет проверку наличия образов в registry, существование внешних prerequisites и реальную установку — эти gate выполняются отдельно.

Проверка развёртывания

Проверка подов

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev \
  -n aip-qa get pods,deploy,statefulset,job,svc,pvc,httproute

Ожидаемые поды:

Проверка готовности компонентов (qa)

kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev -n aip-qa-infra \
  rollout status statefulset/aip-keycloak --timeout=10m
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev -n aip-qa-infra \
  rollout status statefulset/aip-postgresql --timeout=10m
kubectl --kubeconfig ~/.kube/ai-dev --context ai-dev -n aip-qa \
  rollout status deployment/aip-agent-registry-api --timeout=10m

Публичные проверки HTTP (qa)

curl -fsS https://api-gw-qa.ai-dev.inno.tech/agent-registry/health/ready | jq
curl -fsS \
  https://api-gw-qa.ai-dev.inno.tech/keycloak/realms/aip-qa/.well-known/openid-configuration |
  jq -e '.issuer == "https://api-gw-qa.ai-dev.inno.tech/keycloak/realms/aip-qa"'
curl -fsS https://ide-qa.ai-dev.inno.tech/config.js >/dev/null
curl -fsS https://docs-qa.ai-dev.inno.tech/health/ready

Проверка A2A-карточки опубликованного агента по стабильному пути:

curl -fsS https://agent-gw-qa.ai-dev.inno.tech/a2a/v1/agents/{agent_id}/.well-known/agent-card.json | jq

Обновление

Процесс обновления полностью повторяет процедуру первоначального развёртывания.

Важно: До начала обновления необходимо выполнить резервное копирование БД и важных перзистентных объектов в кластере Kubernetes.

Откат и очистка

Откат

Процесс не является атомарным. Для регрессии конфигурации или образа:

1. Возьмите предыдущий проверенный composition commit;
2. Повторите тот же target: reconcilers и релизы Helm идемпотентны.

Откат Git/Garden не откатывает автоматически миграции базы данных, изменения realm или содержимое PVC.

Очистка

Порядок деструктивной очистки, если он явно разрешён:

fixtures → приложения → идентификация приложения → realm-base → Keycloak/PVC

• Автоматических точек очистки тестовых данных нет;
• Удаление shared данных выполняется только версионированной миграцией с точным селектором владения и подтверждением человека;
• Не удаляйте aip-qa, Keycloak PVC или тестовые данные как «откат»;
• Деструктивная очистка выполняется только версионированной миграцией с отдельным порогом подтверждения человека.

Завершение работы (dev-local)

Для полного удаления локального развёртывания:

garden deploy --env dev-local --uninstall

Примечание: При удалении пространств имён все данные PostgreSQL, SpiceDB, OpenSearch и Redpanda будут безвозвратно удалены.

Безопасность

Правила работы в среде

• Запрещено изменять GatewayClass, Gateway, IngressClass, cluster-операторы и чужие пространства имён.
• Cluster-scoped RBAC выключен в Helm-значениях.
• Создание и ротация секретов требуют отдельного подтверждения человека.
• Garden system-метаданные направляются в целевое пространство имён, а не в общий garden-system.

Учётные данные и секреты

• Registry pull secrets создаются отдельно в каждом пространстве имён; Kubernetes Secret не переносится между пространствами имён ссылкой;
• Текущий qa хранит Nexus, управляемый Keycloak admin, тестовые данные и модельные provider учётные данные в deploy/values/secrets/qa.yaml. Они не переиспользуются вне тестового окружения;
• Scibox key должен быть test-only и ограниченным по квоте;
• Production/external учётные данные всегда используют отдельный источник секретов с описанными владельцем, ротацией и сроком действия.

Доверие при сборке

• Корпоративные CA-сертификаты версионированы в deploy/trust/;
• Скрипт import_build_trust.py проверяет и объединяет точные fingerprinted Root и Issuing CA файлы в единый bundle;
• Все composition-owned Build действия получают одинаковый versioned BuildKit secret;
• Product Dockerfiles добавляют bundle в существующую систему доверия только в этапах, инициирующих TLS;
• Временные обходные пути insecure-host и отключённого sslverify не являются принятым путём сборки.

Управление Keycloak

• Administrative credential монтируется только в bootstrap/reconcile execution и никогда не передаётся runtime pods Платформы ИИ или Low-code Конструктора;
• Reconciler не выполняет полную замену realm и не удаляет неизвестные объекты;
• AP и Low-code Конструктор reconcilers получают минимальную область владения; параллельный запуск не должен приводить к потере обновлений.

Сеть и проверка идентификации

• Browser issuer должен точно совпадать с токеном iss;
• Low-code Конструктор callbacks и Web Origins используют точный environment public origin: https://ide-qa.ai-dev.inno.tech в qa. Полные wildcard, внешний redirect wildcard и отключённая проверка redirect запрещены;
• OIDC validation включает signature, issuer, audience и ожидаемые role/client claims; missing identity возвращает 401, insufficient permission — 403;
• Cross-namespace трафик требует явных контрактов NetworkPolicy/DNS.

Тестовые данные

• Fixtures разрешены только явным allowlist окружений; prod всегда deny;
• Fixtures используют детерминированные IDs/метки/prefix и согласование, а не добавление;
• all никогда не включает seed тестовых данных;
• Публикация в aip-<env>-agents блокируется admission, ClusterIP и default-deny NetworkPolicy.

Устранение неполадок

Поды не переходят в состояние Running

1. Проверьте статус подов:

   kubectl -n aip-qa get pods --sort-by=.metadata.creationTimestamp

2. Просмотрите журналы проблемного пода:

   kubectl -n aip-qa logs <pod-name> --tail=200

3. Проверьте события:

   kubectl -n aip-qa get events --sort-by=.lastTimestamp

4. Наиболее частая причина — поды не готовы, а не сбой Helm. Повторите garden deploy после устранения причины.

Занятые порты

Garden dev-local использует фиксированные локальные порты 18080–18083. Если один из них занят, развёртывание завершается ошибкой до начала rollout. Освободите порт или завершите процесс, использующий его.

Ошибка аутентификации реестра

Если действие qa-image-registry-auth завершается ошибкой:

1. Проверьте доступность Nexus.
2. Убедитесь, что учётные данные реестра корректны.
3. Проверьте, что kubeconfig содержит контекст ai-dev.

Ошибка миграции базы данных

1. Остановите развёртывание.
2. Сохраните журнал миграции Alembic.
3. Восстановите совместимый образ приложения.
4. Убедитесь, что alembic check не выдаёт ошибок перед повторной попыткой.

Фикстуры

Фикстуры пользователей

При развёртывании создаются ролеориентированные пользователи Keycloak:

Пароли fixture-пользователей хранятся в секрете aip-identity-fixture-users. Эти учётные записи создаются только в non-production средах и не переносятся в промышленную эксплуатацию.

Фикстуры агентов

Материалы для фиксации результата

При развёртывании сохраните:

• точную команду, среду и время выполнения;
• версии Garden, Docker и Kubernetes;
• пространства имён и версии действий Garden;
• идентификаторы (digests) собранных образов;
• результаты миграций базы данных;
• проверки работоспособности подов;
• результаты тестирования API;
• ограничения среды (отключённые компоненты, внутрикластерные DNS).

Не сохраняйте в журнале учётные данные, токены и пользовательские запросы.