110 lines
9.4 KiB
Markdown
110 lines
9.4 KiB
Markdown
# BRD — ORCH-36: Исполняемый самодеплой (стадия deploy дёргает хост-хук, Вариант B)
|
||
|
||
Work Item: ORCH-036
|
||
Stage: analysis
|
||
Автор: analyst
|
||
Дата: 2026-06-06
|
||
|
||
## 1. Контекст и проблема
|
||
|
||
Стадия `deploy` конвейера сейчас **«бумажная»**. На ней deployer-агент (LLM) только
|
||
пишет `docs/work-items/<wi>/14-deploy-log.md` с `deploy_status: SUCCESS|FAILED`, а QG
|
||
`check_deploy_status` (`src/qg/checks.py:464`) парсит этот вердикт и пускает `deploy → done`.
|
||
**Реального docker-деплоя нет** — продакшен орка катается руками (Стрим).
|
||
|
||
Хост-хук `scripts/orchestrator-deploy-hook.sh` **уже существует** (ORCH-34) и умеет:
|
||
захват PREV_IMG → `git pull` → рестарт сервиса → health-check (10×6с = 60с) →
|
||
авто-rollback при провале health, с корректным exit-code. Дефолты — STAGING-безопасные;
|
||
прод включается через override env (`TARGET_SERVICE`, `TARGET_PORT`, `TARGET_IMAGE`,
|
||
`COMPOSE_PROFILE`).
|
||
|
||
**Главная мина (self-hosting):** прод-контейнер `orchestrator` (8500) — ОДИН на все
|
||
проекты, и в нём же бежит сам deployer-агент. Deployer не может синхронно рестартить
|
||
контейнер, в котором живёт (`docker compose up -d orchestrator` убьёт его процесс на
|
||
середине). Реальный рестарт self-репо обязан делать ВНЕШНИЙ хост-хук (вне контейнера),
|
||
который срабатывает ПОСЛЕ выхода агента. Рубильник — снаружи; орк только ИНИЦИИРУЕТ.
|
||
|
||
## 2. Цель
|
||
|
||
Превратить стадию `deploy` в РЕАЛЬНЫЙ самодеплой: после зелёного `deploy-staging`-гейта
|
||
конвейер вызывает хост-хук с прод-параметрами, хук промоутит образ в прод (8500) с
|
||
health-чеком и авто-rollback. Результат хука (exit-code) маппится в `deploy_status`.
|
||
**На старте — с ОБЯЗАТЕЛЬНЫМ ручным approve** (`DEPLOY_REQUIRE_MANUAL_APPROVE=true`):
|
||
прод не трогается без явного «go» Владельца.
|
||
|
||
## 3. Ценность для бизнеса
|
||
|
||
- Уходит последний ручной шаг конвейера (прод-деплой Стрим) → шаг к автономному внедрению (эпик ORCH-54).
|
||
- `deploy_status: SUCCESS` становится **доказанным** (реальный health-ok), а не декларацией LLM.
|
||
- Гарантия build-once: «что протестировали на staging — то и в проде» (тот же образ, без пересборки).
|
||
- Прод никогда не остаётся в нерабочем состоянии: авто-rollback + health-таймаут.
|
||
|
||
## 4. Заинтересованные стороны
|
||
|
||
| Роль | Интерес |
|
||
|------|---------|
|
||
| Владелец (Слава/Стрим) | Контроль через ручной approve; уведомления о каждом промоуте/откате |
|
||
| Проект enduro-trails | Прод-орк не должен падать (общий инстанс) — групповой риск |
|
||
| Конвейер ORCH | Стадия `deploy` исполняемая, гейты не сломаны |
|
||
|
||
## 5. Объём (scope)
|
||
|
||
### В объёме
|
||
1. Исполнение реального прод-деплоя из стадии `deploy` через хост-хук (ssh / detached на хосте).
|
||
2. Обязательный ручной approve-гейт ПОСЛЕ зелёного staging и ДО прод-рестарта (флаг включён).
|
||
3. Маппинг exit-code хука → `deploy_status: SUCCESS|FAILED` (реальный, не бумажный).
|
||
4. Уведомления (Plane-коммент + Telegram) на каждый промоут и откат.
|
||
5. Build-once: перетегирование образа, прошедшего staging, без пересборки.
|
||
6. Обновление `deployer.md` и `INFRA.md` (документация = golden source).
|
||
7. Для НЕ-self репо (enduro-trails и др.) — деплой по ssh на их хост (поведение не ломается).
|
||
|
||
### Вне объёма (явно)
|
||
- **Включение полного авто** (`DEPLOY_REQUIRE_MANUAL_APPROVE: true → false`) — отдельная задача,
|
||
ТОЛЬКО после набора метрик доверия (см. §7). В этой задаче флаг НЕ выключается.
|
||
- Изменение `docker-compose.yml` без явной необходимости.
|
||
- Изменение стадий `STAGE_TRANSITIONS`, реестра QG, terminal-sync `deploy → done`.
|
||
- Прод-деплой в реальный бой во время разработки задачи (отладка — только на staging-цели хука).
|
||
|
||
## 6. Бизнес-требования
|
||
|
||
- **BR-1.** После зелёного `deploy-staging`-гейта стадия `deploy` РЕАЛЬНО собирает/перетегирует
|
||
образ, рестартит целевой сервис и проверяет health — не пишет бумажный SUCCESS.
|
||
- **BR-2.** Для self-репо `orchestrator` рестарт 8500 выполняется ВНЕШНИМ (detached/host)
|
||
процессом; deployer-агент НЕ убивает контейнер, в котором работает.
|
||
- **BR-3.** `deploy_status: SUCCESS` пишется ТОЛЬКО при health-ok хука; провал/health-fail →
|
||
`deploy_status: FAILED` → откат на `development` (как ORCH-35 staging-rollback, БАГ-8).
|
||
- **BR-4.** Ручной approve обязателен (флаг `true`): без явного «go» прод НЕ трогается.
|
||
- **BR-5.** Каждый промоут и откат уведомляет Владельца: Plane-коммент в задачу + Telegram.
|
||
«Молчаливых» деплоев нет.
|
||
- **BR-6.** Build-once: в прод идёт тот образ, что прошёл staging-гейт (перетег, не пересборка).
|
||
- **BR-7.** Staging-гейт (`check_staging_status`) остаётся обязательным предусловием прод-деплоя.
|
||
- **BR-8.** Прод никогда не остаётся в нерабочем состоянии — авто-rollback при провале health.
|
||
- **BR-9.** Существующие гейты и инварианты не ломаются: `check_deploy_status`,
|
||
`_parse_deploy_status`, rollback `deploy → development` (БАГ-8), terminal-sync `deploy → done`,
|
||
merge-gate (ORCH-43).
|
||
- **BR-10.** Документация (`deployer.md`, `INFRA.md`, `CHANGELOG.md`) обновлена в том же PR.
|
||
|
||
## 7. Критерии готовности к включению ПОЛНОГО авто (вне этой задачи)
|
||
|
||
Переключать `DEPLOY_REQUIRE_MANUAL_APPROVE: true → false` можно ТОЛЬКО когда закрыты ВСЕ 5:
|
||
1. ≥10 успешных промоутов подряд (staging зелёный → approve → прод поднялся, откат не нужен).
|
||
2. Zero false-negative: staging-гейт ни разу не пропустил битый деплой как «зелёный».
|
||
3. Авто-rollback проверен в бою (≥2–3 реальных срабатывания), recovery 100%, MTTR < 60с.
|
||
4. Ни одного «молчаливого» деплоя (каждый промоут/откат уведомил Владельца).
|
||
5. Период наблюдения ≥10 деплоев ИЛИ ≥2 недели без инцидентов в режиме manual-approve.
|
||
|
||
## 8. Риски
|
||
|
||
| Риск | Влияние | Митигация |
|
||
|------|---------|-----------|
|
||
| Падение прод-орка 8500 при self-деплое | Встаёт конвейер ВСЕХ проектов | Detached host-хук + health + авто-rollback; отладка на staging-цели |
|
||
| Deployer рестартит сам себя синхронно | Процесс агента убит на середине | BR-2: рестарт только внешним detached-процессом |
|
||
| Преждевременный `deploy_status: SUCCESS` (хук ещё не закончил) | Задача уходит в done при незавершённом деплое | Гейт читает РЕАЛЬНЫЙ исход хука (механизм — на дизайне) |
|
||
| Деплой без approve | Неконтролируемый прод-деплой | BR-4: approve-гейт блокирует до «go» |
|
||
| Пересборка вместо перетега | В прод уезжает не то, что тестировали | BR-6: build-once, `--no-build` + retag |
|
||
|
||
## 9. Связанные задачи
|
||
ORCH-7 (self-hosting), ORCH-21 (auto-rollback), ORCH-34 (хук готов), ORCH-35 (staging-гейт),
|
||
ORCH-43 (merge-gate в проде), ORCH-54 (эпик автономного внедрения).
|
||
Дизайн-референс: `tasks/orchestrator/DESIGN_STAGING_ENV.md §4/§7`.
|