Files
mtusi2026lab3/README.md
T
2026-11-03 20:49:07 +03:00

18 KiB
Raw Blame History

Лабораторная 3. Балансировка и отказ API-реплики

Запустить несколько взаимозаменяемых экземпляров API за единой точкой входа и сохранить корректность при остановке одного из них.

Это skeleton, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.

Карта курса · Процесс fork/PR · OpenAPI · Семантика API · Проверки · Отчёт · Примеры JSON · Памятка преподавателю

Откуда начинаем

Нужен минимум lab2: PostgreSQL, общие действующие сессии, миграции. Добавляются X-Instance-Id и обязательный Idempotency-Key при отправке сообщения.

Архитектура: Клиент → LB → API × 2+ → общие PostgreSQL и хранилище сессий. Compose или Swarm — на выбор.

Реализованный запуск Compose + Nginx

В этой реализации публичный порт есть только у Nginx. API масштабируется как один Compose-service без container_name; сессии, сообщения и результаты идемпотентности находятся в общей PostgreSQL. Redis используется только как необязательный общий cache с безопасным fallback в PostgreSQL.

Из чистого clone выполните одну последовательность (после копирования .env.example замените локальный пароль):

cp .env.example .env
# отредактировать DATABASE_PASSWORD в .env
docker compose --env-file .env build api
docker compose --env-file .env up -d postgres redis
docker compose --env-file .env run --rm migrate
docker compose --env-file .env up -d --scale api=2 api nginx
curl --fail http://localhost:8080/health/ready

migrate — отдельный one-shot процесс; в API Flyway отключён. При обновлении схемы сначала выполняется совместимая миграция той же командой, затем API заменяются по одной. Nginx 1.27.4 обновляет адреса api через Docker DNS каждые 2 секунды, применяет least_conn, не использует sticky session и повторяет ошибку соединения/502/503/504 на другой реплике. Readiness проверяет завершение V3-схемы, доступность PostgreSQL и состояние Spring ACCEPTING_TRAFFIC.

Проверки после запуска:

make test
make test-idempotency
chmod +x scripts/stop-one.sh scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh

В Windows PowerShell те же проверки можно выполнить с scripts/stop-one.cmd и scripts/restart.cmd; .sh остаются основными POSIX hooks для CI/защиты.

test-idempotency одновременно отправляет 32 одинаковых запроса и требует, чтобы ответы пришли минимум от двух X-Instance-Id, но в истории появилось ровно одно сообщение. stop-one.sh сопоставляет полученный X-Instance-Id с hostname контейнера и останавливает только эту API-реплику. После демонстрации её можно вернуть командой:

docker compose --env-file .env up -d --scale api=2 api

Проверки уровня 4

Обе реплики последовательно останавливаются с восстановлением между опытами:

make test-failover-each \
  ACTION_SCRIPT=scripts/stop-one.sh \
  RESTORE_SCRIPT=scripts/restore-api.sh

В Windows используйте .cmd варианты. Тест сохраняет по каждой реплике successful RPS, число ошибок и время первой успешной операции после stop.

Эквивалент rolling update для Compose — последовательная замена каждого исходного API-контейнера с ожиданием readiness новой реплики перед заменой следующей. Проверка одновременно держит четыре потока записи:

make test-rolling ACTION_SCRIPT=scripts/rolling-update.sh

Nginx обновляет Docker DNS раз в 2 секунды. Сетевой отказ определяется не позднее connect timeout 500 ms, зависший ответ — read timeout 4 s; адрес пассивно исключается на 2 s после первой ошибки. Поэтому верхняя граница обнаружения одного неотвечающего backend — 4 s, а две upstream-попытки укладываются примерно в 8.5 s. Docker readiness каждой API проверяется раз в 2 s с timeout 2 s. Nginx OSS использует readiness при начальном/операторском запуске через Compose и пассивное исключение во время работы.

Для POST /chats/{id}/messages Nginx может повторить запрос на второй backend даже после начала отправки: тело буферизуется, а обязательный общий Idempotency-Key делает такой retry безопасным. Для остальных POST параметр non_idempotent не включён, чтобы не размножать пользователей или чаты.

Отказ узла: отдельный трёхузловой Swarm-стенд

Дополнительные студенческие проверки находятся в student_tests/; исходные тесты курса в tests/ не перемещаются, Spring-тесты остаются в src/test/java.

Для трека отказа узла добавлен одноразовый локальный стенд из трёх настоящих Docker daemons в privileged DinD-контейнерах: manager и два workers. Он не заменяет основной Compose-стенд и использует отдельный порт 18080.

make swarm-up
make test-node-failover PYTHON=python
make swarm-down

swarm-up строит образы из текущего исходного кода, публикует их в одноразовый локальный registry, доступный всем узлам, создаёт overlay network, отдельно выполняет миграцию и запускает API с двумя replicas и max_replicas_per_node=1. Тест выбирает worker с API-задачей и жёстко останавливает весь Docker daemon этого узла. Swarm должен создать новую API-задачу на свободном узле; через LB одновременно выполняются чтения/записи, после чего проверяются старые и подтверждённые во время отказа сообщения.

Защищён только API worker. PostgreSQL, Redis и Nginx закреплены на manager; PostgreSQL использует локальный volume и не реплицирован. Потеря manager/DB узла не переживается и в отчёте не заявляется. Один manager также означает SPOF control plane; DinD underlay и физический host остаются SPOF эксперимента.

