Files
mtusi2026lab3/openspec/changes/rolling-update/proposal.md
T
2026-10-11 00:26:36 +03:00

138 lines
8.7 KiB
Markdown

# Proposal
## Why
Последний пункт рубрики «4» лабы 3 (`README.md`) ещё не закрыт:
- rolling update или эквивалентная поочерёдная замена, проверенная под
нагрузкой;
- миграции запускаются однократно и совместимы с работающей версией,
либо ограничение честно описано.
Сейчас новый код доходит до реплик только через `make down` и `make
run_docker`. Это простой всего API (`KNOWN_ISSUES.md`, `PLAN.md`,
раздел change `rolling-update`). Миграции действительно выполняются
один раз: сервис `migrate` стартует до реплик. Но совместимость новой
схемы с работающей версией нигде не проверялась.
Change `graceful-failover` передал сюда ещё три пункта:
- **дренаж до SIGTERM.** При `docker stop` под нагрузкой остаётся
одиночный 502. Это гонка keep-alive: uvicorn закрывает простаивающие
соединения, а LB в тот же миг шлёт в одно из них запрос. Так было в
1 из 4 фаз `stop`. При плановой замене реплику нужно сначала вывести
из LB;
- **ожидание `UP` в LB**, а не только `healthy` контейнера: новая
реплика попадает в распределение через ≤ 1,5 с после готовности;
- **`make run_docker` не пересоздаёт работающие `api`** после пересборки
образа. Пункт записан в `KNOWN_ISSUES.md`, но отдельно не
воспроизводился.
## What Changes
- **`scripts/rolling-update.sh` и `make rolling_update`.** Скрипт по
одной заменяет реплики на новый образ без простоя:
1. сборка образа;
2. миграции, один раз;
3. рядом со старыми поднимается одна новая реплика;
4. скрипт ждёт её готовности и `UP` в LB;
5. старая реплика выводится из LB и дорабатывает запросы, затем
останавливается и удаляется;
6. шаги 3–5 повторяются для каждой старой реплики.
Перед запуском скрипт проверяет состояние стенда. При сбое на
середине останавливается и оставляет `API_REPLICAS` готовых реплик.
- **Дренаж через runtime API HAProxy.** Канал управления LB слушает
только loopback внутри контейнера LB, наружу и в сеть compose не
открыт. Через него скрипт переводит слот старой реплики в `drain` и
`maint` и потом возвращает его в `ready`. Поведение остановки по
SIGTERM и hook `stop-one.sh` не меняются: hook имитирует отказ, а не
плановую остановку.
- **Новая версия для демонстрации — expand-миграция.** В таблицу
`messages` добавляется колонка `instance_id`, допускающая NULL:
реплика, которая записала сообщение. Новый код её заполняет, старый
не знает о ней и пишет NULL. Контракт и поведение API не меняются.
Миграция ограничивает ожидание блокировки (`lock_timeout`): долгая
чужая транзакция не остановит все записи за ней.
- **Совместимость доказывается на рабочем стенде** по шагам:
1. реплики на образе прежнего commit;
2. новая миграция, а реплики остаются прежними;
3. `make test` и `make student_test` на старом образе и новой схеме;
4. `make rolling_update` под нагрузкой `tests/load.py`;
5. проверки на новом образе.
- **Профиль `rollout` стенда `bench/`** (`make bench_rollout`, `make
bench_rollout_quick`) построен по образцу `failover`:
- стенд стартует на образе заданного commit;
- k6 даёт постоянную интенсивность записи с ключом и чтения;
- посреди нагрузки работает тот же `scripts/rolling-update.sh`;
- сохраняются посекундная шкала, доли ответов старой и новой версии
и время каждого шага замены;
- фиксируются контейнеры, образы и ревизия схемы до и после;
- неуспешные записи повторяются с тем же ключом, затем идёт сверка.
Результаты — в `evidence/rollout/<метка>/`.
- **`make run_docker`.** Пункт `KNOWN_ISSUES.md` проверяется
воспроизведением: собранный новый образ, `docker compose --dry-run up
-d`. Если дефект подтвердится, он исправляется. Если нет, пункт
закрывается с объяснением. В обоих случаях в документации:
`run_docker` пересоздаёт все реплики разом, обновление без простоя
делает `rolling_update`.
- **Документы:**
- правила `balancer.md`, `migrations.md`, `bench.md`, `run-modes.md`,
`docker.md`;
- `AGENTS.md`: команды, карта кода, «Переходное состояние»;
- `REPORT.md`: строки доказательств уровня «4», процедура замены,
ограничения, вопросы защиты.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `load-balancing`:
- поочерёдная замена реплик на новый образ под нагрузкой без ошибок
и без потери записей;
- вывод реплики из LB перед плановой остановкой;
- поведение замены при сбое на середине.
- `db-migrations`:
- миграция совместима с работающей версией (только расширение);
- при замене миграции запускаются один раз и до новых реплик;
- ожидание блокировки ограничено.
- `graceful-shutdown`: плановая остановка реплики после дренажа не
даёт клиенту ни одной ошибки, в том числе 502 гонки keep-alive.
- `load-benchmark`:
- профиль `rollout` стартует на образе заданного commit, а не
текущего checkout;
- новый профиль поочерёдной замены под нагрузкой.
## Impact
- **Новое:**
- `scripts/rolling-update.sh`;
- ревизия alembic `added message instance id`;
- `bench/rollout.py` — разбор и сводка профиля;
- `evidence/rollout/`.
- **Код приложения:**
- модель `Message`;
- `src/core/repos/message.py` — `instance_id` при вставке;
- `MessageService.send_message` передаёт `settings.app.instance_id`.
HTTP API и контракт не меняются.
- **Стенд:**
- `infra/haproxy/haproxy.cfg` — runtime API на loopback;
- `Makefile` — цели `rolling_update`, `bench_rollout`,
`bench_rollout_quick`, при необходимости `run_docker`;
- `.gitignore` — `evidence/rollout/quick-*/`.
- **Стенд `bench/`:**
- `run.py` — профили `rollout` и `rollout_quick`, сборка образа
прежнего commit через `git archive`;
- `k6/failover.js` и `k6/retry.js` — без изменений, повторно
используются.
- **Документы:** `.claude/rules/`, `AGENTS.md`, `REPORT.md`,
`KNOWN_ISSUES.md`, скилл `run-mtusi-messenger` (новая цель).
- **Зависимости** не прибавляются: те же образы HAProxy и k6, shell и
stdlib Python.