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 <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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`: одна новая реплика рядом со
|
||||
|
||||
+3
-2
@@ -103,8 +103,9 @@ SHALL оставаться доступной.
|
||||
|
||||
### Requirement: Сбой поочерёдной замены
|
||||
|
||||
Если новая реплика не стала готовой в LB за срок ожидания, скрипт
|
||||
SHALL удалить её и завершиться с ненулевым кодом. Старые реплики,
|
||||
Если новая реплика не стала готовой в LB за срок ожидания или замена
|
||||
прервана раньше, скрипт SHALL удалить её и завершиться с ненулевым
|
||||
кодом, в том числе когда её ID скрипту ещё не известен. Старые реплики,
|
||||
которые ещё не заменены, SHALL остаться в работе.
|
||||
|
||||
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
|
||||
@@ -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** скрипт завершается с ненулевым кодом до запуска новых
|
||||
реплик, а прежние реплики работают и обслуживают запросы
|
||||
|
||||
@@ -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»
|
||||
|
||||
@@ -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`, а слот старой реплики без ручного состояния
|
||||
|
||||
@@ -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** команда завершается с ненулевым кодом, называет шаг из
|
||||
журнала скрипта, сохраняет частичные результаты и удаляет стенд
|
||||
|
||||
Reference in New Issue
Block a user