Что сделать

  1. Выберите Compose + Nginx/HAProxy/Traefik либо Docker Swarm. Для выбранного варианта дайте одну последовательность запуска.
  2. Уберите локальные сессии/другие данные, от которых зависит корректность, из API. Миграции выполняйте отдельно и согласованно, а не гонкой всех реплик.
  3. Настройте балансировщик, проверки готовности, DNS/обновление backend-адресов и graceful shutdown. Не закрепляйте клиента sticky session как способ исправить раздельное состояние.
  4. Реализуйте общую идемпотентность отправки сообщения. Проверьте одинаковый ключ одновременно через разные реплики.
  5. Подготовьте явный action script, останавливающий одну выбранную API-реплику, и продемонстрируйте чтение/запись во время отказа.

Оценка «3»: работающий минимум

  • Весь стенд описан в compose.yaml или stack.yaml, запускается документированной командой. Не менее двух API-реплик, одна публичная точка входа, одна общая БД и общее хранилище сессий.
  • Разные запросы одного пользователя обслуживаются разными репликами без повторного входа. Это видно по X-Instance-Id. Доступ через LB — основной проверяемый маршрут.
  • Можно остановить любую одну API-реплику при работающей другой: не позднее 10 секунд продолжаются новые чтения/записи, подтверждённые сообщения доступны. Краткие ошибки/оборванные запросы во время обнаружения отказа измеряются и допустимы.
  • Повтор POST сообщения с тем же Idempotency-Key не создаёт дубль, включая конкурентный повтор и переключение реплики. Неподтверждённую запись клиент может безопасно повторить с тем же ключом.
  • make test, persistence и failover-сценарий проходят; для failover проверяется наличие ≥2 наблюдаемых реплик. Для Swarm сборка образа и его доступность узлам описаны отдельно.

Оценка «4»: уровень стажёра/джуна

Весь уровень 3 и все пункты ниже:

  • Health/readiness, timeouts и прекращение приёма при SIGTERM настроены согласованно; LB исключает недоступный backend. Укажите период проверок и максимальное время обнаружения отказа.
  • Последовательно остановите каждую API-реплику (восстанавливая предыдущую); соберите RPS, ошибки и время восстановления. Общая идемпотентность проверяется параллельными запросами с одним ключом.
  • Контейнеры имеют CPU/RAM-лимиты, API не публикуют порты наружу в обход LB; секреты и хранилища общие только там, где нужно. Нет container_name, мешающего масштабированию одного Compose-service.
  • Rolling update или эквивалентная поочерёдная замена проверена под нагрузкой. Миграции запускаются однократно и совместимы с работающей версией либо ограничение честно описано.

Оценка «5»: исследование и доказанный результат

Весь уровень 4 и один законченный трек на выбор. Приведите гипотезу, повторяемую методику, результаты и ограничения.

Трек 1. Цена масштабирования. При фиксированном суммарном CPU/RAM сравните 1/2/4 API-реплики на одном профиле нагрузки; затем проведите серию с ростом ресурсов. Найдите saturation point БД/LB/пула и покажите, почему рост реплик перестаёт помогать. Дайте исходные данные, графики и одно подтверждённое улучшение.

Трек 2. Отказ узла. Расширьте стенд до нескольких узлов, покажите перенос API при потере узла и разберите оставшиеся SPOF (LB, DB, storage). Для заявленной защищённой зависимости покажите реальный failover и сохранность данных. Если DB не реплицирована, не заявляйте выживание её узла.

Как начать и проверить

# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check

# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test

.env.example, compose.example.yaml и contracts/infrastructure.json описывают настройки и роли компонентов. compose.example.yaml — список ролей с пустым services, не запускаемый стенд. Реализуйте свой compose.yaml/stack.yaml, закрепите версии образов, заполните локальный .env и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.

# Compose-вариант после реализации:
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь /health/ready; затем make test.
# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md.

Примеры запросов доступны в examples/requests.http, примеры JSON — в contracts/examples.json. Для полной проверки схемы (по желанию локально; CI делает её автоматически):

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по tests/README.md, остальные доказательства приведите в отчёте.

Сценарий защиты

  1. Запустить стенд и показать ≥2 разных X-Instance-Id через LB с одной сессией.
  2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Скрипт теста выполняет запросы во время action, учитывает ошибки и повторяет сообщения с исходным ключом.
  3. Показать, какой контейнер действительно остановлен; заголовок сам по себе не доказательство разных процессов. Повторить для второй реплики после восстановления первой.
  4. Проверить restart всего стенда с сохранением volumes и неизменным токеном. Для 4/5 — соответствующие эксперименты.

Что должно быть в PR

compose.yaml или stack.yaml, конфигурация LB, scripts/restart.sh, scripts/stop-one.sh, Dockerfile, миграции, результаты отказов.

Заполните REPORT.md и шаблон PR, укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах объявленных переходов.

Вопросы на защите

  • Чем отказ процесса отличается от отказа узла?
  • Почему depends_on/healthcheck сами по себе не являются балансировщиком?
  • Какие POST можно повторять после timeout и что защищает Idempotency-Key?
  • Что сломается при увеличении числа API, если сессии находятся в локальной памяти?

Первичные материалы