AI Platform Docs
Администрирование

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

Инструкция по развёртыванию компонентов Платформы ИИ

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

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

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

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

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


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

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

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

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

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

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

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

Пространство имёнСодержимое
aip-<env>aip: Control Plane (CP), Agent Registry, Team Docs; миграции приложения
aip-<env>-infraPostgreSQL, отдельные базы, SpiceDB, Temporal, Redpanda, OpenSearch, OTel, Valkey, Keycloak; опциональный RabbitMQ; ClickHouse и очередь Activity в dev-local
aip-<env>-modelsaip-model-gateway, маршруты и политики моделей, ограничитель скорости, учётные данные моделей
aip-<env>-agentsрабочие нагрузки и маршруты Publisher и доставленные ключи агентов
aip-<env>-low-code-ideaip-low-code-ide: Low-code Конструктор
aip-<env>-servicesRAG и Memory, подключаемые по запросу
agentgateway-systemединственный оператор agentgateway (общий Gateway DevOps)

Пример для 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-релизы

Релиз HelmЧартПространство имён
aip-environmentcharts/aip-environmentaip-<env>
aip-postgresqlcharts/aip-postgresqlaip-<env>-infra
aip-databasescharts/aip-databasesaip-<env>-infra
aip-spicedbcharts/aip-spicedbaip-<env>-infra
aip-temporalcharts/aip-temporalaip-<env>-infra
aip-valkeycharts/aip-valkeyaip-<env>-infra
aip-redpandacharts/aip-redpandaaip-<env>-infra
aip-opensearchcharts/aip-opensearchaip-<env>-infra
aip-opentelemetrycharts/aip-opentelemetryaip-<env>-infra
aip-clickhouse (dev-local)charts/aip-clickhouseaip-dev-local-infra
aip-activity-schema (dev-local)charts/agent-platform, только профиль Collector и миграция Activityaip-dev-local-infra
aip-rabbitmqcharts/aip-rabbitmq (по запросу)aip-<env>-infra
aip-keycloakkeycloakx версии 7.2.2 (Codecentric, OCI)aip-<env>-infra
aipcharts/agent-platformaip-<env>
aip (тестовые данные)charts/agent-platformaip-<env>-infra
aip-low-code-idecharts/langflow-ssoaip-<env>-low-code-ide

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

В QA образы сервисов подтягиваются из корпоративного реестра nexus.inno.tech:19108 по секрету aip-image-pull-secret, с политикой Always. В dev-local используются локальные сборки и закреплённые публичные образы с политикой IfNotPresent. Корпоративные DNS, VPN, ai-dev и Nexus для базового локального сценария не требуются; загрузка отсутствующих публичных зависимостей может требовать доступа в Интернет.


Секреты

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

СекретСодержимоеПространство имён
aip-image-pull-secretУчётные данные реестрацелевое пространство
aip-identity-adminАдминистративные учётные данные Keycloakaip-<env>-infra
aip-identity-fixture-usersПароли тестовых пользователей и ключ LLM API (по запросу)aip-<env>-infra
aip-model-provider-sciboxКлюч API SCIBOXaip-<env>-models
aip-agent-registry-publication-observerСекрет клиента публикацииинфраструктура и платформа
aip-valkeyПароль Valkey/Sentinel (RLS)aip-<env>-infra
aip-agent-registryПриложение: БД, SpiceDB, OpenSearch, Kafkaaip-<env>
aip-control-plane-databaseСтрока подключения CP БДaip-<env>
aip-activity-reader (dev-local)Только чтение Activity из CPaip-dev-local
aip-activity-collector, aip-activity-migrator, aip-activity-bootstrap (dev-local)Раздельные полномочия доставки, миграции и создания базы Activityaip-dev-local-infra
aip-activity-server (dev-local)Хеши паролей учётных записей ClickHouseaip-dev-local-infra
ap_build_ca_bundle_00a76a28Корневой и промежуточный центры сертификации Innotechсборка

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

Шлюз построен на 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):

ListenerSetHostМаршруты
api-gw-qa.ai-dev.inno.tech-listenersapi-gw-qa.ai-dev.inno.techAPI (AR + CP), Keycloak
cp-qa.ai-dev.inno.tech-listenerscp-qa.ai-dev.inno.techControl Plane UI
ide-qa.ai-dev.inno.tech-listenerside-qa.ai-dev.inno.techLow-code Конструктор
docs-qa.ai-dev.inno.tech-listenersdocs-qa.ai-dev.inno.techTeam Docs
agent-gw-qa.ai-dev.inno.tech-listenersagent-gw-qa.ai-dev.inno.techA2A invocation (public/validation)

Модельный 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

ПараметрЗначение
КластерKind ap-dev-local, context kind-ap-dev-local
kubeconfig~/.kube/aip-dev-local
Пространство имёнaip-dev-local (+ суффиксы)
StorageClassstandard
Registryap-dev-local-registry на 127.0.0.1:5001
Режим сборкиlocal-docker, без кросс-сборки
Канонические URLapi-gw.localhost:18085, cp.localhost:18085, ide.localhost:18086, docs.localhost:18086, agent-gw.localhost:18087

