Control Plane

Назначение и область применения

Настоящее руководство определяет порядок настройки, сопровождения и проверки компонента Control Plane Платформы ИИ в контуре заказчика. Документ предназначен для администратора платформы и предполагает владение основами администрирования Linux, Kubernetes, Helm и HTTP API.

Control Plane — центральный управляющий компонент Платформы ИИ. Он предоставляет versioned management API для управления политиками моделей, виртуальными ключами LLM и публикацией low-code агентов. Компонент владеет desired state (желаемым состоянием) и длительными операциями (durable operations), но не участвует в путях инференса LLM и вызова агентов (A2A invocation).

Platform API Gateway (api-gw) монтирует Control Plane по пути /control-plane: публичное API доступно как /control-plane/api/v1, документация — как /control-plane/docs. Agent Registry смонтирован независимо — под /agent-registry.

Функция «Активность и потребление» добавляет аналитику LLM-запросов и HTTP-запросов к агентам. Доставка событий, отдельные права, постоянная очередь, сроки хранения и безопасный откат описаны в руководстве по эксплуатации активности и потребления. Её итоговая нагрузочная квалификация AU-I05 ещё не завершена.

Важно: Все изменяющие состояние операции асинхронные. Запрос возвращает 202 Accepted с ссылкой на Operation — это подтверждение принятия намерения, а не факта выполнения. Фактическое применение отслеживается через verifiedState ресурса и GET /api/v1/operations/{operationId}.

Термины и сокращения

1. Архитектура

1.1. Общая схема

Control Plane состоит из прикладного API, фоновых воркеров оркестрации и транзакционной базы данных. Управление внешними ресурсами (Kubernetes, LLM Gateway, Agent Registry) выполняется асинхронно через детерминированных reconciler'ов.

1.2. Состав компонентов

Kubernetes, LLM Gateway и Agent Registry — наблюдаемые внешние системы. Control Plane не является их синхронной зависимостью для LLM inference или A2A invocation.

1.3. Границы доверия

2. Бизнес-сущности

