---
doc_id: REF-CK8S-0021
type: runtime-model
title: "kodex — каноника runtime, deploy и bootstrap в wave 6"
status: active
owner_role: SRE
created_at: 2026-04-25
updated_at: 2026-04-25
related_issues: [470, 488, 586]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-25-refactoring-wave6"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-25
---

# Каноника runtime, deploy и bootstrap в wave 6

## TL;DR
- Wave 6 фиксирует не реализацию конкретных Kubernetes-манифестов, а канонический рабочий контур новой платформы.
- `runtime-manager` остаётся владельцем слотов, platform `job`, prewarm/reuse, build/deploy/mirror/cleanup и технического статуса среды.
- `worker` и `agent-runner` являются исполнителями runtime-решений, но не владельцами runtime-истины.
- Первый production-контур по-прежнему стартует с одного сервера и одного Kubernetes-кластера, но документация и код не должны зацементировать эту топологию как единственно возможную.
- Bootstrap новой платформы должен сразу загружать встроенные flow, роли, шаблоны промптов и системные пакеты как установочные фикстуры, после чего каноника живёт в БД owner-сервисов.
- Платформа не хранит полные build/deploy logs и не заводит собственную сущность образа; она хранит только platform state, короткий хвост логов и ссылки на первоисточник.
- До старта кодовых волн после wave 6 все runtime-, deploy- и bootstrap-решения должны считаться зафиксированными на уровне терминов, владения, последовательности и критериев выхода.

## 1. Зачем нужна отдельная runtime-волна
В предыдущих волнах уже были зафиксированы:
- продуктовая модель;
- owner-сервисы и их границы;
- модель данных и provider-native работа;
- release governance и операторский UX;
- пакетная платформа, tenancy, fleet, billing и заделы под automation.

Этого недостаточно для начала реализации, потому что без отдельной runtime-каноники быстро возникнут архитектурные расхождения:
- `agent-manager` начнёт притягивать к себе slot и deploy-логику;
- `worker` или `agent-runner` начнут выглядеть владельцами runtime-состояния;
- первый deploy превратится в набор ad-hoc shell-скриптов без явного ownership;
- одноузловая стартовая конфигурация случайно станет архитектурным пределом платформы.

Wave 6 нужна, чтобы зафиксировать:
1. канонические runtime-контуры;
2. порядок bootstrap и deploy;
3. модель первого production-развёртывания;
4. границу между временным физическим объединением сервисов и постоянным логическим владением;
5. критерии выхода к кодовым волнам.

## 2. Что именно фиксирует wave 6

### 2.1. Входит в scope
Wave 6 фиксирует:
- терминологию и границы runtime-контура;
- канонические типы runtime-режимов;
- модель слота и его reuse;
- модель platform `job`;
- состав workspace и materialization policy;
- bootstrap-порядок owner-сервисов и встроенных фикстур;
- deploy-модель для candidate и production;
- стартовую физическую топологию первой версии;
- ограничения первой реально разворачиваемой версии;
- требования к observability, retention и housekeeping;
- gate перехода к первой кодовой доменной волне.

### 2.2. Не входит в scope
Wave 6 не фиксирует:
- конкретный Helm/Kustomize/tooling stack;
- конкретные Kubernetes manifests и конечные значения env;
- окончательный перечень CI-команд и низкоуровневых bash-скриптов;
- физическое извлечение старого `control-plane` в коде;
- production-ready набор графиков, дашбордов и алертов по каждому сервису.

Это сделано намеренно: wave 6 задаёт канонику, по которой потом делаются компактные кодовые PR.

## 3. Базовые принципы runtime-контура

### 3.1. Kubernetes-only и fleet-first
Платформа остаётся Kubernetes-only.

Это значит:
- любой runtime-контур живёт на кластере, зарегистрированном во `fleet-manager`;
- `runtime-manager` не выбирает инфраструктуру сам по себе, а исполняет решение placement policy;
- локальные shell-first сценарии могут существовать только как технический способ bootstrap, но не как каноническая рабочая модель.

### 3.2. Один slot — один изолированный контур исполнения
Slot остаётся базовой единицей изоляции агентной работы.

