138 lines
8.7 KiB
Markdown
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.
|