163 lines
26 KiB
Markdown
163 lines
26 KiB
Markdown
# Лабораторная №3 — Балансировка и отказ API-реплики
|
||
|
||
Автор: **Дугина Александра, БПИ2301**. Целевая оценка: **4**.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Desktop с Compose v2, Python 3.11+ и make. На использованном Mac Python хоста — 3.13, контейнера — 3.11.16.
|
||
Все команды выполняются из **mtusi2026lab3**.
|
||
|
||
```sh
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -r requirements-dev.txt
|
||
scripts/up.sh
|
||
export BASE_URL="http://localhost:$(sed -n 's/^PUBLIC_PORT=//p' .env)"
|
||
curl -i "$BASE_URL/health/ready"
|
||
make check
|
||
make validate PYTHON=.venv/bin/python
|
||
make test
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
scripts/restore.sh
|
||
python3 scripts/wait-ready.py
|
||
```
|
||
|
||
`scripts/up.sh` вызывает bootstrap, `docker compose --env-file .env config --quiet`, сборку и запуск, ожидает две реплики через LB.
|
||
`bootstrap.py` создаёт случайный пароль PostgreSQL, DSN в `secrets/` и `.env`, выбирает свободный порт 8080–8099 только при отсутствии `.env`. Существующие настройки не заменяет. В текущем запуске выбран **127.0.0.1:8080**. При уже созданном `.env` и занятом порте меняют только PUBLIC_PORT своей lab3. Чужие контейнеры не останавливаются.
|
||
`secrets/`, `.env` игнорируются Git; локальные файлы создаются с umask 077. Compose secrets монтирует их только в нужные контейнеры. Redis доступен исключительно во внутренней сети и не содержит токены в открытом виде.
|
||
`scripts/compose.sh` фиксирует каталог проекта и `.env`, на macOS добавляет Docker credential helper в PATH.
|
||
Swagger UI: `http://localhost:8080/docs`; `/openapi.json` отдаёт обязательный контракт без изменения исходного файла.
|
||
|
||
Безопасная остановка: `scripts/compose.sh stop`. Повторный запуск: `scripts/up.sh`.
|
||
`restart.sh` перезапускает API, PostgreSQL, Redis и LB, не удаляет контейнеры/volumes и не меняет секреты.
|
||
Данные живут в `mtusi2026lab3_postgres_data` и `mtusi2026lab3_redis_data`; сеть — `mtusi2026lab3_default`.
|
||
Удаление учебных данных — отдельная намеренная административная операция, при выполнении работы не применялась. Обычные start/restart/down без удаления volumes данные не очищают.
|
||
|
||
## Архитектура и версии
|
||
|
||
```text
|
||
клиент → 127.0.0.1:8080 → HAProxy → api × 2 (Uvicorn/FastAPI)
|
||
├── PostgreSQL: данные, сессии, идемпотентность
|
||
└── Redis: общий кэш профилей сессий
|
||
```
|
||
|
||
| Компонент | Версия | CPU | RAM |
|
||
|---|---|---:|---:|
|
||
| API, каждая реплика | Python 3.11.16 slim-bookworm, FastAPI 0.115.12, Uvicorn 0.34.2 | 0,75 | 384 MiB |
|
||
| Мигратор | тот же образ приложения, отдельный one-shot процесс | 0,5 | 256 MiB |
|
||
| PostgreSQL | 16.8-bookworm | 1 | 512 MiB |
|
||
| Redis | 7.4.2-alpine | 0,25 | 128 MiB |
|
||
| HAProxy | 3.0.9-alpine | 0,5 | 128 MiB |
|
||
|
||
Остальные зависимости закреплены в `requirements.txt`: psycopg 3.2.6, psycopg-pool 3.2.6, redis-py 5.2.1, Argon2-cffi 23.1.0, Pydantic 2.11.4. Образы поддерживают ARM64. Docker Engine 28.0.1, Compose 2.33.1-desktop.1.
|
||
Хост: MacBookPro18,3, Apple M1 Pro ARM64, 8 CPU, 16 GiB RAM; Docker VM имеет 8 CPU и 8 218 316 800 байт RAM. Полные условия — `evidence/environment.txt`.
|
||
|
||
Перенесены собственные `src/`, SQL начальной схемы, зависимости, Dockerfile и тест авторизации из lab2 (`bd34c1050a61d92faa30468eace4e4dadea306c3`, та же рабочая ветка). Lab2 читалась, её файлы и данные не изменялись. Контракты, публичные тесты и исходный README lab3 сохранены. Добавлены балансировка, заголовок процесса, отдельный мигратор, общая идемпотентность, эксплуатационные скрипты, эксперименты. API — один Compose-service с `deploy.replicas: 2`, без `container_name`, без опубликованных портов. Публичен только LB на loopback.
|
||
|
||
HAProxy выбран за активные HTTP readiness-проверки и штатный Docker DNS resolver/server-template; это позволяет масштабировать один сервис без перечня двух фиксированных имён. Round robin распределяет HTTP-запросы без cookie/sticky session. В конфигурации десять слотов backend (поддерживаемый предел данного учебного конфига). Незаполненные слоты переходят в DNS maintenance. Логи ошибок, переходы UP/DOWN и HTTP-статусы пишутся в stdout контейнера.
|
||
|
||
## Состояние, контракт и идемпотентность
|
||
|
||
PostgreSQL — источник истины для пользователей, membership, чатов, сообщений и сессий. Пароли — Argon2id: time_cost=3, memory_cost=65536 KiB, parallelism=4. Basic используется только для выдачи случайного токена с 256 битами энтропии. В БД хранится SHA-256 токена и expiry; TTL по умолчанию 3600 секунд, рестарт его не продлевает. На каждом защищённом запросе БД проверяет expiry/revoked_at. Redis кэширует профиль пользователя по хешу токена, но не заменяет проверку сессии: отказ Redis допускает чтение профиля из PostgreSQL. Сессионное состояние не локально. Logout отзывает сессию в PostgreSQL и удаляет кэш. Redis использует AOF с appendfsync always и отдельный volume.
|
||
|
||
Доступ к чату проверяется перед операцией; посторонний получает 404. Ошибки соответствуют контракту, request_id в JSON совпадает с X-Request-Id. Каждый созданный API ответ, включая ошибки/health/204, получает X-Instance-Id (случайный UUID при импорте приложения) и X-Request-Id. ID стабилен в жизни одного Uvicorn-процесса, после рестарта меняется. LB-ошибки соединения могут не иметь этих заголовков.
|
||
|
||
Пагинация keyset по `(created_at, id)`, limit 1–100; cursor содержит область user/chat и ID последней записи, проверяется принадлежность. История читается непосредственно из PostgreSQL без устаревающего кэша. При конкурентных вставках между страницами нет snapshot: поздний COMMIT с более ранним created_at может оказаться позади уже выданного cursor. Для неизменной истории обход без повторов; это соответствует контракту. Вложения не добавлены: CreateMessage lab3 принимает только text.
|
||
|
||
`Idempotency-Key` обязателен, ASCII `[A-Za-z0-9._:-]{1,128}`. Таблица `message_requests` имеет PK `(chat_id, sender_id, key)`; HTTP-метод и тип пути фиксированы единственным POST сообщений. Записи не удаляются: защита дольше 24 часов (плата — рост таблицы).
|
||
|
||
В одной транзакции выполняются:
|
||
1. INSERT запроса с ON CONFLICT DO NOTHING.
|
||
2. Победитель создаёт сообщение и связывает результат с ключом.
|
||
3. Конкурирующий INSERT ожидает завершения транзакции победителя. Следующий SELECT в READ COMMITTED видит готовое сообщение. Одинаковый text возвращает тот же объект и 201; отличный — 409.
|
||
|
||
COMMIT атомарен для сообщения и результата. При исключении обе записи откатываются; транзиентные ошибки не закрепляются. Другие пользователи/чаты имеют независимые ключи. Аутентификация и доступ проверяются заново до повтора. Участники неизменяемы в обязательном API. Синхронная транзакция отправки вынесена в thread pool, поэтому HTTP-запросы могут реально конкурировать и внутри одного процесса. Локального словаря ключей нет.
|
||
|
||
## Готовность, отказ и остановка
|
||
|
||
`/health/live` проверяет жизнь процесса. `/health/ready` выполняет SELECT 1 в обязательной PostgreSQL; Redis не критичен благодаря fallback. Если PostgreSQL недоступен — 503 в общем формате. В `evidence/readiness.json` зафиксирован реальный эксперимент: после stop PostgreSQL у обеих API live=200 и ready=503; после stop Redis ready=200 и профиль читается через fallback. Оба хранилища затем восстановлены. Пул: 1–10 соединений на API, ожидание до 5 с, connect_timeout 5 с, statement_timeout 5 с.
|
||
|
||
HAProxy проверяет каждую реплику раз в 1 с, при изменении состояния fastinter 500 мс, fall=2, rise=2, timeout check/connect=1 с. Для отказа соединения практический бюджет обнаружения порядка 2–4 с при свободном Docker-host; это расчёт по настройкам, не гарантия при остановке всей VM. Read timeout сервера 8 с, клиента 10 с. Docker-health API — каждые 2 с, timeout 3 с, retries 3, start_period 5 с; сам Docker-health не маршрутизирует запросы. Решение о маршрутизации принимает HAProxy.
|
||
|
||
Docker DNS `127.0.0.11:53`, hold valid/obsolete/NX=1 с, resolver retry/timeout=1 с обновляет server-template. Отдельный тест реально изменил IP работающей API-реплики и подтвердил её повторную доступность через LB (`dns-change.json`). Для занятия старого IP кратковременно запускалась третья настоящая API-реплика; после теста она удалена без удаления данных. Проверка включает Docker CLI и ожидание, поэтому её 9,420 с — не чистый DNS latency.
|
||
|
||
PID 1 — Uvicorn, STOPSIGNAL SIGTERM. При сигнале сервер закрывает listener, ждёт активные запросы до 4 с; shutdown hook закрывает пул. Compose даёт 6 с до SIGKILL. После закрытия listener HAProxy исключает backend активными проверками. Полного drain перед остановкой нет: краткие ошибки допустимы и измерены. LB не делает автоматический replay POST (`retries 0`): неопределённую запись повторяет клиент с тем же ключом. `stop-one.sh` опрашивает прямой health внутри только API-контейнеров, точно сопоставляет TARGET_INSTANCE_ID и останавливает найденный контейнер; остальные компоненты не трогает. Восстановление — `scripts/restore.sh`, затем ожидание двух ID.
|
||
|
||
## Миграции и rolling update
|
||
|
||
Миграции не запускаются из API/startup и не подключены к docker-entrypoint PostgreSQL. Сервис migrate ждёт healthy PostgreSQL; API ждут `service_completed_successfully`. SQL-файлы применяются в одной транзакции под `pg_advisory_xact_lock(310026)` и записываются в `schema_migrations`. Это также сериализует случайный повторный запуск runner. Времена применения двух миграций зафиксированы; явный повтор runner вывел Already applied, таблица до/после совпала. Восстановление API не запускает зависимости. Мигратор может вызываться повторно при полном `up`, но **каждая версия схемы применяется ровно один раз**, а не каждым API.
|
||
|
||
002 — добавление таблицы без изменения старых колонок, совместимо с работающей API lab2. При демонстрационном обновлении схема не менялась; версии образов старого/нового API записаны в JSON. Для будущих несовместимых миграций этот скрипт не гарантирует rolling: нужен expand/contract, обратная совместимость либо согласованное окно обслуживания. Автоматического rollback схемы нет.
|
||
|
||
```sh
|
||
scripts/compose.sh build api
|
||
# При НОВЫХ совместимых миграциях отдельно, до замены API:
|
||
scripts/compose.sh run --rm --no-deps migrate
|
||
scripts/rolling-update.sh
|
||
# Или эксперимент сразу с 4 writers и проверкой подтверждений:
|
||
python3 student-tests/scenarios.py rolling --output evidence/rolling-update-new.json
|
||
```
|
||
|
||
Алгоритм: сохранить два исходных контейнера; проверить survivor; остановить/удалить только первый API; `up --no-deps --no-recreate --scale api=2 api` создаёт недостающий контейнер новым образом, не пересоздаёт survivor; дождаться readiness нового и наблюдения обоих ID через LB; затем заменить второй исходный. При ошибке готовности дальнейшая замена прекращается. Номера Compose-контейнеров могут увеличиваться; скрипты не зависят от суффиксов 1/2. Это поочерёдная замена Compose на одном host, не встроенный rolling deploy оркестратора, не автоматический rollback и не нулевые ошибки.
|
||
|
||
## Команды и результаты испытаний
|
||
|
||
```sh
|
||
python3 student-tests/check_auth.py
|
||
python3 student-tests/scenarios.py idempotency --output evidence/idempotency.json
|
||
python3 student-tests/scenarios.py failover --target-index 0 --duration 15 --output evidence/failover-replica-1.json
|
||
python3 student-tests/scenarios.py failover --target-index 1 --duration 15 --output evidence/failover-replica-2.json
|
||
python3 student-tests/baseline.py
|
||
python3 student-tests/scenarios.py rolling --output evidence/rolling-update.json
|
||
python3 student-tests/scenarios.py rolling --output evidence/rolling-continuity.json
|
||
python3 student-tests/dns.py
|
||
python3 student-tests/readiness.py
|
||
# Полный повтор (заменяет соответствующие evidence новыми результатами):
|
||
scripts/verify.sh
|
||
```
|
||
|
||
Публичные make check, validate, test, test-persistence и test-failover прошли. У persistence сняты sanitized StartedAt/ID всех контейнеров до/после, включая оба хранилища; токен сохранился. Собственный тест: 24 параллельных одинаковых POST обслужены обеими репликами, один Message и одна копия в истории; повтор с другим body — 409, чужой чат — 404, отозванный токен — 401, независимые user/chat scope, отсутствующий/неверный ключ — 400. Старение тестовых ключей до 25 часов не отменило повтор. Общая сессия и чтение подтверждённого сообщения наблюдались на обеих репликах.
|
||
|
||
| Эксперимент (4 writers) | Duration, с | Успешные / ошибки | Ошибки, % | Successful RPS | p50/p95/p99, мс | Восстановление, с | Потеря подтверждённых |
|
||
|---|---:|---:|---:|---:|---|---:|---:|
|
||
| Baseline, public load.py, 30 с | 30,077 | 11112 / 0 | 0 | 369,451 | 9,070 / 15,647 / 63,266 | — | не оценивается этим генератором |
|
||
| Отказ первой | 16,683 | 4803 / 366 | 7,0807 | 287,901 | 9,761 / 25,936 / 69,031 | 3,277 | 0 из 4804 |
|
||
| Отказ второй после восстановления первой | 16,741 | 4282 / 322 | 6,9939 | 255,782 | 11,185 / 28,477 / 69,385 | 2,879 | 0 из 4283 |
|
||
| Rolling новым образом | 19,218 | 4768 / 453 | 8,6765 | 248,103 | 9,335 / 51,021 / 80,478 | см. ниже | 0 из 4769 |
|
||
| Дополнительный rolling, тот же образ | 20,325 | 5064 / 270 | 5,0619 | 249,150 | 11,866 / 36,704 / 71,268 | см. ниже | 0 из 5065 |
|
||
|
||
В первом эксперименте остановлен container `7d2957677a35…`, alias `d2f38075-ad18-4b40-b025-0b6b75b5deec`; во втором — **другой исходный контейнер** `cdc714ebeb09…`, alias `0fa5e6d8-e471-4f44-992c-42c530dceb1f`. JSON хранит полные IDs и факт Running=false после hook. Первый восстановлен до второго эксперимента; после обоих снова наблюдались две реплики. Чтение полной истории выполнялось при остановленной реплике прежней сессией; подтверждены запись и доступность всех подтверждений.
|
||
|
||
Время восстановления измерено от начала action до завершения первого успешного POST, начатого **после возврата** action. Это консервативная оценка с затратами Docker CLI, обе менее 10 с. Длительность собственных сценариев включает завершение worker/сборщика ресурсов, поэтому больше запрошенного 15-секундного интервала. Успешные RPS посчитаны по этому полному интервалу. Между экспериментами данные не очищались.
|
||
|
||
Rolling новым образом: обе замены заняли 3,447 и 6,235 с; весь action (с подготовкой) 12,639 с. Поле first_success_after_action=12,666 с означает первый POST **после завершения двух замен**, а не 12-секундный простой! Дополнительный эксперимент специально измерил непрерывность: **3424 успешных запроса начаты во время action**, максимальный промежуток между успешными завершениями **1,000 с**; прежняя сессия и все 5065 подтверждений сохранены. Версии образов первого rolling действительно отличаются, повторный rolling проверяет замену контейнеров тем же образом.
|
||
|
||
Методика: synthetic POST text, closed loop, уникальные ключи, 4 потока, без прозрачного retry в измерении throughput. Для отказов 2 с до воздействия, далее нагрузка до ~15 с. Все тестовые объекты синтетические. На baseline уже были данные предшествующих проверок, размер БД в конце — `dataset.txt`. CPU/RAM сняты параллельно, интервалы нерегулярны (docker stats и Docker CLI добавляют задержку); peaks — максимум **из выборок**, не абсолютный пик. Baseline дал 9 выборок; API суммарно до 120,70% CPU / 118,69 MiB, PostgreSQL 41,47% / 53,01 MiB, HAProxy 17,39% / 13,63 MiB, Redis 4,16% / 9,33 MiB. CPU 100% означает одно ядро; API в таблице суммируются. Детали остальных экспериментов — `resources-summary.json`, raw samples — в JSON экспериментов.
|
||
|
||
Это единичные небольшие генераторы на одном ноутбуке: coordinated omission, overhead Python/клиента, latency только успешных ответов, нет определения saturation point. Предельная производительность и SLA production не заявляются. Baseline выполнялся до финального изменения Swagger; путь сообщений и транзакций тот же. Краткие 503/обрывы при остановке не скрыты; нужны retry клиента с тем же ключом и более аккуратный drain для уменьшения ошибок.
|
||
|
||
## Соответствие всем критериям уровней 3 и 4
|
||
|
||
| Уровень / требование | Проверка / реализация | Фактическое доказательство |
|
||
|---|---|---|
|
||
| 3: воспроизводимый Compose, 2+ настоящих API | up.sh, capture-state.py, CPU/port metadata | containers.json, containers.txt |
|
||
| 3: одна публичная точка, общие БД/сессии | compose.yaml, public smoke и persistence | smoke.txt, persistence.txt |
|
||
| 3: одна сессия на разных репликах | scenarios.py idempotency, me и история на двух ID | idempotency.json |
|
||
| 3: X-Instance-Id реального процесса | опрос внутри контейнера, сопоставление hook | failover-replica-1.json, failover-replica-2.json |
|
||
| 3: новые чтения/записи ≤10 с после отказа любой одной | последовательный отказ каждой, полная история до restore | оба failover-replica JSON: 3,277 / 2,879 с |
|
||
| 3: подтверждённые сообщения не потеряны | сравнение всех объектов в полной истории | оба failover-replica JSON, lost_confirmed=0 |
|
||
| 3: общая идемпотентность, включая concurrent/replay | PostgreSQL транзакция, PK; 24 запроса на обе реплики | idempotency.json |
|
||
| 3: make test | публичный контрактный сценарий | smoke.txt |
|
||
| 3: persistence и failover tests | make test-persistence, make test-failover | persistence.txt, failover-public.txt |
|
||
| 4: health/readiness, timeout, SIGTERM, исключение backend | Dockerfile, HAProxy checks, настоящие stop | оба failover JSON; lb-events.txt |
|
||
| 4: восстановление / DNS backend | restore.sh; реальная смена IP | dns-change.json, instances_after_restore в failover JSON |
|
||
| 4: отказ каждой реплики, RPS/errors/recovery | scenarios.py failover с индексами 0/1 | оба failover-replica JSON и TXT |
|
||
| 4: CPU/RAM limits, нет обхода LB и container_name | Compose + sanitized inspect | containers.json, resources-summary.json |
|
||
| 4: корректное общее состояние/секреты | PostgreSQL authority, Redis AOF, secrets mounts | persistence.txt, idempotency.json, compose.yaml |
|
||
| 4: rolling под нагрузкой, рабочий survivor | rolling-update.py, 4 writers, проверка данных | rolling-update.json, rolling-continuity.json |
|
||
| 4: согласованные однократные миграции / совместимость | one-shot migrate, advisory lock, version table | migrations-initial.txt, migrations-rerun.txt, migrations-before.txt, migrations-after.txt |
|
||
| Подготовка: структура/полная схема OpenAPI | make check / make validate | check.txt, validate.txt |
|
||
|
||
Все пути доказательств в таблице относительны `evidence/`. HTTP-тесты не заменяют анализа конфигурации миграций/лимитов: оба вида доказательств приведены вместе.
|
||
|