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

8.7 KiB
Raw Blame History

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.