В первой версии:
- slot = отдельный namespace задачи;
- namespace может содержать только pod агента и минимальный контур, если это `code-only`;
- namespace может содержать развёрнутое окружение проекта, если это `full-env`.

В дальнейшем допускается расширение до `nested cluster`, но:
- доменная модель slot не должна зависеть от того, namespace это или cluster;
- API и БД не должны зашивать `namespace-only` как вечную форму.

### 3.2.1. Прогретые слоты
Wave 6 отдельно фиксирует поддержку прогретых slot.

Прогретый slot:
- заранее создан на нужном кластере и в нужном runtime-профиле;
- уже содержит базовый toolchain, базовые секретные привязки и подготовленный контур исполнения;
- ещё не привязан к конкретной задаче, ветке или набору артефактов.

Owner или policy платформы должны уметь задавать:
- для каких проектов и контуров нужен прогрев;
- сколько прогретых slot держать;
- для каких runtime-профилей и ролей они допустимы;
- на каких кластерах и в каких пулах размещения они поддерживаются.

При назначении задачи платформа:
1. берёт подходящий прогретый slot из пула;
2. materialize'ит в нём workspace под конкретный проект, ветку и набор источников;
3. только после этого запускает pod с агентом.

Если свободного прогретого slot нет, платформа делает обычный cold start, но:
- это должно быть видно оператору;
- нехватка прогретых slot должна становиться входом для tuning policy, а не скрытым деградирующим режимом.

### 3.3. Runtime mode задаётся профилем роли и stage policy
Канонические режимы первой версии:
- `code-only`;
- `full-env`;
- reuse существующего slot;
- production только для чтения.

Режим определяется не желанием агента, а:
- профилем роли;
- `stage role binding`;
- risk policy;
- release policy;
- placement policy проекта и репозитория.

### 3.4. Workspace materialization — часть runtime, а не ad-hoc prep step
Агент должен работать не только с кодом, но и со всем разрешённым локальным набором источников:
- кодовые репозитории;
- проектная документация по `services.yaml`;
- пакеты руководящей документации;
- временные runtime-файлы;
- отрендеренный платформой контекст flow, роли, acceptance и policy.

Каноническое правило:
- flow, роли и шаблоны промптов не кладутся в workspace как источник истины;
- в workspace попадает только отрендеренный execution context;
- owner-версии flow, ролей и шаблонов остаются в БД.

### 3.5. Reuse slot допускается только по детерминированному отпечатку
Переиспользование slot не может быть эвристикой.

Оно допускается только если совпадают:
- immutably resolved build ref;
- runtime fingerprint;
- набор materialized sources;
- отрендеренный policy-контур исполнения;
- отсутствие активного конфликтующего deploy или cleanup;
- корректный рабочий статус самого namespace.

Если хотя бы одно условие не выполняется, платформа обязана:
- обновить или пересобрать runtime-контур;
- при необходимости заново materialize workspace;
- заново выполнить platform `job`, которые нужны для безопасного старта.

### 3.6. Platform `job` — техническое состояние под владельцем домена
Build, mirror, deploy, cleanup, retention, health-check и bootstrap-задачи считаются platform `job`.

Канонический владелец их состояния:
- `runtime-manager`.

`worker`:
- берёт такие задачи в исполнение;
- делает retries и reconciliation;
- не становится владельцем конечного runtime-статуса.

`agent-runner`:
- исполняет ролевого агента внутри уже подготовленного runtime;
- не определяет сам, нужен ли новый slot, новый deploy, mirror или cleanup.

### 3.7. Логи и внешние технические объекты не дублируются
Wave 6 закрепляет:
- registry остаётся владельцем образов;
- Kubernetes остаётся владельцем pod/job/deployment state и полных контейнерных логов;
- PostgreSQL хранит краткий platform state, короткий хвост лога и ссылку на первоисточник.

Это обязательное ограничение:
- не писать полные build/deploy логи в БД;
- не создавать внутреннюю сущность image как ещё один owner-домен;
- не хранить дубликаты cluster events без явной цели и retention policy.

## 4. Канонические runtime-контуры и их ownership

