94 lines
6.8 KiB
Markdown
94 lines
6.8 KiB
Markdown
---
|
||
work_item: ORCH-100
|
||
stage: architecture
|
||
author_agent: architect
|
||
status: proposed
|
||
created_at: 2026-06-10
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 07 — Инфра-требования: ORCH-100 — FND/F1b: sidecar-watchdog
|
||
|
||
Work Item: **ORCH-100** · Repo: **orchestrator** · Стадия: architecture
|
||
|
||
> When-applicable: топология **меняется** (новый рантайм-контейнер). Разовое инфра-действие выполняет
|
||
> человек (Слава/Стрим) на хосте mva154; дальше код `watchdog/` катится через конвейер (self-hosting).
|
||
|
||
## I-1. Топология / окружения
|
||
|
||
Новый сервис `orchestrator-watchdog` в `docker-compose.yml` — **отдельный контейнер** рядом с
|
||
`orchestrator` (8500) и `orchestrator-staging` (8501, profile staging).
|
||
- **Образ:** `build: ./watchdog` (`watchdog/Dockerfile`, `python:3.12-slim`, stdlib-only).
|
||
- **Сеть:** `network_mode: host` — достаёт `/metrics` орка как `http://127.0.0.1:8500/metrics` и
|
||
хост-интерфейсы (ADR-001 D2).
|
||
- **Тома (все read-only к наблюдаемому, NFR-4):**
|
||
- `/var/run/docker.sock:/var/run/docker.sock:ro` — статусы контейнеров (GET-only).
|
||
- `/home/slin/repos:/repos:ro` и `./data:/app/data:ro` (или эквивалент) — дисковые метрики хоста
|
||
через `shutil.disk_usage` (те же пути, что у `disk_watchdog`).
|
||
- **Лимиты:** `mem_limit: 128m` + `mem_reservation: 32m` (тонкость измерима/принудительна, NFR-2);
|
||
`restart: unless-stopped` (самовосстановление, FR-1).
|
||
- **Kill-switch:** `WATCHDOG_ENABLED` (env). `false` → демон инертен (idle-loop, не exit — чтобы
|
||
`restart` не крутил петлю), нулевой эффект на орк.
|
||
- **Контейнеры под наблюдением (BR-4):** минимум `orchestrator`; список `WATCHDOG_CONTAINERS` (CSV).
|
||
- **Образец сервиса (ориентир для developer; точные пути сверить с актуальным `docker-compose.yml`):**
|
||
```yaml
|
||
orchestrator-watchdog:
|
||
build: ./watchdog
|
||
container_name: orchestrator-watchdog
|
||
restart: unless-stopped
|
||
network_mode: host
|
||
mem_limit: 128m
|
||
mem_reservation: 32m
|
||
volumes:
|
||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||
- /home/slin/repos:/repos:ro
|
||
- ./data:/app/data:ro
|
||
env_file: .env.watchdog # ЛИБО общий .env с префиксом WATCHDOG_ (деталь — developer/оператор)
|
||
group_add: ["999"] # docker-группа для чтения docker.sock (как у орка)
|
||
```
|
||
|
||
## I-2. Переменные окружения / секреты
|
||
|
||
Канон (без секретов) — в `.env.example` (TRZ §2). Префикс `WATCHDOG_` (изоляция от `ORCH_`):
|
||
- **Секреты (только на хосте, в гит НЕ коммитятся):** `WATCHDOG_TG_BOT_TOKEN`, `WATCHDOG_TG_CHAT_ID`
|
||
— **собственные** bot/chat sidecar, независимые от Telegram орка (BR-8). Отсутствие → sidecar
|
||
логирует и не шлёт (fail-safe), но не падает.
|
||
- **Управление:** `WATCHDOG_ENABLED` (kill-switch), `WATCHDOG_INTERVAL_S` (дефолт 60),
|
||
`WATCHDOG_ORCH_METRICS_URL` (дефолт `http://127.0.0.1:8500/metrics`).
|
||
- **Пороги/таймауты (дефолты — ADR-001 D5):** `WATCHDOG_ORCH_DOWN_TICKS=3`, `WATCHDOG_MEM_PCT=90`,
|
||
`WATCHDOG_DISK_CRIT_ENABLED=false`, `WATCHDOG_DISK_CRIT_PCT=97`, `WATCHDOG_AGENT_HUNG_MIN=20`,
|
||
`WATCHDOG_AGENT_CPU_FLOOR=0.01`, `WATCHDOG_STAGE_STUCK_MIN=120`, `WATCHDOG_QUEUE_DEPTH=20`,
|
||
`WATCHDOG_COOLDOWN_S` (анти-спам realert), `WATCHDOG_HTTP_TIMEOUT_S`.
|
||
- **Цели:** `WATCHDOG_CONTAINERS` (CSV, дефолт `orchestrator`), `WATCHDOG_DEP_PLANE_URL`/
|
||
`WATCHDOG_DEP_GITEA_URL`/`WATCHDOG_DEP_ANTHROPIC_URL` (health/ping).
|
||
|
||
> Анти-дубль диск-алерта (ADR-001 D6): штатный 85%-алерт остаётся за внутренним `disk_watchdog`
|
||
> (ORCH-063). `WATCHDOG_DISK_CRIT_ENABLED` по умолчанию `false` — sidecar НЕ дублирует диск, пока
|
||
> оператор осознанно не включит независимый критический потолок.
|
||
|
||
## I-3. Деплой / рестарт
|
||
|
||
- **Разовое действие человеком на хосте (Слава/Стрим):**
|
||
1. Создать **отдельного** Telegram-бота watchdog + получить chat-id; положить `WATCHDOG_TG_*` в
|
||
`.env.watchdog` (или `.env`) на хосте.
|
||
2. Заполнить пороги/интервалы (дефолты годятся), включить `WATCHDOG_ENABLED=true`.
|
||
3. Добавить сервис в `docker-compose.yml` (приходит с PR) и поднять **только его:**
|
||
`docker compose up -d --build orchestrator-watchdog`.
|
||
- **Self-hosting инвариант (критично):** поднятие/пересборка `orchestrator-watchdog` **НЕ** трогает
|
||
прод-контейнер `orchestrator` (отдельный сервис) — конвейер всех проектов не прерывается. **НЕ**
|
||
выполнять `docker compose up -d` без явного имени сервиса, если это спровоцирует рекреейт орка.
|
||
- **Прод-выкат кода watchdog** — через штатный self-hosting-конвейер и **обязательный staging-гейт
|
||
(8501)** перед прод-деплоем; деплой sidecar не рестартит прод-контейнер орка.
|
||
- **Проверка после старта (NFR-7):** `docker logs orchestrator-watchdog` показывает старт + тики;
|
||
тестовый алерт приходит в канал watchdog; остановка орка (на staging) → приходит `orch_down`.
|
||
|
||
## I-4. CI/CD
|
||
|
||
- Без изменений `.gitea/workflows/` по существу: новые тесты sidecar (`watchdog/tests/` или
|
||
`tests/watchdog/`) подхватываются существующим `pytest tests/`/прогоном (изолированы, чистые
|
||
функции — без контейнера/таймера). Если выбран отдельный путь `watchdog/tests/`, developer
|
||
обеспечивает его включение в существующий тест-ран (без нового workflow-файла).
|
||
- Docker-сборка нового образа — стандартным `docker compose build` (отдельный `watchdog/Dockerfile`),
|
||
без правок пайплайна CI.
|
||
</content>
|