Сущности сгруппированы по логическим областям: управление моделями, управление ключами, публикация агентов. Все объекты создаются Администратором Платформы через management API, за исключением ресурсов самообслуживания (/api/v1/me/*).

2.1. Управление моделями

Tier (Уровень)

Профиль качества обслуживания для каждого API ключа. Определяет лимит скорости (запросы в минуту) и квоту (токены в минуту). Tier не имеет членов, владельцев или унаследованных прав.

Важные особенности:

• Все мутации (POST/PATCH/DELETE) асинхронные: возвращают 202 Accepted — это не подтверждённый успех; фактическое применение отслеживается через verifiedState и /api/v1/operations.
• PATCH/DELETE требуют точный If-Match (формат "r<revision>"), иначе 412 PreconditionFailed.
• Удаление возможно только для неиспользуемого уровня (проверка зависимостей: ключи, политики), иначе 409 Conflict.

Provider (Поставщик)

Конфигурация внешнего LLM-провайдера (например, OpenAI, Anthropic). Включает адаптер, конечную точку, привязку учётных данных и состояние. Сырые учётные данные хранятся только как зашифрованная строка в базе данных Control Plane; компонент не разворачивает вычислительные ресурсы провайдера.

Замечание: креды провайдера нельзя удалить. Провайдер может быть создан без связанных кредов; добавление кредов — v1/providers/{providerId}/credential.

Model (Модель)

Конкретная модель с глобально уникальным именем, привязкой к провайдеру и профилем (внутренний или внешний). Наличие модели не подразумевает автоматического права доступа; права выдаются только через явные привязки к API ключам.

Важные особенности:

• gatewayName и providerId неизменяемы: в схему обновления входят только upstreamModel, profile и desiredState. Сменить «внутреннее» имя модели нельзя — можно сменить модель, на которую ссылается запись (upstreamModel).
• Удаление возможно только когда модель не требуется активными ключами или маршрутами, иначе 409 Conflict.
• Массовое изменение состояния модели поддерживается через bulk-операции (set_model_state в /api/v1/bulk/previews → :execute).

Замечание: параметр displayName Tier может быть пустым, тогда как во многих местах интерфейса отображается не кодовое имя, а человекочитаемое. Рекомендуется всегда заполнять displayName при создании уровня.

2.2. Управление ключами

KeyIssuancePolicy (Политика выдачи ключей)

Настройка, определяющая условия самообслуживающейся выдачи ключей для людей и сервисов. Singleton — единичный объект на всю установку. Изменение политики влияет только на будущие выдачи и не изменяет ранее выданные ключи.

Имеет состояния verifiedState: pending, enabled, disabled, degraded.

Методы:

ApiKey (Ключ API)

Виртуальный ключ доступа к LLM. Имеет одного владельца (человек, сервис или агент), привязку к уровню и непустой набор разрешённых моделей. Ключ создаётся через защищённую транзакцию: идентификатор операции подтверждается сервисом авторизации (SpiceDB), а сам ключ верифицируется Gateway перед тем, как платформа вернёт секретный материал (возвращается один раз).

Важные особенности:

• Секретный материал ключа (oneTimeSecret, формат cpk_<base64url>) возвращается только один раз при создании или ротации (статусы 201/200 с заголовком Idempotency-Replayed: false). При идемпотентной повторной отправке того же Idempotency-Key возвращается только метаданные.
• Ключи, принадлежащие агенту (owner.type = "agent"), нельзя обновлять, ротировать или отзывать через административные методы — их жизненный цикл управляется публикацией агента (publish/unpublish/rollback/revalidate). Попытка приводит к 409 Conflict с кодом agent_key_lifecycle_owned_by_publication.
• При отзыве (revoke) ключ верифицируется через Gateway — если Gateway не отвечает в течение таймаута, возвращается 504 VerificationTimeout.
• Каждая операция создания/ротации/отзыва создаёт Operation, на которую ссылается operationLink.

2.3. Публикация агентов

Agent (Агент)

Сущность, представляющая low-code агента. Имеет стабильный идентификатор, выдаваемый издателем, и изменяемые метаданные (имя, отображаемое имя, описание). Может иметь ровно одного прямого владельца (человек или сервис) или не иметь владельца вовсе. Жёсткое удаление агентов не предусмотрено — удаление заменяется unpublish.

AgentVersion (Версия агента)

Неизменяемая версия агента с SemVer, исходным артефактом и хэшами политик. Любое изменение неизменяемых данных создаёт новую версию. Версия замораживает допустимый набор моделей, уровень и ревизию политики публикации.

Важно: llmRequired, modelIds и tierId — выводимые, а не задаваемые поля. Их значение определяется сервером на основе AgentPublicationPolicy и low-code источника; передача их в запросе создания отклоняется с ошибкой 400 InvalidRequest.

LowCodeSource — ссылка на низкоуровневый источник агента:

Источники Source не содержат секретов, ключей, путей к Kubernetes, токенов или внутренних адресов. Прямая загрузка в OCI, Kubernetes или Agent Registry запрещена.

AgentPublicationPolicy (Политика публикации агентов)

Единичный установочный синглтон, задающий допустимый уровень (Tier) и набор моделей (не более 256) для новых версий агентов. Замораживается при создании версии; последующие изменения не действуют задним числом.

Выключенная или недоступная политика блокирует создание новых LLM-версий, но не влияет на уже активные версии.

Publication (Публикация)

Привязка агента к конкретной версии в рамках окружения. Окружение берётся из доверенной конфигурации установки, а не из команды управления.

PublishJob (Задача публикации)

Длительный рабочий процесс жизненного цикла публикации: фазы, наблюдения, повторные попытки, компенсации и терминальный результат. Каждая команда управления создаёт ровно одну задачу с уникальным operation_id.

Фазы publish: accepted → validating_source → allocating_identity → freezing_version → provisioning_candidate_credential → rendering_candidate → applying_candidate → verifying_workload → verifying_route → selecting_candidate → completed

Фазы unpublish: withdrawing_route → awaiting_registry_withheld → revoking_credential → deleting_workload

Состояния публикации:

Состояния задачи (Job.state): queued (в очереди), running (выполняется), retry_wait (ожидание повтора), compensating (выполняется компенсация), succeeded, failed, cancelled.

3. Типовые сценарии администратора

3.1. Настройка провайдера и моделей

Роль: Администратор Платформы

Результат: Платформа готова к работе с подключёнными провайдерами.

3.2. Настройка политики выдачи ключей

Роль: Администратор Платформы

Результат: Пользователи и сервисы самостоятельно выпускают ключи в рамках заданных ограничений через POST /api/v1/me/keys. Выдача не затрагивает ранее выданные ключи.

3.3. Выдача ключа администратором

Роль: Администратор Платформы

Результат: Субъект получает ключ; полный аудит-трейл выдачи доступен администратору.

3.4. Управление ключами

Роль: Администратор Платформы

Ключи с владельцем-агентом не управляются через административные методы — их жизненный цикл принадлежит публикации агента.

3.5. Создание и публикация агента

Роль: Пользователь (человек или сервис) с правом control_plane#publish

Публикация инициируется из Low-code IDE: провайдер agent-platform экспортирует проверенную версию потока и вызывает Control Plane через api-gw от имени пользователя. Прямые вызовы Control Plane пользователем не предусмотрены.

Признаки успешной публикации:

• 202 Accepted — операция принята, а не завершена;
• финальная готовность — publicationState = active в статусе публикации;
• статус операции в GET /api/v1/operations/{operationId} — succeeded.

3.6. Настройка политики публикации

Роль: Администратор Платформы

4. Жизненный цикл публикации

4.1. Команды

Причина unpublish (reasonCode): user_requested, security_response, source_retired, operational. Триггер revalidate: scope_restored, operator_recovery, provider_recovered.

4.2. Гейты валидации

Статус публикации содержит 15 строго определённых гейтов. Гейт passed означает, что внешняя система (Registry, Gateway, Admission Controller) подтвердила факт, а не просто запись в базе данных. Статусы гейтов: pending, passed, failed, not_applicable. Агент становится active только после прохождения всех применимых гейтов.

Состояния degraded и suspended возникают, если один или несколько гейтов failed или pending.

4.3. Наблюдения от Agent Registry

Agent Registry — независимая система; его состояние является источником истины для валидации гейтов публикации.

При отсутствии наблюдения операция ещё не завершена — ожидается ответ Registry.

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

5.1. Хранение секретов

Сырые учётные данные провайдеров никогда не покидают зашифрованное хранилище Control Plane.

Важно: Не помещайте значение токена, сырой ключ, учётные данные провайдера или внутренний адрес в запрос, лог или сообщение об ошибке.

5.2. Авторизация

Модель «ресурс — право» Control Plane:

Защитные гейты авторизации:

• Operation requester gate — новая Operation скрыта и не может стартовать до подтверждения operation:{operationId}#requester через SpiceDB;
• Owner transfer gate — при смене владельца Registry атомарно заменяет старый кортеж agent#owner;
• Agent-owned key lifecycle — ключи агента не изменяются через административное API;
• любой недействительный или неизвестный результат авторизации обрабатывается как отказ (fail-closed).

5.3. Идемпотентность и контроль версий

• Заголовок Idempotency-Key (16–128 символов, ^[A-Za-z0-9._~-]+$) обязателен для всех write-операций.
• Заголовок If-Match (ETag вида "r<revision>") обязателен для PATCH и DELETE.
• Повтор с тем же ключом и тем же каноническим дайджестом возвращает оригинальный результат; другой дайджест — 409 Conflict (idempotency_conflict).

6. Мониторинг и диагностика

6.1. Проверка состояния

# Поды, развёртывания и сервисы
kubectl -n "$CP_NAMESPACE" get deploy,pod,svc

# Журналы API и воркеров
kubectl -n "$CP_NAMESPACE" logs deploy/ap-control-plane-api --all-pods --tail=200
kubectl -n "$CP_NAMESPACE" logs deploy/ap-control-plane-model-reconciler --all-pods --tail=200
kubectl -n "$CP_NAMESPACE" logs deploy/ap-control-plane-key-reconciler --all-pods --tail=200
kubectl -n "$CP_NAMESPACE" logs deploy/ap-control-plane-publisher --all-pods --tail=200

# События
kubectl -n "$CP_NAMESPACE" get events --sort-by=.lastTimestamp

Диагностику операции: GET /api/v1/operations/{operationId}; диагностику публикации: GET /api/v1/agents/{agentId}/status.

6.2. Типовые нарушения

7. Восстановление

7.1. Цели восстановления

Сопоставимые цели Agent Registry — RTO 60 минут, RPO 5 минут.

7.2. Восстановление после отказа

1. Развернуть ту же версию компонента с прежними секретами и конфигурацией.
2. Восстановить PostgreSQL из резервной копии (схема control_plane).
3. Проверить доступность Temporal namespace control-plane.
4. Запустить API и воркеры; проверить статус операций.
5. Проверить публичное API или список ресурсов.

7.3. Крах воркера

Temporal автоматически перезапускает Workflow из истории. Ручное вмешательство не требуется:

1. Проверить, что Temporal namespace доступен.
2. Проверить логи воркера на повторяющиеся ошибки.
3. Если Workflow завис — проверить права RBAC и доступ к внешним системам (Kubernetes, Gateway, Registry).
4. Для согласованного ручного продолжения использовать preview → execute Recovery API.

7.4. Recovery API

Для согласованного ручного продолжения после дрейфа или отказа внешнего ресурса:

1. Preview — получить ограниченный инвентарь и observe-only классификацию.
2. Execute — выполнить согласованное продолжение с подтверждением области воздействия.

Recovery API не угадывает владельца, не выполняет автоматическое принятие и не допускает широкой очистки.

7.5. Миграции базы данных

Задание миграции и проверка при запуске используют транзакционную блокировку PostgreSQL. При ошибке:

1. Остановить развёртывание версии.
2. Сохранить номер миграции (Alembic) и ошибку базы.
3. Вернуть совместимый образ приложения.
4. Понижение версии схемы выполнять только после проверки сохранности данных.
5. Не запускать разрушительный SQL из интерактивного контейнера.

8. Сводные таблицы API

Базовый путь: /control-plane/api/v1. Аутентификация — Bearer-токен.

Управление моделями и ключами

Самообслуживание (me)

Публикация агентов

Операции

Коды ответов

Известные ограничения

• Учётные данные провайдера нельзя удалить (провайдер может быть создан без них).
• «Внутреннее» имя модели (gatewayName) неизменяемо — можно сменить только upstreamModel.
• Пустое displayName уровня отображается пустым в интерфейсе — заполняйте его при создании.
• Жёсткое удаление агентов не предусмотрено — используйте unpublish.
• Изменяемые Flow.data не публикуются; неизвестный или изменённый компонент отклоняется с ошибкой.
• Прямая загрузка в OCI, Kubernetes или Agent Registry запрещена.