Files
mtusi2026lab2/openspec/specs/lab3-failover-operations/spec.md
T

14 KiB
Raw Blame History

lab3-failover-operations Specification

Purpose

Определяет эксплуатационные гарантии реплицированного стенда: за какое время балансировщик исключает отказавшую реплику, как переживается поочерёдный отказ и плановая замена реплик под нагрузкой, как проверяется общая идемпотентность параллельными запросами и как ограничены ресурсы, порты, секреты и хранилища.

Requirements

Requirement: Согласованные проверки, таймауты и остановка

Балансировщик SHALL проверять каждую реплику GET /health/ready с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, restore.sh, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает 503 или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в stop_grace_period и в 10 с.

Scenario: Конфигурация согласована

  • WHEN выполняется make student-test
  • THEN тест цепочки таймаутов по compose.yaml, infra/haproxy/haproxy.cfg и scripts/stop-one.sh проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше stop_grace_period и 10 с, timeout server балансировщика больше REQUEST_TIMEOUT_SECONDS, а тот больше суммы таймаутов БД

Scenario: Обнаружение измерено по каждому виду отказа

  • WHEN выполняется make detection
  • THEN три прогона подряд для SIGTERM, docker kill, docker pause и остановки PostgreSQL записывают в evidence/detection/run<N>/*.json время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума плюс допуск замера 0,25 с (запуск docker CLI до сигнала и опрос статистики LB раз в 50 мс); в отчёте приводится диапазон трёх прогонов

Scenario: Остановка по сигналу не теряет запросы

  • WHEN реплике посылается SIGTERM через scripts/stop-one.sh
  • THEN балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого

Scenario: Возврат реплики без преждевременного трафика

  • WHEN остановленная реплика запускается снова под нагрузкой
  • THEN балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (wretr, wredis) за прогон равны 0

Scenario: Зависшая реплика

  • WHEN процесс реплики приостановлен (docker pause) и не отвечает на проверки
  • THEN балансировщик исключает её не позднее чем через 3,5 с, а после docker unpause возвращает в ротацию

Requirement: Поочерёдный отказ под нагрузкой

Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться состояние реплик после остановки (docker ps -a), интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика.

Scenario: Каждая реплика по очереди

  • WHEN выполняется make failover-each
  • THEN evidence/failover-each/summary.json содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её X-Instance-Id не встречался, а после возврата она снова обслуживает запросы; в evidence/failover-each/<hostname>/action.txt после хука записан docker ps -a реплик, где остановлена именно эта реплика

Requirement: Общая идемпотентность под параллельными запросами

Параллельные POST /api/v1/chats/{chat_id}/messages с одним Idempotency-Key и одним телом, распределённые балансировщиком по разным репликам, SHALL создавать ровно одно сообщение и SHALL получать одинаковые ответы 201; тот же ключ с другим телом SHALL получать 409.

Scenario: Серия гонок через LB

  • WHEN выполняется make lb-check (20 раундов по 8 параллельных запросов с одним ключом на раунд)
  • THEN все 160 ответов 201, их обслужили не менее двух реплик, в каждом раунде тела ответов совпадают, в истории ровно одна копия, а другой body получает 409

Requirement: Лимиты и изоляция

Каждый сервис стенда, включая генератор нагрузки, SHALL иметь лимиты CPU и памяти. Ни один сервис SHALL NOT задавать container_name. Опубликованные порты SHALL быть только у балансировщика и только на 127.0.0.1. Секреты SHALL монтироваться только сервисам, которые ими пользуются; volumes данных SHALL принадлежать только своему хранилищу; реплики API SHALL работать с корневой файловой системой только для чтения; внутренняя сеть SHALL быть недоступна снаружи, а генератор нагрузки SHALL видеть только балансировщик.

Scenario: Проверка лимитов и изоляции

  • WHEN выполняется make limits
  • THEN проверка по docker compose config и docker inspect запущенных контейнеров печатает таблицу сервисов с лимитами, портами, секретами, volumes и сетями в evidence/limits.txt и завершается PASS; ни у одного контейнера api нет опубликованных портов

Scenario: Нарушение политики

  • WHEN сервису без необходимости добавлен секрет, порт или container_name, либо снят лимит
  • THEN make limits перечисляет нарушение и завершается ненулевым кодом

Requirement: Поочерёдная замена под нагрузкой и однократные миграции

Оператор SHALL одной командой заменять реплики новой версией образа по одной: сначала миграции применяются один раз отдельным процессом, затем на каждую старую реплику запускается новая, и старая останавливается только после того, как балансировщик видит новую готовой. Число готовых реплик в балансировщике SHALL NOT опускаться ниже исходного. Миграции SHALL быть совместимы с работающей предыдущей версией (только добавление объектов схемы) либо ограничение SHALL быть описано в REPORT.md.

Scenario: Замена под нагрузкой

  • WHEN выполняется make rolling-update
  • THEN evidence/rolling/result.json показывает, что балансировщик ни разу не видел меньше исходного числа готовых реплик, доля ошибок нагрузки не больше 1 %, зонд не потерял записей, а после замены запросы обслуживают только новые контейнеры

Scenario: Обновление с прежней версии

  • WHEN выполняется make rolling-update FROM_REV=<коммит>
  • THEN стенд сначала поднимается на образе, собранном из этого коммита, а затем заменяется текущей версией с теми же гарантиями; журнал замены называет старый и новый образ каждой реплики

Scenario: Миграции один раз

  • WHEN идёт поочерёдная замена
  • THEN migrate запускается один раз до замены первой реплики, реплики схему не меняют, а повторный alembic upgrade head завершается кодом 0 без новых ревизий и изменения данных

Requirement: Достоверность нагрузочного доказательства

Для сохранённого минимума ЛР3 (строка 3.9 README ЛР4) нагрузочный зонд SHALL измерять восстановление по завершению первого успешного POST после последней ошибки, а не по времени самой ошибки. Первый успешный POST после начала действия SHALL завершиться не позже 10 с. Отсутствие успешного ответа после ошибки SHALL приводить к неуспешной проверке. После нагрузки полная история отдельного чата зонда SHALL совпадать с подтверждёнными телами Message, без пропусков и дублей. Нулевое число запросов, пропущенные итерации нагрузки и отсутствие наблюдений LB SHALL NOT давать PASS.

Scenario: Ошибка не подтверждает восстановление

  • WHEN последняя попытка записи завершилась ошибкой либо успешный ответ после неё пришёл позже 10 с от начала действия
  • THEN проверка восстановления завершается неуспешно, даже если сама ошибка возникла раньше 10 с

Scenario: История после действия

  • WHEN поочерёдный отказ или rolling update завершён под нагрузкой
  • THEN зонд читает все страницы своего чата и сравнивает все поля с ответами 201; пропуск, дубль или изменение сообщения дают неуспех

Scenario: Неполная нагрузка или статистика

  • WHEN генератор не выполнил запросов, пропустил итерации либо опрос LB не получил статистику
  • THEN прогон не подтверждает сохранение нагрузки и ёмкости и завершается неуспешно