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:
+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