2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00
2026-11-15 22:00:21 +03:00

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

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

Реализация использует FastAPI, PostgreSQL, Redis как необязательный профильный кэш и HAProxy. Единственная опубликованная точка входа — HAProxy; API-реплики и хранилища находятся во внутренней сети Compose. UI не требуется.

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

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

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

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

Что сделать

  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 не реплицирована, не заявляйте выживание её узла.

Запуск стенда

Требуются Docker Engine/Desktop с Compose v2 и Python 3.9+ на машине, с которой запускаются проверки. Образы приложений/зависимостей закреплены в compose.yaml и Dockerfile.

[ -f .env ] || cp .env.example .env
mkdir -p secrets
[ -f secrets/database_password ] || openssl rand -hex 32 > secrets/database_password
chmod 600 secrets/database_password

docker compose --env-file .env config --quiet
docker compose --env-file .env build api migrate
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 load_balancer

# Дождитесь готовности и выполните публичный контракт:
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
make check
make test
make test-grade4

# Скрипты отказов должны быть исполняемыми:
chmod +x scripts/stop-one.sh scripts/restart.sh scripts/rolling-restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

Для независимой проверки каждой реплики получите aliases, наблюдаемые как X-Instance-Id, затем явно выберите target. После каждого прогона восстановите обе реплики:

for c in $(docker compose ps -q api); do docker inspect --format '{{.Config.Hostname}}' "$c"; done
make test-failover-target TARGET_INSTANCE_ID=alias-1 OUTPUT=evidence/failover-api1.json
docker compose --env-file .env up -d --scale api=2 api
make test-failover-target TARGET_INSTANCE_ID=alias-2 OUTPUT=evidence/failover-api2.json
docker compose --env-file .env up -d --scale api=2 api

Уровень 4: запустите make load OUTPUT=evidence/rolling-restart-load.json в одном терминале и make rolling-restart в другом; соберите вывод обоих процессов. make rolling-restart поочерёдно завершает каждый процесс с SIGTERM, ожидает readiness и только затем переходит к следующей реплике.

Эксперимент трека 5 записывает каждый запуск как отдельный JSON, сводки CSV/JSON и SVG-график:

python3 scripts/benchmark.py --duration 10 --concurrency 8 --repeats 3

Скрипт сравнивает 1/2/4 реплики при общем лимите API 1 CPU/512 MiB и две конфигурации с увеличенными суммарными лимитами. Увеличение API-реплик и нагрузка создают синтетические данные в учебной PostgreSQL. Не публикуйте секреты; raw output содержит только метрики.

Обычная остановка сохраняет volumes; намеренный сброс удаляет учебную БД и Redis:

docker compose --env-file .env down       # сохранить данные
docker compose --env-file .env down -v    # намеренно удалить volumes и тестовые данные

Для полной OpenAPI-валидации:

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

make test проверяет контракт, а не инфраструктурную оценку. Persistence, failover, последовательный рестарт и нагрузочный трек проверяются отдельными командами; доказательства и ограничения приведены в REPORT.md.

Офлайн-проверка

make check

Примеры запросов доступны в 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, если сессии находятся в локальной памяти?

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

S
Description
No description provided
Readme
517 MiB
Languages
Python 93.6%
Makefile 3.4%
Shell 3%