Old image passes smoke and student tests on the new schema, rolling update, rollback and roll forward under tests/load.py give zero failed requests; the run_docker known issue is not reproduced and is closed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
180 lines
11 KiB
Markdown
180 lines
11 KiB
Markdown
# Tasks
|
||
|
||
Как строить — `design.md` (дальше «решение N»). Что должно получиться —
|
||
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
|
||
`balancer.md`, `docker.md`, `migrations.md`, `bench.md`,
|
||
`run-modes.md`, `repo-layer.md`, `service-layer.md`.
|
||
|
||
Рабочий стенд `mtusi-lab3` до задачи 6.1 не трогать миграциями и
|
||
пересборкой. Его база должна остаться на ревизии `7652184b7016`, а
|
||
реплики — на прежнем образе: это исходное состояние демонстрации
|
||
совместимости. Не запускать `make run_docker`, `make upgrade`, `make
|
||
revision`. Сборка `make test_isolated` двигает тег
|
||
`mtusi-messenger:lab3`, но не реплики и не базу стенда; задача 6.1 всё
|
||
равно собирает прежний образ заново.
|
||
|
||
Evidence снимается с закоммиченного кода: коммит кода → evidence →
|
||
коммит evidence. Замер для отчёта (`make bench_rollout`) — только после
|
||
проверки хоста по брифу, рабочий стенд на время замера остановлен.
|
||
|
||
## 1. Приложение: колонка `messages.instance_id`
|
||
|
||
- [x] 1.1 Модель `Message` и ревизия alembic по решению 7:
|
||
- `instance_id: Mapped[str | None]` (Text, NULL) с комментарием;
|
||
- ревизия `added message instance id` через `uv run alembic revision
|
||
--autogenerate` против базы на прежней ревизии, только чтение схемы.
|
||
Затем вручную: `SET LOCAL lock_timeout = '5s'` первой строкой
|
||
`upgrade` и комментарий про expand и contract.
|
||
|
||
Проверка: `uv run alembic upgrade head` и `downgrade -1` / `upgrade
|
||
head` на временной базе (не рабочей); `alembic check` после `upgrade`
|
||
— без расхождений.
|
||
- [x] 1.2 `insert_message(..., instance_id)` в repo и передача
|
||
`settings.app.instance_id` из `MessageService.send_message`; DTO и
|
||
ответ API не меняются. Проверка: `make lint`; после задачи 5.2 строка
|
||
сообщения, записанного через API, содержит `instance_id` =
|
||
`X-Instance-Id` ответа.
|
||
|
||
## 2. Балансировщик и скрипт замены
|
||
|
||
- [x] 2.1 `infra/haproxy/haproxy.cfg`: `stats socket
|
||
ipv4@127.0.0.1:9999 level admin` в `global` с комментарием (решение
|
||
2). Проверка: `haproxy -c` в закреплённом образе с `API_PORT=8080` —
|
||
`Configuration file is valid`.
|
||
- [x] 2.2 `scripts/rolling-update.sh` по решениям 1–6 (исполняемый бит
|
||
в git). Внутри:
|
||
- предусловия;
|
||
- сборка из рабочего дерева или `ROLLOUT_COMMIT`;
|
||
- миграция один раз, `ROLLOUT_MIGRATE=0` — пропуск;
|
||
- цикл замены: ожидание `healthy` и `UP` по адресу, `drain` →
|
||
`scur` = 0 → `maint` → `stop` → `rm` → адрес ушёл → `ready`;
|
||
- итоговая проверка;
|
||
- `trap` с состояниями решения 5;
|
||
- строки `HH:MM:SS rolling-update: …` с контейнером, слотом и адресом;
|
||
- секретов не печатает.
|
||
|
||
Цель `make rolling_update` (`API_REPLICAS`, `COMMIT`, `MIGRATE`).
|
||
Проверка: задачи 5.2 и 6.1–6.2.
|
||
|
||
## 3. Профиль `rollout` стенда `bench/`
|
||
|
||
- [x] 3.1 `bench/rollout.py` (решение 8): разбор строк скрипта, событий
|
||
Docker проекта и журнала LB по шагам замены; шкала с `old_ok` /
|
||
`new_ok`; окна до, во время и после; строка прогона; строки по
|
||
репликам; `summary.md`. Только stdlib, парсеры — из `failover.py`.
|
||
- [x] 3.2 `bench/run.py`:
|
||
- профили `rollout` и `rollout_quick`, поля `Profile`;
|
||
- `--from` для отладки;
|
||
- образ прежнего commit через `git archive`, тег `bench-from` и
|
||
`docker tag`;
|
||
- общая подготовка с `failover`;
|
||
- запуск `scripts/rolling-update.sh` с окружением compose стенда;
|
||
- сбор событий, журнала LB и строк скрипта;
|
||
- повтор, сверка, итоговые проверки;
|
||
- каталог `evidence/rollout/<метка>/`, снятие тега при уборке.
|
||
|
||
Цели `bench_rollout` (`ROLLOUT_LABEL ?= baseline`) и
|
||
`bench_rollout_quick` в `Makefile`, `evidence/rollout/quick-*/` в
|
||
`.gitignore`. Проверка: `make lint`; `make bench_rollout_quick` —
|
||
код 0, замена двух реплик, сверка сошлась, `summary.md` и
|
||
`replicas.csv` с шагами; занятая метка — отказ до стенда.
|
||
|
||
## 4. Документы
|
||
|
||
- [x] 4.1 Правила под решения:
|
||
- `balancer.md` — порядок «сборка → миграции», дренаж, состояния
|
||
слота, сбой, runtime API;
|
||
- `migrations.md` — новая ревизия, `lock_timeout`, откат кода без
|
||
отката схемы;
|
||
- `bench.md` — профиль `rollout`;
|
||
- `run-modes.md` — 502 гонки keep-alive остаётся только у остановки
|
||
без дренажа;
|
||
- `docker.md` — `run_docker` и обновление по решению 9.
|
||
|
||
`AGENTS.md`:
|
||
- команды — `rolling_update`, `bench_rollout`, `bench_rollout_quick`;
|
||
- карта кода — `rolling-update.sh` без «(лаба 3)», `bench/rollout.py`,
|
||
`evidence/rollout/`;
|
||
- «Переходное состояние» — закрытый пункт убрать.
|
||
|
||
Скилл `run-mtusi-messenger` — новая цель. Проверка: `grep -n
|
||
"rolling-update" AGENTS.md .claude/rules/*.md` — нет обещаний «будет».
|
||
|
||
## 5. Общая проверка кода и коммит
|
||
|
||
- [x] 5.1 `make lint`, `make check`, `openspec validate rolling-update
|
||
--strict`, `haproxy -c`. Проверка: все с кодом 0.
|
||
- [ ] 5.2 Самопроверки на своих стендах, рабочий не трогается:
|
||
- `make test_isolated` — новая ревизия на временной базе, smoke и
|
||
набор;
|
||
- `make failure_checks`;
|
||
- `make bench_rollout_quick`;
|
||
- `make bench_failover_quick`;
|
||
- `make bench_quick`.
|
||
|
||
Затем коммит кода (`feat: …`). Проверка: все с кодом 0, рабочее
|
||
дерево чистое.
|
||
|
||
## 6. Evidence с commit кода
|
||
|
||
- [x] 6.1 Совместимость и `make run_docker` на рабочем стенде (решения 6,
|
||
7, 9; `evidence/rollout/compatibility.md`):
|
||
- реплики на образе `c50b721` (`git archive`), LB пересоздан с новым
|
||
`haproxy.cfg`, ревизия `7652184b7016`, `make test`;
|
||
- `docker compose build api` и `docker compose --dry-run up -d` —
|
||
исход решения 9;
|
||
- `docker compose run --rm migrate` — новая ревизия при прежних
|
||
репликах, затем `make test` и `make student_test` на них;
|
||
- `make rolling_update` под `tests/load.py`;
|
||
- откат `make rolling_update COMMIT=c50b721 MIGRATE=0` под нагрузкой;
|
||
- снова `make rolling_update`;
|
||
- `make test` и `make student_test`;
|
||
- `docker compose ps` и образы на каждом шаге;
|
||
- `instance_id` сообщений по версиям.
|
||
|
||
Исход решения 9 — в `KNOWN_ISSUES.md` (и `Makefile`, если дефект
|
||
подтвердился). Проверка: в файле на каждом шаге команда, код выхода и
|
||
наблюдение.
|
||
- [x] 6.2 Отказы скрипта (`evidence/rollout/script-failures.md`):
|
||
- остановленная реплика (`stop-one.sh`) и `API_REPLICAS=3` —
|
||
отказ до сборки;
|
||
- `ROLLOUT_READY_TIMEOUT=1` — новая удалена, N реплик `UP`;
|
||
- Ctrl+C во время дренажа — старая доведена до удаления, слоты
|
||
чистые;
|
||
- миграция не получила блокировку (открытая транзакция на `messages`
|
||
в `psql`) — замена не начиналась, повтор после конца транзакции
|
||
прошёл (на временной базе или до 6.1);
|
||
- порт 9999 LB из другого контейнера сети — отказ соединения.
|
||
|
||
Проверка: после каждого случая `make lb_stats` — N реплик `UP`, слотов
|
||
`DRAIN` / `MAINT` вне DNS нет.
|
||
- [ ] 6.3 Регрессия на commit кода (`evidence/tests/rolling-update-checks.md`):
|
||
- `make test`, `make student_test` через LB;
|
||
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh`;
|
||
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` в режимах
|
||
`stop` и `kill`, `make replicas` между ними;
|
||
- выводы 5.1–5.2.
|
||
|
||
Проверка: в шапке — спеки, change, дата, commit, стенд, хост.
|
||
- [ ] 6.4 Хост по брифу: питание, давление на память, `docker ps`,
|
||
`docker info`, `vm_stat` (`Swapouts`) до и после. Затем `make stop`,
|
||
`nohup make bench_rollout` с журналом, после — снова рабочий стенд.
|
||
Проверка: `evidence/rollout/baseline/` со статусом `complete`, сверка
|
||
сошлась; плохой хост — Telegram и остановка (бриф).
|
||
- [ ] 6.5 `REPORT.md` по решению 10:
|
||
- строки доказательств уровня «4» вместо TODO;
|
||
- процедура замены;
|
||
- раздел профиля `rollout` в «Эксперименты и отказы»;
|
||
- ограничения;
|
||
- ответы на вопросы защиты.
|
||
|
||
Проверка: у каждой новой строки есть команда, наблюдение и файл; в
|
||
evidence и отчёте нет паролей, токенов и абсолютных путей домашнего
|
||
каталога.
|
||
- [ ] 6.6 Финал:
|
||
- `make lint`, `openspec validate rolling-update --strict`;
|
||
- отметить задачи, коммит evidence и отчёта (`docs: …`);
|
||
- `graphify update .`;
|
||
- рабочий стенд `mtusi-lab3` поднят, все реплики `UP`;
|
||
- рабочее дерево чистое.
|