| Контур | Владелец | Что считается истиной | Что намеренно не принадлежит контуру |
|---|---|---|---|
| Placement и доступность кластеров | `fleet-manager` | серверы, кластеры, connectivity, placement policy | slot state, run state, provider state |
| Slot и platform `job` | `runtime-manager` | slot lifecycle, reuse, prewarm, build/deploy/mirror/cleanup, runtime status | пользовательское намерение, flow semantics, provider-native review |
| Очереди исполнения и reconciliation | `worker` | техническое исполнение взятой задачи и попыток | каноническое решение, нужен ли slot или deploy |
| Выполнение ролевого агента | `agent-runner` | lifecycle конкретной агентной сессии внутри выделенного runtime | runtime ownership, provider-native truth, flow truth |
| Flow/run/prompt orchestration | `agent-manager` | run, stage transitions, role selection, wait states, acceptance | slot topology, build/deploy status |
| Platform MCP access | `platform-mcp-server` | policy-aware инструментальная поверхность | чужая доменная истина |

Из этой таблицы следует жёсткое правило:
- никакая реализация wave 7+ не должна снова собирать slot, deploy и flow в одном сервисе.

## 5. Стартовая физическая топология первой версии

### 5.1. Что допускается в первой реально разворачиваемой версии
На старте допускается:
- один основной сервер платформы;
- один основной Kubernetes-кластер платформы;
- один production-контур самой платформы;
- owner-организация и клиентские организации;
- один основной registry-контур;
- один основной Postgres-контур;
- минимальный набор встроенных flow и ролей.

Но уже в этой версии должны быть видны заделы для:
- нескольких серверов;
- нескольких кластеров;
- нескольких организаций;
- нескольких provider accounts;
- нескольких package sources;
- нескольких runtime placement policy.

При этом wave 6 сразу закрепляет более широкую целевую модель:
- платформа управляет не только своим собственным production-контуром;
- разрабатываемые через платформу проекты могут деплоиться в namespace того же кластера или в другие управляемые кластеры и серверы;
- для `sre`/`ops` и сходных ролей должен существовать read-only доступ к целевым производственным контурам проектов по policy;
- основной сервер и основной кластер платформы с первой же итерации должны регистрироваться как объекты fleet-каталога, а не существовать как неявное знание "того самого" окружения.

### 5.2. Канонические namespace-контуры
Для первой версии фиксируются четыре класса namespace:
1. системный namespace платформы;
2. production namespace платформы;
3. slot namespaces.
4. управляемые namespace целевых стадий и production-контуров проектов.

Смысл:
- системный namespace держит общие служебные части, которые не должны жить в каждом slot;
- production namespace держит owner-сервисы, edge и UI новой версии;
- slot namespaces остаются отдельным контуром исполнения задачи.
- управляемые namespace целевых контуров держат staging, preprod, prod и другие рабочие среды разрабатываемых проектов, если policy размещает их в этом же кластере.

Для самой платформы это тоже оставляет место под отдельный staging-контур:
- либо как специальный управляемый namespace;
- либо как отдельный candidate runtime-контур по policy.

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

### 5.3. Инфраструктурный базовый слой первой версии
Первый production-контур должен иметь как минимум:
- ingress и TLS-контур;
- PostgreSQL-контур с logical `database-per-service`;
- доступ к registry;
- storage policy для runtime и временных файлов;
- минимальный контур наблюдаемости для health, readiness, metrics и короткой runtime-диагностики;
- secret injection из внешнего bootstrap-контура.

Если включаются голос и временные медиа:
- нужен отдельный контур хранения временных бинарных объектов;
- эти объекты не должны становиться частью PostgreSQL как постоянного blob-хранилища.