dev-local — локальный профиль: Gateway и его оператор поднимает Garden. Для основного развёртывания и проверок используйте скрипт запуска из каталога deploy; он сам выбирает среду и изолирует конфигурацию Helm от реестров рабочей станции:

python3 scripts/dev_local_garden.py deploy agent-platform --yes
python3 scripts/dev_local_garden.py run activity-main-smoke
python3 scripts/dev_local_garden.py test activity-provider-boundary

Параметр --env скрипт запуска не принимает. Первая проверка выполняет известный LLM-запрос и читает его через CP; вторая проверяет сетевую границу Activity и сохранение общего приёма OTLP. Базовый LLM-провайдер — локальный эмулятор OpenAI API. Настоящая модель подключается отдельно и не является условием базовой проверки платформы.

Activity в основном dev-local

Композиция включает ClickHouse 26.8.10.6, Contrib 0.156.0 и события от шлюзов на agentgateway 1.5.0. Закреплённые идентификаторы образов приведены в составе зависимостей.

Последовательность зависимостей:

shared-clickhouse → agent-platform-activity-schema → shared-opentelemetry
                    └──────────────────────────────→ agent-platform

Продуктовый чарт поставляет профиль доставки и конечное миграционное задание; общие провайдеры устанавливает композиция. Collector получает отдельный вход Activity: Service aip-activity-otlp:4317 направляет трафик на порт 4319. Общие входы OTLP 4317/4318 Collector продолжают обслуживать остальные сигналы. ClickHouse недоступен напрямую обычным рабочим нагрузкам.

Очередь использует PVC aip-activity-queue размером 4Gi, ClickHouse — aip-clickhouse-data размером 20Gi. Оба тома сохраняются при удалении соответствующего Helm-релиза благодаря helm.sh/resource-policy: keep; удаление пространства имён этой защитой не покрывается. Это локальные значения конфигурации, а не принятый размер для промышленной нагрузки.

Подключение CP задаётся activity.enabled, activity.otlpEndpoint, activity.clickhouseHttpEndpoint, activity.readSecretName и параметрами activity.observer. Миграция и профиль доставки включаются отдельно через activity.delivery.enabled и activity.delivery.migratorSecretName. Источник Agent Gateway доставляет композиция отдельно от модельного шлюза; один флаг CP не заменяет проверку обеих конфигураций.

Итоговая квалификация AU-I05 ещё выполняется. Автоматическое включение этой цепочки в QA/RC, промышленная отказоустойчивость и гарантированная граница потери данных в текущую локальную поставку не входят. Порядок выключения, опустошения очереди и восстановления приведён в руководстве оператора.

qa

ПараметрЗначение
Контекст kubeai-dev
Пространство имёнaip-qa (+ суффиксы)
StorageClasslonghorn
Registrynexus.inno.tech:19108/ap
Режим сборкиlocal-docker с кросс-сборкой linux/amd64
Keycloakaip-keycloak в aip-qa-infra

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

rc

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

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

КомпонентURL
Платформа ИИ (AR + CP)https://api-gw-qa.ai-dev.inno.tech/agent-registry
Control Planehttps://api-gw-qa.ai-dev.inno.tech/control-plane
Control Plane UIhttps://cp-qa.ai-dev.inno.tech
Keycloakhttps://api-gw-qa.ai-dev.inno.tech/keycloak
Low-code Конструкторhttps://ide-qa.ai-dev.inno.tech
Team Docshttps://docs-qa.ai-dev.inno.tech
A2A invocationhttps://agent-gw-qa.ai-dev.inno.tech
LLM Gatewayhttps://model-gw-qa.ai-dev.inno.tech

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


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

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

Build actionПродукт
agent-platform-imageAgent Registry API
control-plane-imageControl Plane (api + workers)
control-plane-frontend-imageControl Plane SPA
team-docs-imageTeam Docs
low-code-runtime-imagelow-code fixture runtime
platform-lfx-wheel-imagecarrier для LFX wheel (ADR-0009)
langflow-backend-imageLow-code Конструктор backend
langflow-frontend-imageLow-code Конструктор frontend
keycloak-reconciler-imageidentity reconciler Jobs

Для сборок с корпоративными зависимостями используется секрет BuildKit ap_build_ca_bundle_00a76a28 (корневой и промежуточный центры сертификации Innotech). Базовый dev-local не требует корпоративного хранилища образов и такого подключения.


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

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

РепозиторийURL
Платформа ИИssh://git@sfera-t1.ru:22/SCIBOX/aip/ai-platform.git#<commit>
Low-code Конструкторssh://git@sfera-t1.ru:22/SCIBOX/aip/langflow.git#<commit>
RAG (read-only)ssh://git@sfera-t1.ru:22/SCIBOX/aip/rag.git#<commit>
Memory (read-only)ssh://git@sfera-t1.ru:22/SCIBOX/aip/memory.git#<commit>

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

