diff --git a/openspec/changes/rolling-update/.openspec.yaml b/openspec/changes/rolling-update/.openspec.yaml new file mode 100644 index 00000000..a3692196 --- /dev/null +++ b/openspec/changes/rolling-update/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-11 diff --git a/openspec/changes/rolling-update/design.md b/openspec/changes/rolling-update/design.md new file mode 100644 index 00000000..b7c277a0 --- /dev/null +++ b/openspec/changes/rolling-update/design.md @@ -0,0 +1,472 @@ +# Design + +## Context + +Мотивация — `proposal.md`, «Why». Требования — дельты в `specs/`. +Стенд, LB и цепочка таймаутов — `.claude/rules/balancer.md`, миграции — +`migrations.md`, стенд `bench/` — `bench.md`. + +Текущее состояние (commit `c50b721`, change `graceful-failover` в +архиве): + +- **Стенд.** Сервис `api` × `API_REPLICAS` без имени контейнера. HAProxy + находит реплики через DNS Docker: 8 слотов `server-template`, + `init-state down`, `rise 2`, `inter 1s`, `fastinter 500ms`, `http-reuse + never`, `timeout server 10s`. Сервис `migrate` — одноразовый контейнер + на образе API, реплики ждут его завершения. +- **Миграции.** Три ревизии, все только добавляют. Ревизия ключей + идемпотентности `7652184b7016` уже писалась как expand. +- **Остановка реплики** (`stop-one.sh`, профиль `failover`) — `docker + stop` без вывода из LB. Под нагрузкой это даёт одиночный 502 в части + фаз `stop`: гонка keep-alive при SIGTERM (`graceful-failover`, + решения 3 и 10). +- **Обновление кода.** Сейчас — только `make down` + `make run_docker`. + `KNOWN_ISSUES.md` говорит, что `make run_docker` после пересборки не + пересоздаёт работающие `api`. +- **Хранилище образов Docker Desktop 29.8 — containerd** (`docker info`: + `io.containerd.snapshotter.v1`). У тега три разных digest: индекс + (`docker image inspect`), манифест платформы (метка + `com.docker.compose.image` контейнера) и конфигурация (поле + `.Image` контейнера; его показывает `docker ps` вместо имени тега). + Разведка 2026-10-11: реплики рабочего стенда работают на текущем + теге `mtusi-messenger:lab3`. Метка контейнера совпадает с манифестом + платформы тега, хотя `docker ps` показывает `04f700d0d939`, а не + имя. + +Разведка runtime API HAProxy (2026-10-11). Временный HAProxy того же +образа и с копией `haproxy.cfg` плюс `stats socket ipv4@127.0.0.1:9999 +level admin` стоял перед репликами рабочего стенда, команды шли через +`bash` `/dev/tcp` изнутри контейнера: + +- `show stat` по CLI отдаёт адрес слота (`172.30.0.5:8080`); +- `set server api/api-1 state drain` — слот `DRAIN`, 6 из 6 новых + запросов ушли на вторую реплику; +- `state maint` — `MAINT`, запросов на неё тоже нет; +- `state ready` при живом адресе — слот сначала `DOWN 1/2`, затем `UP` + через проверки. Возврат из ручного состояния проходит обычный `rise`, + а не мгновенный `UP`. + +## Goals / Non-Goals + +**Goals:** + +- Замена реплик на новый образ одной командой, без ошибок клиента под + нагрузкой и без потери записей. Плановая остановка — с дренажём, + поэтому без 502 гонки keep-alive. +- Миграция при замене: одна, до новых реплик, совместима со старым + кодом. Это проверено старым образом на новой схеме. +- Предсказуемое поведение при сбое: `API_REPLICAS` готовых реплик и + чистые слоты LB в любом исходе. +- Профиль `rollout` воспроизводим одной командой и использует тот же + скрипт, что рабочий стенд. + +**Non-Goals:** + +- Автоматический откат при сбое. Скрипт останавливается, а смешанные + версии допустимы: миграция только расширяет схему. Откат — тот же + скрипт с образом прежнего commit (решение 6). +- Дренаж в `stop-one.sh` и в профиле `failover`. Hook имитирует отказ, + а его срок возврата (< 10 с) не вмещает дренаж и graceful. +- Contract-миграция (удаление, переименование). В этой поставке её нет, + правило и порядок описаны. +- Swarm и сторонние плагины (`docker rollout`). Выбор Compose + HAProxy + подтверждён 2026-10-07 (`PLAN.md`); незакреплённых зависимостей не + прибавляется (`balancer.md`). +- Изменение HTTP API и контракта. + +## Decisions + +### 1. Порядок `scripts/rolling-update.sh` + +`#!/bin/sh`, `set -eu`, как `stop-one.sh`. Скрипт вызывает `docker +compose` без `-p` и `-f`. Проект, файлы и файл подстановок берутся из +окружения (`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`) +или из каталога репозитория. Поэтому один и тот же скрипт работает с +рабочим стендом и со стендом `bench/` (решение 8). Разведка +подтвердила: Compose 5.5.1 берёт `COMPOSE_ENV_FILES`, а +`COMPOSE_PROJECT_NAME` перекрывает `name:` файла. + +0. **Предусловия** (ничего не меняют): + - работает ровно `API_REPLICAS` реплик (по умолчанию 2); + - остановленных реплик сервиса нет. Иначе `up --scale` запустил бы + остановленную старую вместо новой; + - все реплики `UP` в LB; + - `API_REPLICAS` + 1 ≤ числа слотов LB. + + Нарушение — код 2 и подсказка `make replicas`. +1. **Сборка.** По умолчанию `docker compose build api` из рабочего + дерева. С `ROLLOUT_COMMIT=` образ собирается из файлов + commit (решение 6) под тем же тегом сервиса (`docker compose config + --images api`). +2. **Миграции один раз:** `docker compose run --rm --no-deps migrate` на + только что собранном образе. Ошибка — код 1 до замены. Скрипт + миграций не запускает при `ROLLOUT_MIGRATE=0` (откат, решение 6). + Порядок «сборка → миграции», а не наоборот, как в `balancer.md`: + новые ревизии лежат в новом образе. Правило исправляется. +3. **Новая реплика:** `docker compose up -d --no-deps --no-recreate + --no-build --scale api=N+1 api`. Новая — та, ID которой не было до + команды. +4. **Ожидание готовности** (решение 4). +5. **Вывод и удаление старой** (решение 3). +6. Шаги 3–5 — для каждой реплики, которая работала до шага 1. + +В конце — те же проверки, что в шаге 0: `N` работающих реплик, все +`UP`, ни одной из прежнего списка. Каждый шаг пишет строку `HH:MM:SS +rolling-update: …` с контейнером, слотом и адресом. Эти строки +разбирает профиль `rollout`. Вывод сборки и миграции идёт следом, в нём +нет секретов. + +### 2. Дренаж — runtime API HAProxy на loopback + +В `global` `haproxy.cfg`: `stats socket ipv4@127.0.0.1:9999 level +admin`. Скрипт отправляет команды так: `docker compose exec -T haproxy +bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 …'`, как `make lb_stats` читает +статистику. Слот реплики находится по её адресу в `show stat`: имя +слота с именем контейнера не связано (`balancer.md`). + +Почему так: + +- Снаружи контейнера LB канал не виден: loopback другого контейнера + недоступен, на хост порт не публикуется. Кто может выполнить `docker + exec`, и так управляет всем стендом. +- Приложение и цепочка таймаутов не меняются, поведение по SIGTERM + (спек `graceful-shutdown`) остаётся прежним. Решение принимает + оркестратор замены — он знает, что остановка плановая. +- Действует мгновенно, а не через 1,5 с проверок. + +Альтернативы: + +- **Readiness 503 по SIGTERM.** Реплика после сигнала отвечает на + `/health/ready` 503 и ещё ≥ 1,5 с принимает запросы, пока LB её не + исключит. Минусы: + - меняется спек `graceful-shutdown` («после SIGTERM новые соединения + не принимаются»); + - нужен свой обработчик сигнала поверх uvicorn; + - остановка удлиняется до 1,5 + 8 с — впритык к `stop_grace_period` + 10 с; + - срок `stop-one.sh` (< 10 с) перестаёт выполняться. + + Отвергнуто. +- **`stats admin` на странице `:8404`.** Порт открыт всей сети compose: + любой контейнер стенда, включая реплику, мог бы вывести реплики из + LB. Отвергнуто. +- **Unix-сокет.** Нужен `socat` или `nc -U`, а в образе HAProxy их нет; + bash с unix-сокетом не работает. Добавлять инструмент в закреплённый + образ — свой образ LB. Отвергнуто. +- **`set weight 0`** — то же, что `drain`, но состояние не видно в + статистике явно. `drain` нагляднее (`make lb_stats` показывает + `DRAIN`). + +### 3. Состояния слота старой реплики + +1. `set server api/<слот> state drain`. Новых запросов нет, начатые + дорабатывают (разведка). +2. Ожидание `scur` = 0 (запросов в полёте) не дольше + `ROLLOUT_DRAIN_TIMEOUT` = 12 с. Это больше `timeout server` 10 с: + дольше запрос через LB не живёт. По сроку — предупреждение и + остановка: оставшееся доработает graceful uvicorn (8 с). +3. `state maint` — проверки слота остановлены. Гибель процесса не + пишет в журнал `DOWN` с ошибкой соединения, и слот не может + вернуться в распределение по проверкам, пока процесс ещё отвечает. +4. `docker stop --timeout 10` (= `stop_grace_period`), `docker rm`. + Простаивающие соединения LB с репликой uvicorn закрывает при + SIGTERM. LB их больше не выбирает: слот выведен. Поэтому гонки + keep-alive нет. +5. Ожидание, пока адрес уйдёт из слота: DNS `hold` 1 с, не дольше + 10 с. Затем `state ready`. + +Почему `ready` нужен и почему после ухода адреса. Ручное состояние — +свойство слота, а не реплики. Если слот останется в `drain` или +`maint`, следующая реплика, которой DNS отдаст этот слот, не получит ни +одного запроса. А `ready` при ещё живом адресе вернул бы проверки к +мёртвому адресу: слот был бы `DOWN`, запросов бы не получил (разведка: +`ready` → `DOWN 1/2` → проверки), но журнал LB шумел бы. + +Почему `drain`, а потом `maint`, а не сразу `maint`. Исход для новых +запросов одинаков. Но `drain` — штатное «не давать новых, доработать +текущие», а ожидание `scur` = 0 видно в статистике и журнале LB как +отдельный шаг. `maint` нужен только на время гибели процесса. + +### 4. Новая реплика готова — `UP` в статистике LB + +Ожидание, срок `ROLLOUT_READY_TIMEOUT` = 60 с: + +1. Контейнер `healthy`, если у него есть healthcheck (рабочий стенд: + healthcheck образа, `start_interval` 1 с), иначе `running`. На + стенде `bench/` healthcheck выключен. +2. Слот с адресом новой реплики в состоянии `UP`. + +Только `healthy` мало. Слот получает адрес из DNS и начинает в `DOWN` +(`init-state down`). В распределение он попадает после двух успешных +проверок, то есть до 1,5 с после готовности (`downinter` + `fastinter`, +`graceful-failover`). Вывести старую раньше — на время до 1,5 с +остаться с N − 1 репликами. + +### 5. Сбой на середине + +Автоматического отката нет (Non-Goals). Скрипт держит инвариант +«`API_REPLICAS` готовых реплик и чистые слоты». Состояние текущей +замены — в переменных, `trap` на `EXIT`, `INT`, `TERM`: + +| Где оборвалось | Что делает скрипт | Итог | +|---|---|---| +| предусловия, сборка, миграция | ничего не трогал | N старых, код 2 / 1 | +| новая реплика не `UP` за срок, или прерывание до `UP` | `docker rm -f` новой; её слот уходит по DNS, ручного состояния у него не было | N реплик (k − 1 новых, остальные старые), код 1 | +| новая `UP`, старая в дренаже или останавливается | довести шаг 3 решения 3: `maint`, `stop`, `rm`, `ready`. Повторный Ctrl+C на время уборки игнорируется | N реплик, код 1 или 130 | +| уборка сама не удалась | печатает команды для ручного завершения (`docker rm …`, `set server … state ready`) | код 1 | + +Почему «довести», а не «вернуть» старую. Новая реплика уже готова и +получает запросы. Вернуть старую — значит N + 1 реплик или ещё один +вывод из LB. Довести шаг — не больше ~25 с: 12 с дренажа, 10 с +остановки, 2 с DNS. + +- Смешанные версии после сбоя безопасны: схема совместима с обеими + (решение 7, спек `db-migrations`). +- Повторный запуск заменяет все работающие реплики. Уже новые + заменяются на тот же образ: это лишняя, но безопасная работа. Образы + скрипт не сравнивает, решение 9. +- Слоты не переполняются: одновременно не больше N + 1 реплик, а N + 1 + ≤ 8 проверяется в предусловиях. + +Проверка сбоя — `ROLLOUT_READY_TIMEOUT=1`: реплика стартует ~3 с и за +1 с готовой не станет. Плюс Ctrl+C во время дренажа и остановленная +реплика перед запуском (`evidence/rollout/script-failures.md`). + +### 6. Образ другого commit без изменения рабочего дерева + +`git archive --format=tar | docker build -t <тег> -`. +Контекст — ровно файлы commit, `.dockerignore` commit применяется к +tar-контексту. Рабочее дерево, индекс и HEAD не меняются, лишних +каталогов нет. + +Где используется: + +- **Профиль `rollout`.** Старт на образе `Profile.rollout_from` (решение + 8). +- **Демонстрация на рабочем стенде.** Реплики на образе прежнего + commit: `git archive c50b721 | docker build -t mtusi-messenger:lab3 -` + и `docker compose up -d --no-build`. +- **Откат кода скриптом.** `make rolling_update COMMIT= + MIGRATE=0`. Миграции прежнего образа не знают новой ревизии, и + `alembic upgrade head` упал бы на «Can't locate revision». Поэтому + при откате миграции пропускаются явно. Схема остаётся новой, + прежний код на ней работает (решение 7). Автоопределения нет: явный + флаг надёжнее разбора текста ошибки alembic. + +Альтернативы: + +- `git worktree add` в scratchpad — тоже не трогает рабочее дерево, но + оставляет метаданные в `.git/worktrees` и требует уборки; +- `checkout` и `stash` запрещены (бриф) и сломали бы незакоммиченную + работу; +- `docker build` с git-URL контекста — нужен доступ к удалённому + репозиторию и push. + +### 7. Новая версия для демонстрации — `messages.instance_id` + +Колонка `instance_id text NULL` в `messages`: `X-Instance-Id` реплики, +которая записала сообщение. Новый код пишет `settings.app.instance_id` +при вставке (параметр `insert_message`, DTO не меняется). Старый код +колонку не знает: + +- вставка перечисляет колонки, и в новой колонке остаётся NULL; +- чтение выбирает `MESSAGE_COLUMNS`, то есть те же колонки. + +Контракт и ответы API не меняются: колонка наружу не отдаётся. + +Почему так: + +- Новый код **зависит** от новой схемы: без миграции его вставка упала + бы. Значит, порядок «миграция до новых реплик» проверяется по-настоящему. + Старый код **терпит** новую схему. Это и есть expand/contract в + миниатюре. +- По данным видно, какая версия записала сообщение (NULL — прежняя). + Это доказательство замены в БД, а не только по заголовкам. +- Ревизия — `op.add_column(..., nullable=True)`. В PostgreSQL ≥ 11 + колонка без значения по умолчанию добавляется изменением каталога, + без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на + миллисекунды, но в очереди за ней ждут все новые запросы к + `messages`. Поэтому первой строкой ревизии идёт `SET LOCAL + lock_timeout = '5s'`: + - чужая долгая транзакция не заставит миграцию держать очередь; + - по сроку миграция падает, схема не меняется, и замена не + начинается (спек `db-migrations`); + - повторный запуск проходит. +- `downgrade` удаляет колонку. Это шаг contract, допустимый только + после того, как не осталось нового кода. + +Альтернативы: + +- **Индекс `CONCURRENTLY`.** Код от схемы не зависит, демонстрация + совместимости пустая. Кроме того, `CONCURRENTLY` не выполняется + внутри транзакции alembic. +- **Переименование колонки.** Это не expand: старый код ломается. + Годится только как пример того, чего нельзя. +- **Только правка кода без схемы.** Совместимость миграций не + проверяется вовсе. + +Цена: +~13 байт на строку `messages` (12 символов ID и заголовок +varlena). Трек 1 снимает базовый замер после change, поэтому меток для +сравнения «до» нет. + +### 8. Профиль `rollout` стенда `bench/` + +| Поле | `rollout` | `rollout_quick` | +|---|---|---| +| реплик, лимиты | 2; как рабочий стенд (как `failover`) | те же | +| интенсивность | 100 записей с ключом + 100 чтений в секунду | та же | +| `rollout_from` | `c50b721` — последний commit до change | тот же | +| окна: до замены / бюджет замены / после | 15 / 90 / 15 с | 5 / 60 / 8 с | +| порог доли успешных | 99 % | 99 % | +| читаемый чат | 1 000 сообщений | тот же | + +- **Старт.** `run.py` собирает образ текущего checkout (паспорт, как + всегда) и образ `rollout_from` через `git archive` под тегом + `mtusi-messenger:bench-from`. Затем `docker tag` на + `mtusi-messenger:bench`, `Stand.start()`. Миграции прежнего образа + дают его последнюю ревизию, реплики стартуют прежнего образа. + Подготовка — как у `failover`: фикстура, читаемый чат, курсоры + (общий хелпер). +- **Нагрузка** — тот же `k6/failover.js`, `DURATION` = до + бюджет + + после, `PHASE` 1. Через «до» секунд `run.py` запускает + `scripts/rolling-update.sh`. Окружение — `Stand.env` (пароли, + `BENCH_*`), плюс `COMPOSE_PROJECT_NAME=mtusi-bench`, `COMPOSE_FILE` + (оба файла), `COMPOSE_ENV_FILES=bench/bench.env`, `API_REPLICAS`. + `docker compose build api` пересобирает текущий checkout под тег + `mtusi-messenger:bench`, слои из кэша. Правило `bench.md` «`-p`, + оба `-f`, `--env-file`» выполняется переменными окружения. +- **Время — часы ВМ.** Начало замены `t0` — событие `create` контейнера + миграции (`docker events` с меткой проекта). Шаги каждой реплики + берутся из трёх источников: + - события Docker: `create`/`start` новой, `kill` с сигналом 15, + `die`, `destroy` старой; + - журнал LB: `UP` слота новой, `drain`/`maint` слота старой; + - строки скрипта: какие слот и адрес у какой реплики. + + Сборка до `t0` измеряется по строкам скрипта (секунды). +- **Окна ошибок.** «До» — запросы, завершённые до `t0`. «Замена» — + отправленные от `t0` до `destroy` последней старой. «После» — всё + остальное. +- **Шкала.** Посекундно от `t0`, по образцу `failover`. Добавлены + `old_ok` и `new_ok`: успешные ответы с `X-Instance-Id` прежних и + новых контейнеров. Новые столбцы — в конце (`bench.md`). +- **Повтор и сверка** — `k6/retry.js` и `psql` стенда, как в `failover`. + Плюс: + - ревизия `alembic_version` до и после — измерение, а не изменение + схемы; + - контейнеры и `.Image` до и после; + - тег образа после замены. +- **Результаты** — `evidence/rollout/<метка>/`: + - `meta.json` (паспорт и раздел `rollout`); + - `rollout.csv` (строка прогона); + - `replicas.csv` (строка на заменённую реплику); + - `timeline.csv`, `summary.md`; + - `raw/rollout-k6.json`, `raw/rollout-lb.log`, `raw/rollout-script.log` + (только строки `rolling-update:`). + + Пробные `quick-rollout-*` — в `.gitignore`. +- **Отказ команды** — по списку спека `load-benchmark`. Ошибки клиента + — пометка (`errors`), а не отказ. +- **Код:** + - `bench/rollout.py` — чистые функции разбора и сводки на stdlib + поверх парсеров `failover.py`; + - `run.py` — профили, `--from ` для отладки (в + `overrides`), оркестрация. + + Тег `bench-from` снимается при уборке. + +### 9. `make run_docker` и пересборка + +Гипотеза: пункт `KNOWN_ISSUES.md` — ошибка диагностики. В хранилище +containerd `docker ps` показывает у реплик digest конфигурации, а не +имя тега, и это выглядит как «старый образ» (Context). Compose +сравнивает метку `com.docker.compose.image` с манифестом платформы +тега и должен пересоздавать реплики после пересборки. + +Проверка в apply. Реплики работают на образе прежнего commit, затем: + +1. `docker compose build api` (новый образ); +2. `docker compose --dry-run up -d`; +3. метки контейнеров против `docker image inspect --platform`. + +Исход: + +- **Compose пересоздаёт** (`Recreate`). Пункт закрывается в + `KNOWN_ISSUES.md` с объяснением. В комментарии `run_docker` и в + `REPORT.md`: `run_docker` пересоздаёт все реплики разом, с простоем; + без простоя — `make rolling_update`. +- **Не пересоздаёт.** `run_docker` получает явное пересоздание `api` + после сборки, пункт закрывается исправлением. + +Скрипт замены от этого не зависит: он определяет новую реплику по ID, +а не по образу. + +### 10. Evidence и отчёт + +| Файл | Что показывает | +|---|---| +| `evidence/rollout/<метка>/` | полный профиль `rollout` с commit change: шкала, шаги по репликам, контейнеры и образы до и после, сверка; хост по брифу | +| `evidence/rollout/compatibility.md` | рабочий стенд: реплики прежнего образа → новая миграция → `make test` и `make student_test` на прежнем образе и новой схеме → `make rolling_update` под `tests/load.py` → откат `COMMIT=c50b721 MIGRATE=0` под нагрузкой → снова вперёд; `docker compose ps` и образы до и после, `instance_id` сообщений по версиям, ревизия схемы; проверка `--dry-run` из решения 9 | +| `evidence/rollout/script-failures.md` | предусловия (остановленная реплика, не то число реплик), новая реплика не готова (`ROLLOUT_READY_TIMEOUT=1`), Ctrl+C во время дренажа, миграция не получила блокировку (`lock_timeout`), канал управления LB недоступен из сети | +| `evidence/tests/rolling-update-checks.md` | регрессия на commit кода: `make lint`, `check`, `test`, `student_test`, `test_isolated`, `failure_checks`, `test-persistence`, `test-failover` (`stop` и `kill`), `bench_quick`, `bench_failover_quick`, `bench_rollout_quick` | + +`REPORT.md`: + +- строки таблицы доказательств уровня «4» — замена под нагрузкой, + миграции однократно и совместимы, вместо строки TODO; +- процедура замены и состояния слота; +- раздел профиля `rollout` в «Эксперименты и отказы»; +- ограничения: нет автоотката, contract отдельной поставкой, одиночный + 502 остаётся только у незапланированного `docker stop`; +- ответ на вопрос защиты о `depends_on` и healthcheck дополняется + ожиданием `UP` в LB при замене; +- раздел «Обновление без простоя и миграции» в ответах на вопросы + защиты. + +## Risks / Trade-offs + +- **[Канал управления LB — admin-уровень]** → слушает только + `127.0.0.1` внутри контейнера LB. Проверка — попытка подключиться к + порту 9999 LB из другого контейнера сети (`script-failures.md`). + Доступ через `docker exec` равен доступу к Docker, то есть ко всему + стенду. +- **[`lock_timeout` 5 с может не хватить под тяжёлой записью]** → + миграция падает без изменений, замена не начинается, повтор проходит. + Это лучше, чем очередь всех записей за миграцией. Без нагрузки + блокировка берётся за миллисекунды. +- **[Новый код на старой схеме падает]** → только если миграцию + пропустить при движении вперёд. Скрипт пропускает её лишь по явному + `MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в + скрипте и спеке. +- **[`git archive` берёт только закоммиченное]** → это и нужно: + «прежняя версия» — commit, а не рабочее дерево. Commit записывается в + паспорт. +- **[Профиль `rollout` собирает образ под нагрузкой]** → сборка из кэша + слоёв — секунды CPU ВМ, видны в шкале до `t0`. Так и при реальной + замене на том же хосте; длительность — в результатах. +- **[`docker compose exec` на каждую команду LB]** → ~0,1–0,2 с на вызов, + опрос каждые 0,25–0,5 с. Замена двух реплик — десятки вызовов, + секунды. +- **[Повторный запуск после сбоя заменяет и уже новые реплики]** → это + лишняя работа, но безопасная и проще, чем сравнивать digest в + хранилище containerd (Context). +- **[DNS отдал адрес удалённой реплики новой раньше, чем слот вернулся + в `ready`]** → IPAM Docker не переиспользует адрес сразу, а `ready` + выставляется до следующего `--scale`. Слот новой реплики проверяется + в шаге ожидания по её адресу: если он застрял в ручном состоянии, + замена падает по сроку с понятной причиной, а не тихо. +- **[Один хост]** → профиль показывает поведение замены и порядок + величин, а не распределение. Генератор, LB, реплики, сборка и + PostgreSQL делят ВМ Docker. + +## Migration Plan + +1. Код, ревизия, скрипт и конфиг LB коммитятся. Рабочий стенд получает + их одной командой `make rolling_update`: новая ревизия применяется, + реплики заменяются. `haproxy.cfg` с runtime API подхватывается + пересозданием LB (`docker compose up -d haproxy`). Это короткий + перерыв точки входа, а не реплик. Делается один раз, до первой + замены: без канала управления скрипт останавливается в предусловиях. +2. Откат кода — `make rolling_update COMMIT=<прежний> MIGRATE=0`. Схема + остаётся новой, прежний код на ней работает. Колонку удаляет только + отдельная contract-миграция, когда прежнего кода точно нет. diff --git a/openspec/changes/rolling-update/proposal.md b/openspec/changes/rolling-update/proposal.md new file mode 100644 index 00000000..1f8822dc --- /dev/null +++ b/openspec/changes/rolling-update/proposal.md @@ -0,0 +1,137 @@ +# 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. diff --git a/openspec/changes/rolling-update/specs/db-migrations/spec.md b/openspec/changes/rolling-update/specs/db-migrations/spec.md new file mode 100644 index 00000000..73ed3b79 --- /dev/null +++ b/openspec/changes/rolling-update/specs/db-migrations/spec.md @@ -0,0 +1,71 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Совместимость миграции с работающей версией + +Миграция SHALL только расширять схему: +- новая таблица; +- новая колонка, допускающая NULL или со значением по умолчанию; +- новый индекс. + +Удаление и переименование таблицы, колонки или ограничения, а также +новое ограничение, которое нарушит запись прежней версии, MUST NOT +входить в ту же поставку, что и код, которому они нужны. Такое +изменение выполняется отдельной миграцией после того, как реплик +прежней версии не осталось (expand/contract). Если так сделать нельзя, +ограничение SHALL описываться в `REPORT.md`. + +Реплики прежнего образа SHALL обслуживать обязательные запросы на +схеме после новой миграции. Откат кода к прежнему образу MUST NOT +требовать отката схемы. + +Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком. +Долгая транзакция приложения не должна заставить миграцию держать +очередь за собой и остановить запись остальных реплик. По истечении +срока миграция SHALL завершаться ошибкой без изменения схемы, а её +повторный запуск SHALL проходить. + +#### Scenario: Старый образ на новой схеме + +- **WHEN** стенд работает на образе прежнего commit, и миграции нового + образа применены, а реплики не заменены +- **THEN** `make test` и `make student_test` через LB проходят на + прежних репликах + +#### Scenario: Запись прежней версии + +- **WHEN** после новой миграции сообщение отправлено через реплику + прежнего образа +- **THEN** ответ 201, а сообщение видно в истории через реплику любого + образа + +#### Scenario: Блокировка не получена + +- **WHEN** таблицу, которую меняет миграция, держит открытая + транзакция дольше срока ожидания блокировки +- **THEN** миграция завершается ошибкой, схема не меняется, запись + других клиентов продолжается, а после окончания транзакции повторный + запуск применяет миграцию + +### Requirement: Однократные миграции при замене реплик + +Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции +один раз за запуск: отдельным одноразовым контейнером на новом образе, +после сборки образа и до запуска первой новой реплики. Реплики MUST +NOT запускать миграции сами. Если миграция завершилась ошибкой, замена +MUST NOT начинаться: работающие реплики не трогаются, скрипт +завершается с ненулевым кодом. + +#### Scenario: Одна миграция на замену + +- **WHEN** выполнен `make rolling_update` для двух реплик +- **THEN** в журнале замены одна миграция до первой новой реплики, в + журналах реплик записей alembic нет, а ревизия схемы после замены — + последняя + +#### Scenario: Миграция упала + +- **WHEN** миграция при замене завершается ошибкой +- **THEN** скрипт завершается с ненулевым кодом до запуска новых + реплик, а прежние реплики работают и обслуживают запросы diff --git a/openspec/changes/rolling-update/specs/graceful-shutdown/spec.md b/openspec/changes/rolling-update/specs/graceful-shutdown/spec.md new file mode 100644 index 00000000..46b575f5 --- /dev/null +++ b/openspec/changes/rolling-update/specs/graceful-shutdown/spec.md @@ -0,0 +1,31 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Плановая остановка реплики без ошибок + +При плановой остановке реплики за балансировщиком (поочерёдная замена, +`load-balancing`) реплика SHALL сначала выводиться из LB. Только когда +у неё не осталось запросов в полёте, она получает SIGTERM. Поэтому +плановая остановка под постоянной нагрузкой MUST NOT давать клиенту ни +одной ошибки, включая 502 гонки keep-alive из требования «Остановка +реплики за балансировщиком». + +Поведение процесса по SIGTERM не меняется: требования выше действуют. Не +меняется и остановка без дренажа (`scripts/stop-one.sh`, `docker +stop`): она имитирует отказ, и исключение для 502 гонки keep-alive к +ней по-прежнему применяется. + +#### Scenario: Остановка после дренажа под нагрузкой + +- **WHEN** через LB с постоянной интенсивностью идут запись с ключом и + чтение истории, и реплика остановлена после вывода из LB +- **THEN** ни одного неуспешного ответа, в том числе 502, а журнал LB + не показывает ошибок соединения с этой репликой + +#### Scenario: Остановка за заявленный срок после дренажа + +- **WHEN** реплика выведена из LB и получила SIGTERM +- **THEN** процесс завершается быстрее 10 с с кодом выхода не 137, а в + её журнале есть «Shutting down», «Stopped API» и «Finished server + process» diff --git a/openspec/changes/rolling-update/specs/load-balancing/spec.md b/openspec/changes/rolling-update/specs/load-balancing/spec.md new file mode 100644 index 00000000..f4a6fbdc --- /dev/null +++ b/openspec/changes/rolling-update/specs/load-balancing/spec.md @@ -0,0 +1,120 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Поочерёдная замена реплик + +Команда `make rolling_update` (`scripts/rolling-update.sh`) SHALL +заменять работающие реплики API на образ из текущего checkout по одной, +без остановки обслуживания. Порядок: +1. сборка образа; +2. миграции, один раз (`db-migrations`); +3. для каждой старой реплики: + - рядом запускается одна новая; + - скрипт ждёт её готовности и состояния `UP` в статистике LB; + - старая выводится из LB, дорабатывает запросы, останавливается и + удаляется. + +Реплик одновременно SHALL быть не больше `API_REPLICAS` + 1. Число +должно помещаться в слоты LB. Правка конфигурации LB и его перезапуск +MUST NOT требоваться. + +После успешной замены SHALL работать ровно `API_REPLICAS` реплик. Все +они SHALL быть на новом образе и в состоянии `UP` в LB. Контейнеров +прежнего образа SHALL не остаться ни работающих, ни остановленных. + +Под постоянной нагрузкой через LB (запись с ключом и чтение истории) +замена MUST NOT давать клиенту ошибок. Каждая подтверждённая запись +SHALL оставаться доступной. + +Перед заменой скрипт SHALL проверять стенд: +- работает ровно `API_REPLICAS` реплик; +- остановленных реплик нет; +- все реплики `UP` в LB; +- для ещё одной реплики есть свободный слот LB. + +Если условие не выполнено, скрипт SHALL завершаться с ненулевым кодом +до сборки и ничего не менять. + +#### Scenario: Замена двух реплик + +- **WHEN** работают две реплики прежнего образа, и выполнен `make + rolling_update` +- **THEN** команда завершается с кодом 0, работают две реплики с новыми + `X-Instance-Id` на новом образе, обе `UP` в LB, а контейнеров прежних + реплик нет + +#### Scenario: Замена под нагрузкой + +- **WHEN** во время `make rolling_update` через LB с постоянной + интенсивностью идут запись с ключом и чтение истории +- **THEN** ни один ответ клиенту не ошибочен, в ответах сначала есть + только старые `X-Instance-Id`, затем старые и новые, затем только + новые, а число сообщений в чате равно числу отправленных ключей + +#### Scenario: Стенд не готов к замене + +- **WHEN** одна реплика остановлена `scripts/stop-one.sh`, или работает + не `API_REPLICAS` реплик +- **THEN** скрипт завершается с ненулевым кодом до сборки, называет + причину и предлагает `make replicas`, а контейнеры не меняются + +### Requirement: Вывод реплики из балансировщика перед остановкой + +Перед плановой остановкой реплики LB SHALL перестать направлять ей +новые запросы. Запросы, которые она уже обрабатывает, SHALL +дорабатываться. Остановка SHALL начинаться после того, как запросов в +полёте у неё не осталось, или по истечении срока ожидания, большего +`timeout server` LB. Управление LB SHALL быть доступно только изнутри +контейнера LB. Из сети compose и с хоста оно MUST NOT быть доступно. + +Состояние слота, выставленное при замене, SHALL сниматься, когда адрес +удалённой реплики ушёл из слота. Слот, который потом получит новая +реплика, SHALL включаться по обычным проверкам готовности. + +#### Scenario: Выведенная реплика не получает запросов + +- **WHEN** слот реплики переведён в дренаж, и через LB идут запросы +- **THEN** все новые ответы приходят от других реплик, а запросы, + начатые до дренажа, получают ответ + +#### Scenario: Управление LB недоступно из сети + +- **WHEN** контейнер в сети стенда или процесс на хосте обращается к + портам LB +- **THEN** изменить состояние реплики он не может: канал управления LB + слушает только loopback внутри контейнера LB + +#### Scenario: Слот после замены + +- **WHEN** замена завершена +- **THEN** в статистике LB нет слотов в дренаже или в обслуживании, + выставленном вручную; свободные слоты — только в обслуживании по DNS + +### Requirement: Сбой поочерёдной замены + +Если новая реплика не стала готовой в LB за срок ожидания, скрипт +SHALL удалить её и завершиться с ненулевым кодом. Старые реплики, +которые ещё не заменены, SHALL остаться в работе. + +Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика +стала `UP`, скрипт SHALL довести вывод текущей старой реплики до +удаления. Только после этого он завершается. + +В любом исходе SHALL работать `API_REPLICAS` готовых реплик. Слоты LB +SHALL быть без состояния, выставленного вручную. Реплики разных версий +допустимы: миграция совместима с обеими. Повторный запуск SHALL +доводить замену до конца. + +#### Scenario: Новая реплика не готова + +- **WHEN** новая реплика не стала `UP` в LB за срок ожидания +- **THEN** она удалена, скрипт завершился с ненулевым кодом и назвал + шаг, работают `API_REPLICAS` реплик, все `UP`, и запросы через LB + обслуживаются + +#### Scenario: Прерывание во время дренажа + +- **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB +- **THEN** старая реплика остановлена и удалена, новая работает, + реплик `API_REPLICAS`, а слот старой реплики без ручного состояния diff --git a/openspec/changes/rolling-update/specs/load-benchmark/spec.md b/openspec/changes/rolling-update/specs/load-benchmark/spec.md new file mode 100644 index 00000000..019c3570 --- /dev/null +++ b/openspec/changes/rolling-update/specs/load-benchmark/spec.md @@ -0,0 +1,166 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Фиксированный стенд + +Стенд SHALL состоять из балансировщика (LB), реплик приложения, +PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по +умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, +собранного из текущего checkout тем же `Dockerfile`. Исключение — +профиль поочерёдной замены. Он стартует на образе commit, заданного +методикой: образ собирается тем же `Dockerfile` из файлов этого commit +без изменения рабочего дерева. Заканчивается профиль на образе текущего +checkout. LB SHALL +запускаться из того же образа и с той же конфигурацией, что у рабочего +стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у +рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL +получает те же настройки образа плюс модуль записи планов, выключенный +вне снятия плана. Схема БД SHALL применяться миграциями до наполнения. + +Лимиты SHALL быть одинаковыми во всех прогонах профиля: +- у каждой реплики приложения — лимит CPU и памяти без swap, заданный + методикой (в профилях лабы 2 — 1 CPU и 2 ГБ); +- у LB, PostgreSQL и Valkey — свои лимиты CPU и памяти без swap, + заданные методикой. + +Healthcheck образа приложения SHALL быть отключён: готовность реплик +проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки +приложения и хранилищ SHALL браться из методики стенда, а не из `.env` +и `config.toml` рабочего стенда. Пароли хранилищ SHALL генерироваться +на прогон. Генератор нагрузки SHALL работать в той же docker-сети и +обращаться к приложению через LB по имени сервиса, минуя проброс +портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми +все реплики. + +#### Scenario: Лимиты в паспорте + +- **WHEN** прогон завершён +- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти + реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных + контейнеров, и они одинаковы для всех размеров + +#### Scenario: Нехватка памяти + +- **WHEN** процесс приложения превысил лимит памяти и был убит +- **THEN** прогон помечен как проваленный из-за OOM, а не записан как + обычный результат + +#### Scenario: Настройки рабочего стенда не влияют + +- **WHEN** `.env` и `config.toml` рабочего стенда изменены или + отсутствуют +- **THEN** стенд запускается с теми же настройками приложения и + хранилищ, а окружение приложения в паспорте то же + +#### Scenario: Схема до наполнения + +- **WHEN** начинается наполнение размера +- **THEN** миграции применены до последней ревизии, и приложение + отвечает готовностью + +#### Scenario: Одна реплика за балансировщиком + +- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`, + `restore_quick`) запущен с одной репликой +- **THEN** все запросы генератора проходят через LB, прогон завершается + с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и + разделы, что раньше + +#### Scenario: Образ прежнего commit + +- **WHEN** запускается профиль поочерёдной замены +- **THEN** реплики стартуют на образе commit из методики, схема — на + его последней ревизии, рабочее дерево не меняется, а commit и образы + до и после записаны в паспорт + +## ADDED Requirements + +### Requirement: Профиль поочерёдной замены + +Команда `make bench_rollout` (метка `ROLLOUT_LABEL`) SHALL на свежем +стенде с лимитами рабочего стенда и `API_REPLICAS` по методике +выполнять поочерёдную замену реплик (`scripts/rolling-update.sh`, +`load-balancing`) под нагрузкой. Реплики стартуют на образе прежнего +commit и заменяются на образ текущего checkout. Команда `make +bench_rollout_quick` делает то же с короткими окнами, метка +`quick-rollout-…`, в git она не идёт. Результаты SHALL сохраняться в +`evidence/rollout/<метка>/`. Занятая метка SHALL давать отказ до +запуска стенда. + +Нагрузка — постоянная интенсивность, заданная методикой: запись +сообщения с `Idempotency-Key` и чтение страницы истории. Скрипт +замены SHALL запускаться через заданное методикой время после начала +нагрузки. Нагрузка SHALL продолжаться после его завершения. Скрипт +SHALL быть тем же, что у рабочего стенда, и выполняться против проекта +compose стенда. + +SHALL сохраняться посекундная шкала от начала замены (создание +контейнера миграции): +- успешные записи и чтения; +- ошибки по кодам; +- доля успешных; +- p50 и p95 задержки успешных; +- число успешных ответов старых и новых реплик; +- распределение ответов по `X-Instance-Id`. + +По каждой заменённой реплике SHALL сохраняться: +- время от запуска новой реплики до её `UP` в LB; +- время дренажа старой реплики; +- время её остановки; +- время замены целиком. + +Для прогона целиком SHALL сохраняться: +- длительность замены; +- ошибки по кодам до, во время и после замены; +- минимальная доля успешных в секунде; +- контейнеры, их образы и ревизия схемы до и после. + +После прогона каждая неподтверждённая запись SHALL повторяться с тем +же ключом и телом до 201. Число сообщений чата записи SHALL совпадать +с числом отправленных ключей, одинаковых текстов MUST NOT быть. + +Команда SHALL завершаться с ненулевым кодом в случаях: +- скрипт замены вернул ненулевой код; +- генератор упал; +- PostgreSQL или Valkey падал; +- сверка не сошлась; +- в конце работает не `API_REPLICAS` реплик; +- среди работающих реплик есть реплика прежнего образа; +- не все реплики `UP` в LB. + +Ошибки клиента при замене — результат, а не отказ команды: они +считаются и показываются. + +#### Scenario: Полный профиль + +- **WHEN** выполнен `make bench_rollout` +- **THEN** в `evidence/rollout/<метка>/` есть посекундная шкала, таблица + шагов по каждой заменённой реплике, сводка, контейнеры и образы до и + после, код выхода 0 + +#### Scenario: Быстрый профиль + +- **WHEN** выполнен `make bench_rollout_quick` +- **THEN** за несколько минут проходит замена всех реплик, код выхода 0, + каталог метки в git не попадает + +#### Scenario: Версии в ответах + +- **WHEN** замена завершена +- **THEN** шкала показывает, как доля ответов старых реплик падает до + нуля, а новых растёт до всех, а ответов прежних `X-Instance-Id` после + удаления их контейнеров нет + +#### Scenario: Без потерь и дублей при замене + +- **WHEN** нагрузка с записью шла всё время замены +- **THEN** после повтора неподтверждённых записей с тем же ключом в чате + записи столько сообщений, сколько отправлено ключей, без одинаковых + текстов + +#### Scenario: Замена не удалась + +- **WHEN** скрипт замены завершился с ненулевым кодом +- **THEN** команда завершается с ненулевым кодом, называет шаг из + журнала скрипта, сохраняет частичные результаты и удаляет стенд diff --git a/openspec/changes/rolling-update/tasks.md b/openspec/changes/rolling-update/tasks.md new file mode 100644 index 00000000..e91ec791 --- /dev/null +++ b/openspec/changes/rolling-update/tasks.md @@ -0,0 +1,179 @@ +# 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`; + - рабочее дерево чистое.