Wave 6 дополнительно фиксирует обязательные shared-seams базового слоя:
- объектное хранилище обязательно для голоса и временных медиа;
- Vault становится каноническим хранилищем секретов платформы, platform-managed workloads и зависимостей платформы, а env используется только как bootstrap-вход в этот контур;
- проектные workloads могут использовать и другие внешние хранилища секретов, включая собственный Vault проекта, если это допускают policy проекта, placement policy и контур целевого кластера;
- SSO с 2FA становится каноническим access-контуром для непубличных поверхностей платформы и управляемых служебных контуров;
- owner-сервисы работают по модели `database-per-service`; даже если физически используют одну PostgreSQL-инсталляцию, между таблицами разных owner-сервисов не используются `FOREIGN KEY`, cross-database join и каскадные операции как нормальный режим;
- гарантированная доставка доменных событий в первой версии обеспечивается не через Kafka по умолчанию, а через transactional outbox/inbox, идемпотентных потребителей и owner-controlled retries;
- Redis и Kafka не считаются обязательным baseline wave 6: они остаются допустимыми расширениями, если позже появится конкретный подтверждённый сценарий, который нельзя надёжно закрыть owner-БД, outbox/inbox и lease-моделью.

### 5.4. Допустимое временное физическое объединение
Первая кодовая реализация может временно развернуть меньше физических сервисных единиц, чем целевая карта owner-сервисов.

Это допустимо только при одновременном соблюдении всех условий:
- логическое владение уже соответствует owner-модели;
- БД и контракты не смешивают чужие домены;
- временный сервис не становится новым постоянным `control-plane`;
- у временного объединения есть явный план последующего извлечения.

То есть допустима тонкая оболочка или временное объединение процесса, но недопустим возврат к старой монолитной истине.

### 5.5. Правило новой реализации против legacy-кода
Wave 6 отдельно закрепляет правило перехода от старой версии к новой:
- новый код пишется только в новых сервисах и новых каталогах под целевую архитектуру;
- переписывать старые сервисы "по месту" запрещено;
- старые сервисы могут быть временно перенесены в `deprecated/**` как историческая шпаргалка;
- код из `deprecated/**` не должен участвовать в активном build/deploy graph новой версии;
- к моменту первого deploy новой платформы старые редакции сервисов должны быть выведены из активного дерева исполнения.

## 6. Канонический deploy-маршрут

### 6.1. Общий принцип
Deploy — это не один непрозрачный шаг, а связанный маршрут platform `job`:
1. подготовка источников и зависимостей;
2. mirror или fetch там, где это требуется policy;
3. build;
4. publish;
5. deploy;
6. smoke и postdeploy-observation;
7. cleanup или follow-up.

Каждый шаг должен быть виден как отдельный технический статус или как отдельная `job`, если этого требует операционный смысл.

### 6.2. Candidate и production
Wave 6 закрепляет два разных deploy-класса:
- candidate deploy для `full-env` и release-подготовки;
- production deploy для реальной выкладки.

Candidate deploy:
- не должен silently превращаться в production;
- может жить в slot-контуре;
- используется для `run:dev`, `run:qa`, `run:release`.

Production deploy:
- идёт в production namespace или иного production-target, выбранного placement policy;
- проходит через release gates и postdeploy governance;
- не считается завершённым на зелёном deploy-шаге.

### 6.3. Порядок выкладки owner-сервисов
Канонический порядок остаётся таким:
1. shared dependencies;
2. migrations по owner-базам;
3. internal owner-services;
4. edge services;
5. frontend.

Это относится и к новой платформе.

Если сервис не имеет своей БД, это не даёт права нарушать зависимостной порядок для остальных.

Базовый порядок может дополнительно уточняться:
- зависимостями из `services.yaml`;
- политикой release line;
- placement policy целевого кластера и namespace.

Для production-deploy wave 6 сразу закрепляет ещё одно правило:
- если от сервиса ожидается сохранение доступности во время выкладки, policy не должна опускаться ниже двух реплик;
- для ключевых edge/core сервисов целевое baseline-значение первой версии — три реплики;
- rollout должен уметь выкатывать новые версии по одной реплике, не разрушая доступность целевого контура.

### 6.4. Deploy не строится на GitHub Actions как основном механизме
Даже если технически в каких-то местах используется внешняя automation, каноническая модель остаётся такой:
- build/deploy выполняются как platform-managed операции;
- источником статуса для платформы являются owner-сервисы и Kubernetes;
- GitHub Actions не становятся главным execution backbone новой версии.

## 7. Bootstrap-модель новой платформы