Порядок поднимает 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.


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

Цель GardenНазначение
allАгрегирует обе ветки runtime над одним общим identity provider: deploy.agent-platform + deploy.langflow
agent-platformRuntime Платформы ИИ без opt-in фикстур
langflowRuntime Low-code Конструктора без opt-in фикстур
agent-platform-fixturesOpt-in фикстуры: пользователи, low-code агент (публикуется через Control Plane)
all-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.


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

ДействиеКоманда
Валидация конфигурацииgarden validate --env qa
Развёртывание (qa)garden deploy all --env qa --yes
Только runtime Платформыgarden deploy agent-platform --env qa --yes
Только Low-codegarden deploy langflow --env qa --yes
Fixture Платформыgarden deploy agent-platform-fixtures --env qa --yes
Full fixturesgarden deploy all-fixtures --env qa --yes
Проверка подовkubectl -n aip-qa get pods
Удаление (dev)garden deploy --env qa --uninstall

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

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

  • 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 сохраняются.

ПорядокRelease / chartОбластьОбязательное условие
1aip-environmentplatformНеймспейс релиза существует
2aip-postgresqlinfraCredentials окружения
3aip-databasesinfraPostgreSQL готов
4aip-spicedb, aip-temporalinfraПрикладные БД и роли созданы
4aip-redpanda, aip-opensearch, aip-opentelemetry, aip-valkeyinfraCredentials окружения
4, opt-inaip-rabbitmqinfraНужен только для RAG/Memory
5aip / agent-platformplatform, models, agentsПровайдеры, идентичность, Gateway
5aip-low-code-ide / langflow-ssoideИдентичность и endpoints платформы
5, opt-inaip-rag, aip-memoryservicesPostgreSQL, OpenSearch, RabbitMQ

При 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

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

ПодСтатус
aip-agent-registry-apiRunning
aip-control-plane-apiRunning (если включён)
aip-team-docs-webRunning
aip-keycloakRunning
aip-postgresqlRunning
aip-spicedbRunning
aip-opensearchRunning
aip-redpandaRunning
aip-valkeyRunning
aip-temporalRunning
aip-opentelemetry-collectorRunning
aip-model-gatewayRunning (если включён)

Проверка готовности компонентов (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.

Для Activity после перехода в activity-storage/v2 нужен совместимый читатель. Старый читатель v1 не возвращается простым откатом коммита. При выключении экспорта сначала подтвердите остановку обоих источников, затем доставку принятых событий, сохраняя PVC очереди и ClickHouse. Не удаляйте аналитическую историю для возврата приложения. См. план миграции.

Очистка

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

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

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

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

python3 scripts/dev_local_garden.py deploy --uninstall

Примечание: При удалении пространств имён будут удалены также тома ClickHouse и очереди Activity. Удаление локального стенда не является процедурой возврата версии с сохранением истории.


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

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

  • Запрещено изменять 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:

ПользовательРоль
workspace-adminАдминистратор рабочей области
agent-invokerВызывающий агент
unauthorized-userЗапрещённый пользователь (тест)

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

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

АгентТип реализацииСтатус
lowcode-linguist-v1low-codeОпубликован через Control Plane API, доступен по /a2a/v1/agents/{agent_id}
sdk-smoke-v1sdkОтключён до принятия ADR-0009 (нет R2-пути публикации)

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

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

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

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

На этой странице

Назначение документаАрхитектура развёртыванияСтруктура развёртываемых компонентовПространства имёнHelm-релизыСекретыШлюзовая инфраструктураControl PlaneLLM GatewayОкруженияКанонические идентификаторыdev-localActivity в основном dev-localqarcПубличные адреса qaСборка образовИсходные репозитории и версионированиеГраф зависимостей развёртыванияЦели развёртыванияСводная таблица командПредварительная подготовкаНеобходимые компонентыRBAC-проверкиПроверка внешних родителей (qa)Статические проверкиПошаговая инструкция по развёртываниюШаг 1. Проверка конфигурацииШаг 2. Аутентификация в реестре образовШаг 3. РазвёртываниеРазвёртывание среды выполнения без тестовых данныхРазвёртывание только Платформы ИИ с тестовыми даннымиПолное развёртывание тестового стендаСценарий развёртывания RC только через HelmСостав поставкиПорядок установкиIdentity bootstrap без GardenПроверка конфигурацииПроверка развёртыванияПроверка подовПроверка готовности компонентов (qa)Публичные проверки HTTP (qa)ОбновлениеОткат и очисткаОткатОчисткаЗавершение работы (dev-local)БезопасностьПравила работы в средеУчётные данные и секретыДоверие при сборкеУправление KeycloakСеть и проверка идентификацииТестовые данныеУстранение неполадокПоды не переходят в состояние RunningЗанятые портыОшибка аутентификации реестраОшибка миграции базы данныхФикстурыФикстуры пользователейФикстуры агентовМатериалы для фиксации результата