From 84ee13ca5a99de2b3b2146d3a41a04bd642dfef8 Mon Sep 17 00:00:00 2001 From: roman Date: Sun, 11 Oct 2026 01:59:19 +0300 Subject: [PATCH] chore: archive rolling-update change Sync the rolling-update delta specs into db-migrations, graceful-shutdown, load-balancing and load-benchmark, move the change to the archive, mark it in PLAN.md and update the transitional state and code map in AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 16 ++- PLAN.md | 6 +- .../2026-10-11-rolling-update}/.openspec.yaml | 0 .../2026-10-11-rolling-update}/design.md | 0 .../2026-10-11-rolling-update}/proposal.md | 0 .../specs/db-migrations/spec.md | 0 .../specs/graceful-shutdown/spec.md | 0 .../specs/load-balancing/spec.md | 5 +- .../specs/load-benchmark/spec.md | 0 .../2026-10-11-rolling-update}/tasks.md | 0 openspec/specs/db-migrations/spec.md | 71 +++++++++ openspec/specs/graceful-shutdown/spec.md | 28 ++++ openspec/specs/load-balancing/spec.md | 135 ++++++++++++++++++ openspec/specs/load-benchmark/spec.md | 102 ++++++++++++- 14 files changed, 352 insertions(+), 11 deletions(-) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/.openspec.yaml (100%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/design.md (100%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/proposal.md (100%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/specs/db-migrations/spec.md (100%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/specs/graceful-shutdown/spec.md (100%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/specs/load-balancing/spec.md (96%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/specs/load-benchmark/spec.md (100%) rename openspec/changes/{rolling-update => archive/2026-10-11-rolling-update}/tasks.md (100%) diff --git a/AGENTS.md b/AGENTS.md index 8aedc4fb..3019e1a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,9 +108,13 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog работ, решения и трек «5» — `PLAN.md`. Стенд — проект compose `mtusi-lab3` со своей базой: HAProxy перед двумя репликами `api` (change `replicas-lb`) с согласованной цепочкой таймаутов (change -`graceful-failover`, в архиве); `make test`, `make test-persistence` и -`make test-failover` проходят через LB, новый код доходит до реплик без -простоя через `make rolling_update` (change `rolling-update`). +`graceful-failover`); `make test`, `make test-persistence` и `make +test-failover` проходят через LB, новый код доходит до реплик без +простоя через `make rolling_update` (change `rolling-update`). Все три +change — в архиве. После замен реплики называются `api-N` с растущим +номером (compose нумерует новые контейнеры сервиса по возрастанию): +штатные цели с ними работают, `make down` + `make run_docker` снова +дают `api-1`, `api-2`. - Стенд `bench/` уже на HAProxy + N реплик, но нагрузка трека 1 (открытая модель, серии A/B, метрики LB и PostgreSQL по репликам) — @@ -272,7 +276,7 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog | `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) | | `make instances` | вход одним синтетическим пользователем, 12 × `GET /users/me` через LB: `X-Instance-Id` каждого ответа и итог по репликам | | `make lb_stats` | слоты HAProxy: адрес, состояние проверки (`DRAIN`, `MAINT` при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) | -| `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`); сбой — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ | +| `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) | | `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | | `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст | | `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) | @@ -366,7 +370,7 @@ infra/ # конфигурации сервисов сте haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене) scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG -scripts/rolling-update.sh # make rolling_update: предусловия, сборка (или COMMIT через git archive), миграции один раз, по одной: новая UP в LB → старая drain → maint → stop → rm → слот ready; trap при сбое; тот же скрипт — профиль rollout стенда bench/ +scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/ Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам .dockerignore @@ -380,7 +384,7 @@ evidence/idempotency/ # повтор, 409, гонка, таблица к evidence/replicas/ # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ evidence/failover/<метка>/ # результаты make bench_failover: паспорт, phases.csv, посекундная timeline.csv, summary.md, итоги k6 и журнал LB по фазам -evidence/rollout/ # совместимость старого образа с новой схемой и make rolling_update на рабочем стенде, отказы скрипта +evidence/rollout/ # совместимость старого образа с новой схемой, make rolling_update и жизненный цикл стенда после замены, отказы скрипта (Ctrl+C, слоты, lock_timeout миграции) evidence/rollout/<метка>/ # результаты make bench_rollout: паспорт с контейнерами, образами и ревизией до и после, rollout.csv, replicas.csv, timeline.csv, summary.md, строки скрипта, журнал LB evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6 evidence/compare/ # таблицы make bench_compare: <до>__<после>.md diff --git a/PLAN.md b/PLAN.md index cdaba0a3..4f5f3707 100644 --- a/PLAN.md +++ b/PLAN.md @@ -292,7 +292,7 @@ Swarm дал бы встроенный rolling update (`update_config`), но э | 1 | `instance-id-idempotency` | 3 (+4: гонка одного ключа) | Переименование стенда в `mtusi-lab3`. `X-Instance-Id` на каждом ответе и `instance_id` в логах. Таблица ключей, `Idempotency-Key` в ручке, сервисе и repo: повтор → тот же 201, другое тело → 409. Ключ добавляется во все свои клиенты: тесты, k6, драйвер скилла | `make test_isolated` (smoke lab3 + свой набор), `make failure_checks`, `make bench_quick` зелёные на одном процессе. **Код реализован 2026-10-08** (`/opsx:apply`); осталось: общая проверка, коммит, evidence, `REPORT.md`, verify и archive | | 2 | `replicas-lb` | 3 (+4: лимиты, порты, секреты, гонка через реплики) | HAProxy — единственная точка входа, `api` × `API_REPLICAS` без портов, лимиты CPU/RAM у всех, секреты по сервисам. `restart.sh` с LB, новый `stop-one.sh`. Тесты против стенда с LB | `make test`, `make test-persistence`, `make test-failover` через LB для каждой реплики; гонка ключа видит ≥2 реплики. **Заархивирован 2026-10-10** (`openspec/changes/archive/2026-10-10-replicas-lb/`; verify — решение 14 design: формула обнаружения зависшей реплики `fall × (inter + timeout check)` = 8 с, цена лимита 1 CPU для Argon2id, evidence снято заново с `a4ca9ef`) | | 3 | `graceful-failover` | 4 | Цепочка таймаутов зафиксирована и обоснована. Замер времени обнаружения отказа при `stop` и `kill`. Стенд `bench/` переходит на HAProxy + N реплик, профиль `failover`: поочерёдная остановка каждой реплики под нагрузкой | посекундные RPS, ошибки и время восстановления по каждой реплике в `evidence/failover/`, таблица таймаутов в `REPORT.md`. **Заархивирован 2026-10-11** (`openspec/changes/archive/2026-10-11-graceful-failover/`; замер `evidence/failover/baseline/` с `459f84c`; verify — решение 10 design: отвергнутый вариант пула LB переснят на закоммиченном коде, уборка триггера `hang-key` при прерывании, `make bench_compare` отказывает метке без LB; дренаж до SIGTERM и `make run_docker` без пересоздания реплик переданы в `rolling-update`, ниже) | -| 4 | `rolling-update` | 4 | `scripts/rolling-update.sh`: замена реплик по одной на новый образ под нагрузкой. Миграции однократно и совместимы со старой версией | прогон под нагрузкой с ошибками по секундам в `evidence/rollout/`; старый образ работает на новой схеме | +| 4 | `rolling-update` | 4 | `scripts/rolling-update.sh`: замена реплик по одной на новый образ под нагрузкой. Миграции однократно и совместимы со старой версией | прогон под нагрузкой с ошибками по секундам в `evidence/rollout/`; старый образ работает на новой схеме. **Заархивирован 2026-10-11** (`openspec/changes/archive/2026-10-11-rolling-update/`; замер `evidence/rollout/baseline/` с `9dcea0b`, итоговый код `84161c0`; verify — решение 12 design: уборка при Ctrl+C внутри `up --scale`, предусловие о слотах LB с ручным состоянием, `lock_timeout` миграции 2 с вместо 5 с (при равном `statement_timeout` запросы в очереди за миграцией получали 503), ограничение отката; совместимость и отказы скрипта пересняты на `84161c0`) | | 5 | `scaling-bench` | 5 (трек 1) | Открытая модель нагрузки, серии A (фиксированный бюджет 1×4 / 2×2 / 4×1) и B (1…8 реплик), метрики HAProxy и Postgres, графики, точка насыщения | метки серий и A/A в `evidence/bench/`, точка насыщения и её причина в `REPORT.md` | | 6 | `scaling-improvement` | 5 (трек 1) | Одно улучшение на найденном узком месте, «до/после» через `make bench_ab`, отделение эффекта от шума | `evidence/compare/` с эффектом больше шума A/A, вывод в `REPORT.md` | | 7 | — (отчёт и PR) | 3–5 | Сводка `REPORT.md`, проверка из чистого clone, шаблон PR, уборка переходных разделов | PR `ЛР 3 — БВТ2301 — Сафронов — на 5` | @@ -469,7 +469,9 @@ Swarm дал бы встроенный rolling update (`update_config`), но э - Миграции однократно и совместимы с работающей версией (либо ограничение описано). -**Скрипт** `scripts/rolling-update.sh` и цель Makefile: +**Скрипт** `scripts/rolling-update.sh` и цель Makefile (как сделано — +design change, решение 1: сборка раньше миграций, миграция в +контейнере сервиса `migrate`, а не `run --rm`): 1. Миграции один раз (`run --rm migrate`). 2. Сборка нового образа. 3. `--scale api=N+1 --no-recreate`: одна новая реплика рядом со diff --git a/openspec/changes/rolling-update/.openspec.yaml b/openspec/changes/archive/2026-10-11-rolling-update/.openspec.yaml similarity index 100% rename from openspec/changes/rolling-update/.openspec.yaml rename to openspec/changes/archive/2026-10-11-rolling-update/.openspec.yaml diff --git a/openspec/changes/rolling-update/design.md b/openspec/changes/archive/2026-10-11-rolling-update/design.md similarity index 100% rename from openspec/changes/rolling-update/design.md rename to openspec/changes/archive/2026-10-11-rolling-update/design.md diff --git a/openspec/changes/rolling-update/proposal.md b/openspec/changes/archive/2026-10-11-rolling-update/proposal.md similarity index 100% rename from openspec/changes/rolling-update/proposal.md rename to openspec/changes/archive/2026-10-11-rolling-update/proposal.md diff --git a/openspec/changes/rolling-update/specs/db-migrations/spec.md b/openspec/changes/archive/2026-10-11-rolling-update/specs/db-migrations/spec.md similarity index 100% rename from openspec/changes/rolling-update/specs/db-migrations/spec.md rename to openspec/changes/archive/2026-10-11-rolling-update/specs/db-migrations/spec.md diff --git a/openspec/changes/rolling-update/specs/graceful-shutdown/spec.md b/openspec/changes/archive/2026-10-11-rolling-update/specs/graceful-shutdown/spec.md similarity index 100% rename from openspec/changes/rolling-update/specs/graceful-shutdown/spec.md rename to openspec/changes/archive/2026-10-11-rolling-update/specs/graceful-shutdown/spec.md diff --git a/openspec/changes/rolling-update/specs/load-balancing/spec.md b/openspec/changes/archive/2026-10-11-rolling-update/specs/load-balancing/spec.md similarity index 96% rename from openspec/changes/rolling-update/specs/load-balancing/spec.md rename to openspec/changes/archive/2026-10-11-rolling-update/specs/load-balancing/spec.md index 2710efdd..3928af7d 100644 --- a/openspec/changes/rolling-update/specs/load-balancing/spec.md +++ b/openspec/changes/archive/2026-10-11-rolling-update/specs/load-balancing/spec.md @@ -103,8 +103,9 @@ SHALL оставаться доступной. ### Requirement: Сбой поочерёдной замены -Если новая реплика не стала готовой в LB за срок ожидания, скрипт -SHALL удалить её и завершиться с ненулевым кодом. Старые реплики, +Если новая реплика не стала готовой в LB за срок ожидания или замена +прервана раньше, скрипт SHALL удалить её и завершиться с ненулевым +кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики, которые ещё не заменены, SHALL остаться в работе. Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика diff --git a/openspec/changes/rolling-update/specs/load-benchmark/spec.md b/openspec/changes/archive/2026-10-11-rolling-update/specs/load-benchmark/spec.md similarity index 100% rename from openspec/changes/rolling-update/specs/load-benchmark/spec.md rename to openspec/changes/archive/2026-10-11-rolling-update/specs/load-benchmark/spec.md diff --git a/openspec/changes/rolling-update/tasks.md b/openspec/changes/archive/2026-10-11-rolling-update/tasks.md similarity index 100% rename from openspec/changes/rolling-update/tasks.md rename to openspec/changes/archive/2026-10-11-rolling-update/tasks.md diff --git a/openspec/specs/db-migrations/spec.md b/openspec/specs/db-migrations/spec.md index 420f5560..dbdf2d93 100644 --- a/openspec/specs/db-migrations/spec.md +++ b/openspec/specs/db-migrations/spec.md @@ -87,3 +87,74 @@ - **WHEN** та же миграция применяется к пустой базе или повторно - **THEN** ничего не удаляется, и команда завершается с кодом 0 + +### Requirement: Совместимость миграции с работающей версией + +Миграция SHALL только расширять схему: +- новая таблица; +- новая колонка, допускающая NULL или со значением по умолчанию; +- новый индекс. + +Удаление и переименование таблицы, колонки или ограничения, а также +новое ограничение, которое нарушит запись прежней версии, MUST NOT +входить в ту же поставку, что и код, которому они нужны. Такое +изменение выполняется отдельной миграцией после того, как реплик +прежней версии не осталось (expand/contract). Если так сделать нельзя, +ограничение SHALL описываться в `REPORT.md`. + +Реплики прежнего образа SHALL обслуживать обязательные запросы на +схеме после новой миграции. Откат кода к прежнему образу MUST NOT +требовать отката схемы. + +Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком. +Долгая транзакция приложения не должна заставить миграцию держать +очередь за собой и остановить запись остальных реплик. Срок SHALL быть +меньше срока запроса приложения к БД (`statement_timeout`): запросы, +вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а +не завершаются ошибкой вместе с ним. По истечении срока миграция 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/specs/graceful-shutdown/spec.md b/openspec/specs/graceful-shutdown/spec.md index da91f3a5..62380e07 100644 --- a/openspec/specs/graceful-shutdown/spec.md +++ b/openspec/specs/graceful-shutdown/spec.md @@ -107,3 +107,31 @@ keep_alive_seconds`. LB MUST NOT держать простаивающие со - **THEN** соединения на порт API внутри каждой реплики закрываются раньше `keep_alive_seconds` с момента последнего запроса, по сроку простоя LB + +### 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/specs/load-balancing/spec.md b/openspec/specs/load-balancing/spec.md index 7c084c57..0dc3cb60 100644 --- a/openspec/specs/load-balancing/spec.md +++ b/openspec/specs/load-balancing/spec.md @@ -321,3 +321,138 @@ idle_in_transaction_timeout_ms`. Блокировки этой транзакц - **THEN** после прерывания транзакции повтор получает 201, в чате ровно одно сообщение с этим текстом, а после разморозки реплика снова обслуживает запросы + +### 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; +- нет слотов 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`, а контейнеры не меняются + +#### Scenario: Слот остался в ручном состоянии + +- **WHEN** слот LB без адреса оставлен в ручном обслуживании или + дренаже, и выполнен `make rolling_update` +- **THEN** скрипт завершается с ненулевым кодом до сборки, называет слот + и печатает команду, которая возвращает его в `ready`, а контейнеры не + меняются + +### 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 удалить её и завершиться с ненулевым +кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики, +которые ещё не заменены, SHALL остаться в работе. + +Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика +стала `UP`, скрипт SHALL довести вывод текущей старой реплики до +удаления. Только после этого он завершается. + +В любом исходе SHALL работать `API_REPLICAS` готовых реплик. Слоты LB +SHALL быть без состояния, выставленного вручную. Реплики разных версий +допустимы: миграция совместима с обеими. Повторный запуск SHALL +доводить замену до конца. + +#### Scenario: Новая реплика не готова + +- **WHEN** новая реплика не стала `UP` в LB за срок ожидания +- **THEN** она удалена, скрипт завершился с ненулевым кодом и назвал + шаг, работают `API_REPLICAS` реплик, все `UP`, и запросы через LB + обслуживаются + +#### Scenario: Прерывание при запуске новой реплики + +- **WHEN** скрипт прерван Ctrl+C, пока compose создаёт новую реплику, и + её ID скрипту ещё не известен +- **THEN** новая реплика удалена, работают `API_REPLICAS` прежних + реплик, все `UP`, а слоты без ручного состояния + +#### Scenario: Прерывание во время дренажа + +- **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB +- **THEN** старая реплика остановлена и удалена, новая работает, + реплик `API_REPLICAS`, а слот старой реплики без ручного состояния diff --git a/openspec/specs/load-benchmark/spec.md b/openspec/specs/load-benchmark/spec.md index d837e9d9..032ed7f1 100644 --- a/openspec/specs/load-benchmark/spec.md +++ b/openspec/specs/load-benchmark/spec.md @@ -56,7 +56,11 @@ Ctrl+C, контейнеры, сеть и volume стенда SHALL удалят Стенд SHALL состоять из балансировщика (LB), реплик приложения, PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа, -собранного из текущего checkout тем же `Dockerfile`. LB SHALL +собранного из текущего checkout тем же `Dockerfile`. Исключение — +профиль поочерёдной замены. Он стартует на образе commit, заданного +методикой: образ собирается тем же `Dockerfile` из файлов этого commit +без изменения рабочего дерева. Заканчивается профиль на образе текущего +checkout. LB SHALL запускаться из того же образа и с той же конфигурацией, что у рабочего стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL @@ -112,6 +116,13 @@ Healthcheck образа приложения SHALL быть отключён: с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и разделы, что раньше +#### Scenario: Образ прежнего commit + +- **WHEN** запускается профиль поочерёдной замены +- **THEN** реплики стартуют на образе commit из методики, схема — на + его последней ревизии, рабочее дерево не меняется, а commit и образы + до и после записаны в паспорт + ### Requirement: Сценарии нагрузки Стенд SHALL поддерживать два сценария с синтетическими данными @@ -962,3 +973,92 @@ SHALL совпадать с числом разных ключей, отправ время фазы - **THEN** команда завершается с ненулевым кодом, называет контейнер, а стенд удаляется + +### 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** команда завершается с ненулевым кодом, называет шаг из + журнала скрипта, сохраняет частичные результаты и удаляет стенд