### 7.1. Bootstrap делится на четыре уровня
Канонический порядок bootstrap:
1. базовый слой хоста и кластера;
2. базовый инфраструктурный слой платформы;
3. owner-services bootstrap;
4. seed bootstrap встроенных объектов.

Такое разделение нужно, чтобы:
- не смешивать подготовку хоста и логическую инициализацию домена;
- не подменять domain seed обычным runtime-deploy;
- иметь явную точку повторяемого переустановочного bootstrap.

### 7.2. Базовый слой хоста и кластера
На этом уровне подготавливаются:
- сам сервер или серверы;
- Kubernetes-кластер;
- доступы администратора;
- ingress/TLS basis;
- storage basis;
- registry access;
- минимальный контур наблюдаемости.

Этот уровень не должен знать о flow, ролях, проектах и provider-аккаунтах как о доменных объектах платформы.

### 7.3. Базовый инфраструктурный слой платформы
На этом уровне подготавливаются:
- production namespace и системный namespace;
- PostgreSQL и owner-базы;
- базовые secret bindings;
- служебные зависимости, без которых owner-сервисы не стартуют.

### 7.4. Owner-services bootstrap
На этом уровне:
- применяются миграции owner-сервисов;
- поднимаются owner-сервисы;
- поднимаются edge и UI;
- выполняются readiness-check и минимальная операционная проверка.

### 7.5. Seed bootstrap встроенных объектов
После старта owner-сервисов выполняется отдельная seed-инициализация:
- owner-организации;
- встроенных flow;
- встроенных ролей;
- встроенных шаблонов промптов;
- системных package entries;
- базовых policy и системных настроек.

Канонический источник для этого уровня:
- установочные фикстуры репозитория платформы.

После загрузки:
- owner-версии живут в БД;
- дальнейшая работа идёт уже через owner-сервисы и UI;
- репозиторий не читается как runtime source of truth на каждом запуске агента.

## 8. Operational minimum первой версии

### 8.1. Что должно быть видно оператору с самого начала
Даже первая реально развёртываемая версия обязана показывать:
- status owner-сервисов;
- status platform `job`;
- status slot и candidate deploy;
- блокирующие ошибки bootstrap;
- проблемы housekeeping и retention;
- запросы human gate;
- ссылку на первоисточник логов и короткий хвост логов.

### 8.2. Что не должно делаться вручную через ad-hoc shell как нормальный режим
Недопустимо считать нормой:
- ручное создание provider metadata в обход owner-сервиса;
- ручной запуск постоянных runtime-сценариев напрямую через `kubectl exec`;
- ручное редактирование production state внутри pod как часть рабочей процедуры;
- скрытый bootstrap, который нельзя воспроизвести заново по документированной последовательности.

### 8.3. Housekeeping обязателен уже в первой версии
Очистка устаревших slot, временных файлов и иные retention-задачи не откладываются на потом.

Даже если policy первой версии очень простая, она обязана:
- существовать;
- исполняться как platform `job`;
- быть видимой оператору;
- поднимать сигнал при сбое.

Оператор должен видеть не только факт успеха или ошибки, но и итог очистки:
- сколько slot, namespace, временных объектов и иных единиц было очищено;
- сколько операций было пропущено и почему;
- сколько операций завершилось с ошибкой;
- какую оценку освобождённого объёма или количества объектов вернул cleanup-контур;
- какие внешние cleanup-действия были вызваны во внешних системах, если сама платформа не является владельцем этих сущностей.

## 9. Что wave 6 требует от следующих волн
После принятия этого документа каждая кодовая волна обязана:
- ссылаться на runtime ownership из wave 6;
- не смешивать slot/build/deploy/cleanup с flow/run ownership;
- не зашивать single-cluster и single-org как вечные предположения;
- не превращать установочные фикстуры в runtime-истину;
- не писать полный технический лог в PostgreSQL;
- не возвращать старую модель `control-plane` как монолитного владельца;
- не писать новую логику "поверх" старых сервисов по месту вместо создания новых owner-сервисов.

Если для практической реализации потребуется временный шов, он должен быть:
- явно ограничен;
- описан как временный;
- связан с конкретной последующей extraction-волной.
