Files
mtusi2026lab3/openspec/changes/rolling-update/specs/load-balancing/spec.md
T
2026-10-11 00:26:36 +03:00

121 lines
7.6 KiB
Markdown

# 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`, а слот старой реплики без ручного состояния