21 KiB
Лабораторная работа 3 — балансировка и отказ API
Автор: Савин Александр, БВТ2303. Целевая оценка: 5, трек 1 — цена масштабирования
Запуск из чистого clone
Нужны Docker Engine и Compose v2 (docker compose либо docker-compose), Python 3.9+ для проверок. scripts/compose.sh выбирает доступную форму Compose. Образы закреплены: Python 3.11.11-slim, PostgreSQL 16.6-alpine, Valkey 8.0.2-alpine, HAProxy 3.0.5-alpine. Зависимости API — requirements.txt, графиков — requirements-research.txt.
cd mtusi2026lab3
./scripts/bootstrap.sh
# Если 8080 занят, в .env установить APP_PORT=8083.
./scripts/compose.sh config --quiet
./scripts/compose.sh up -d --build
# Дождаться HTTP 200 от /health/ready и двух healthy API:
./scripts/compose.sh ps -a
export BASE_URL=http://localhost:8083 # или свой APP_PORT
make check
make test
make test-idempotency
make test-cache
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
./scripts/compose.sh start api
# Дождаться возвращения двух реплик через LB.
make test-replicas
make test-persistence ACTION_SCRIPT=scripts/restart.sh
Bootstrap создаёт случайный пароль в локальном .env с правами 600, существующий файл не перезаписывает. .env исключён из Git и Docker build context. Пароль передаётся контейнерам через environment — учебное упрощение: оператор Docker может его прочитать. Только LB публикует порт, API/БД/Valkey наружу не опубликованы. Данные соседней lab2 не подключаются и не меняются. На текущей машине lab3 работает на 8083, lab2 остаётся на 8080.
Полная OpenAPI-валидация: установить requirements-dev.txt в venv, затем make validate PYTHON=.venv/bin/python. Остановка с сохранением данных: ./scripts/compose.sh down; возврат: ./scripts/compose.sh up -d. Намеренное удаление учебных данных lab3: ./scripts/compose.sh down -v; для проверок это не нужно.
Архитектура и переход от lab2
Клиент → HAProxy → Compose service api ×2 → общие PostgreSQL и Valkey. PostgreSQL хранит пользователей, сессии, чаты, членство, сообщения и результаты идемпотентных запросов. Valkey — общий необязательный кэш сессий с AOF. Пагинация, Argon2id, проверки прав, expiry/revocation и сверка идентичности кэша с БД перенесены из lab2. Локальных сессий API нет; sticky sessions не используются.
X-Instance-Id равен hostname контейнера и сопоставляется с docker inspect. X-App-Revision показывает сборочную ревизию образа. Секреты в заголовки не попадают. Здесь не заявляется требование lab7 скрывать hostname.
Новый Store создаёт один клиент Valkey с библиотечным пулом на процесс, закрывает при shutdown. Контрольный режим CACHE_CLIENT_MODE=per_request воспроизводит прежнее создание клиента на каждую операцию; обычный режим shared. Обязательный SELECT сессии и сравнение кэшированных данных с PostgreSQL остаются. Повреждённый/чужой/отозванный кэш не определяет личность пользователя.
Readiness, DNS и завершение
Docker-healthcheck использует лёгкий HTTP-probe на socket с сетевым timeout 1s и бюджетом процесса 4s (interval 2s, retries 2); это учитывает холодный запуск вспомогательного Python. HAProxy: roundrobin, активный GET /health/ready раз в секунду, fall=2, rise=1, timeout check=1s. Расчётное обнаружение отказа — около 4 секунд в худшем сочетании двух интервалов/timeout при нормальном планировании; это не SLA при перегрузке. Readiness проверяет PostgreSQL; live — процесс. Valkey не блокирует readiness, поскольку есть fallback в БД.
Docker DNS 127.0.0.11:53 обновляет backend-адреса: server-template допускает до 8 API, hold valid/obsolete=1s. Обновление IP реально проверяется поочерёдной заменой контейнеров с новыми ID/IP, новые hostname должны появиться через LB до остановки старого API.
Uvicorn при SIGTERM прекращает приём, ждёт выполняющиеся запросы до 8 секунд, затем закрывает пул. Compose stop_grace_period=12s. HAProxy: connect=1s, server=10s, client=15s, автоматические retry отключены. Краткие ошибки при обнаружении отказа измеряются; клиент повторяет неопределённый POST сообщения с прежним ключом. Создание чата/пользователя не получает прозрачных retry. stop-one.sh использует сокращённый бюджет 3 секунды, оставляя выбранный контейнер остановленным.
Согласованные миграции и идемпотентность
Мигратор — отдельный one-shot service, API запускаются после его успеха и сами DDL не выполняют. Advisory lock сериализует миграторов; schema_migrations и SQL-версия фиксируются в той же транзакции. Повторный запуск процесса мигратора пропускает применённые версии. Миграция 002 добавляет таблицу/индекс, совместима с работающей схемой lab2; старое приложение, однако, ещё не предоставляет новый контракт идемпотентности.
Область ключа: sender_id + фиксированный POST/маршрут + канонический UUID чата + Idempotency-Key. ASCII-шаблон и длина проверяются. Advisory lock хэша области сериализует конкурирующие повторы между всеми API. Под блокировкой читается результат либо сообщение и JSON ответа записываются одной транзакцией. Побочный эффект и результат атомарны. Прежний body возвращает тот же Message и 201; иной body — 409. Ошибка/rollback не фиксируется. Сессия и членство проверяются заново перед replay.
JSON-порядок не влияет на сравнение, отсутствующий attachment_ids и [] равны. Текст не trim-ится, разные пробелы — разные body. Непустые вложения не входят в lab3. TTL результата — 24 часа с первой записи; истёкший ключ удаляется при следующем обращении к нему. Фоновая очистка не реализована: неиспользуемые истёкшие результаты занимают диск. Таймаут блокировки может дать временную 503, повтор с прежним ключом безопасен.
Лимиты и область общего состояния
Обычный стенд: API по 2 CPU/256 MiB (лимит выбран с запасом для Argon2id и фиксированного 2s timeout публичного resilience-теста), PostgreSQL 1 CPU/512 MiB, Valkey 0.25 CPU/128 MiB, LB 0.25 CPU/64 MiB. CPU-лимиты являются верхними границами, не резервированием: сумма возможных квот превышает 4 vCPU VM, одновременная насыщенная работа всех компонентов не обещается. Пул API max_size=5, min_size=1; две реплики дают до 10 подключений, четыре — до 20 при обычном max_connections=100 PostgreSQL. Лимиты и отсутствие опубликованных API-портов подтверждены в evidence/final-containers.json. container_name в compose.yaml отсутствует.
API_IMAGE/API_REPLICAS/API_CPUS/API_MEMORY/DB_POOL_MAX_SIZE/DB_CPUS/LB_CPUS/CACHE_CLIENT_MODE соответствуют реальным параметрам Compose. Значения .env.example — рабочие defaults; экспериментальные ограничения передаются временно через environment. В исследовании БД намеренно ограничивается до 0.25 CPU, обычный стенд после эксперимента возвращается к 1 CPU.
Rolling update под нагрузкой
# Сначала подготовить новый образ, старый продолжает работать:
API_IMAGE=mtusi-lab3-api:final-v5 ./scripts/compose.sh build --build-arg APP_REVISION=lab3-v5 api
API_IMAGE=mtusi-lab3-api:final-v5 make test-rolling
# Чтобы последующий обычный up использовал этот tag, записать API_IMAGE в .env.
scripts/rolling_update.py работает с одной временной дополнительной репликой (surge=1): создаёт её выбранным образом без пересоздания работающих API, ждёт Docker health (probe на socket, бюджет 4s) и фактический hostname за LB, останавливает/удаляет одну старую реплику. Повторяет для каждой исходной. При ошибке готовности старую реплику не удаляет, оставляет состояние для диагностики. Число экземпляров в ходе нормального обновления — 2→3→2→3→2.
Проверяется смена реальных image IDs и удаление всех исходных container IDs. Новый образ имеет новую сборочную ревизию, API-контракт тот же, SQL-изменений в этом rollout нет. Миграции в ходе rolling не запускаются (--no-deps). Для будущих несовместимых SQL-изменений такой скрипт сам по себе недостаточен: нужен совместимый expand/migrate/contract либо остановка сервиса. Автоматический rollback не реализован.
Четыре клиентских потока одновременно пишут и читают через LB, повторяют неопределённые сообщения с прежними ключами. После обновления проверяется вся история, подтверждённые сообщения и отсутствие дублей. Реальные показатели — evidence/rolling-load.json, смена контейнеров/образов — evidence/rolling-containers.json.
Доказательства
| Критерий | Команда | Доказательство |
|---|---|---|
| Структура и схема | make check; make validate | evidence/check.txt; evidence/validate.txt |
| Публичный API | make test | evidence/smoke.txt |
| Общая сессия и ≥2 настоящих API | make test-idempotency | evidence/idempotency.txt; evidence/final-containers.json |
| 16 конкурентных повторов через разные API | make test-idempotency | 1 сообщение; 409 при ином body; semantic replay; независимость пользователей |
| Отказ с безопасным повтором | make test-failover ACTION_SCRIPT=scripts/stop-one.sh | evidence/failover.txt; evidence/after-public-failover.txt |
| Отказ каждой реплики с восстановлением предыдущей | make test-replicas | evidence/replica-matrix.json: RPS, ошибки, восстановление и состояния контейнеров |
| Сохранность после рестарта API и хранилищ | make test-persistence ACTION_SCRIPT=scripts/restart.sh | evidence/persistence.txt; evidence/before-persistence.txt; evidence/after-persistence.txt |
| Сохранение правил кэша lab2 после оптимизации | make test-cache | evidence/cache-consistency.txt |
| Readiness, timeouts, DNS, SIGTERM | конфигурация + отказ/rolling | infra/haproxy.cfg; compose.yaml; evidence/rolling-containers.json |
| Лимиты, приватные API, отсутствие container_name | config/inspect | compose.yaml; evidence/final-containers.json |
| Замена контейнеров новым образом под нагрузкой | API_IMAGE=… make test-rolling | evidence/rolling-load.json; evidence/rolling-containers.json |
| Однократные согласованные версии миграций | migrate.py, schema_migrations | migrations/; evidence/migrations.txt |
Фактические результаты проверок
Публичный smoke, OpenAPI и регрессии кэша — PASS. Конкурентная проверка: 16 запросов с одним ключом через два API, одно сообщение в истории, конфликтующий body — 409. Защита от подмены идентичности кэша проверена восемью параллельными чтениями; повреждённый кэш, восстановление после cache miss и повторное заполнение после logout не дают чужую/отозванную сессию.
Публичный failover обычного стенда: 65 успешных записей, 3 неудачные попытки, восстановление 3.042s. Скрипт действительно оставил один API остановленным; snapshot сохранён до его восстановления. Повтор с прежним ключом не создал дублей.
| Отказ API | Успешных пар POST+GET | Неудачных попыток | Успешных пар/с | Восстановление, с |
|---|---|---|---|---|
| 228d36b4417c | 77 | 6 | 4.806 | 3.072 |
| e0560ed00847 | 84 | 5 | 5.404 | 2.666 |
Полный restart — PASS: прежний токен прочитал прежние подтверждённые сообщения. У пяти контейнеров API×2/DB/Valkey/LB изменился StartedAt при сохранении ID и volumes. Финальная конфигурация содержит две healthy API с лимитом 2 CPU/256 MiB каждая; опубликован только LB:8083.
Зафиксированный rolling при четырёх клиентских потоках (API по 1 CPU, более тесный бюджет, чем обычные 2 CPU): 902 успешные пары, 56 неудачных попыток за 34.87s; 25.868 успешных пар/с. p50/p95/p99 успешной пары: 16.886 / 461.635 / 877.331 мс. Все исходные container IDs удалены, image IDs изменились, подтверждения сохранены, дублей 0. После выбора окончательного обычного CPU-лимита повторены smoke, идемпотентность, публичный failover, матрица каждого отказа и persistence.
Ошибки переходного периода измерены и не скрываются: LB исключает backend после обнаружения отказа, разрыв выполняющегося запроса возможен. Это локальная проверка под нагрузкой, не zero-downtime SLA. RPS матрицы/rolling считается по успешным парам POST+GET и фактическому времени сценария, включая финальную проверку истории; эти клиенты работают с хоста. Их значения не следует напрямую сравнивать с RPS одних POST генератора внутри Docker-сети.
Уровень 5, трек 1
Законченная методика, гипотезы, таблицы и ограничения находятся в RESEARCH.md. Выполнены 42 запуска: 18 для сравнения 1/2/4 API, 18 для насыщения/CPU БД, 6 для улучшения пула Valkey. Каждый — 2 секунды прогрева и 10 секунд измерения, три повтора каждой конфигурации. Генератор работает в Docker-сети через LB. Сырые latencies/ошибки, CPU/RAM, лимиты, SHA образов, счётчики БД/Valkey и manifest параметров сохранены в evidence/scaling/.
При фиксированном API-бюджете 1 CPU/1024 MiB средний throughput для 1/2/4 реплик составил 639.5 / 470.3 / 349.8 POST/с. При растущем бюджете (каждой API 0.5 CPU/256 MiB) — 499.7 / 460.8 / 429.9 POST/с. Рост реплик сам по себе не дал улучшения. В серии growing БД занимала полную квоту 0.25 CPU; изменение только БД до 1 CPU подняло throughput при четырёх API с 448.3 до 952.9 POST/с в отдельной серии saturation. Наблюдаемая область насыщения исходной конфигурации — около 400–500 POST/с при c≈16; c=64 увеличило p95 до 425.2 мс без прироста throughput.
Подтверждённое изменение кода: общий пул Valkey вместо клиента на каждый запрос. При одинаковых ресурсах среднее число новых соединений сократилось с 5422.7 до 2.3 за запуск; throughput вырос с 445.0 до 584.0 POST/с (+31.3%), p95 снизился с 124.1 до 82.5 мс. Разброс исходного варианта большой, интервалы min–max перекрываются: этот прирост не является универсальной гарантией. Сокращение churn соединений подтверждено непосредственно счётчиком Valkey.
Графики: scaling.png, saturation.png, cache-improvement.png. Рядом находятся SVG, summary.csv, summary.json и исходные JSON каждого повтора. Скрипты research_scaling.py, benchmark.py, plot_scaling.py и summarize_research.py воспроизводят результаты и представление.
Ограничения
Защищён отказ одного процесса API. LB, БД и Docker host не реплицированы; потеря узла или volumes не покрывается. Volume не является backup. Три коротких повтора в VM, синхронные SQL-операции в async-обработчиках, растущая БД и closed-loop генератор ограничивают выводы. Не заявляются универсальная производительность, выживание узла БД, доказанное исчерпание RAM, полноценный production deployment или точная локализация следующего bottleneck после увеличения CPU БД. Подробности — RESEARCH.md.