Files
mtusi2026lab3/openspec/changes/rolling-update/tasks.md
T

11 KiB
Raw Blame History

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

  • 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 — без расхождений.

  • 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. Балансировщик и скрипт замены

  • 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.

  • 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/

  • 3.1 bench/rollout.py (решение 8): разбор строк скрипта, событий Docker проекта и журнала LB по шагам замены; шкала с old_ok / new_ok; окна до, во время и после; строка прогона; строки по репликам; summary.md. Только stdlib, парсеры — из failover.py.

  • 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. Документы

  • 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. Общая проверка кода и коммит

  • 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 кода

  • 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, если дефект подтвердился). Проверка: в файле на каждом шаге команда, код выхода и наблюдение.

  • 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;
    • рабочее дерево чистое.