Files

294 lines
47 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: Лебедев Дмитрий, БВТ2302
- Целевая оценка; выбранный трек 5: **5, трек 1 «Цена масштабирования»**
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ:
- библиотеки: Starlette 1.7.0, uvicorn 0.54.0, psycopg 3.2.10 + psycopg_pool 3.2.6, redis-py 5.2.1; HAProxy 3.0; генератор нагрузки — Go, только стандартная библиотека;
- документация: Docker Compose (services, deploy, networks), HAProxy 3.0 Configuration Manual (server-template, resolvers, http-check, retry-on, maxconn/queue, http-error), PostgreSQL (INSERT … ON CONFLICT, ожидание конкурентной вставки), Linux CFS bandwidth control (cpu.cfs_quota_us, nr_throttled);
- **ИИ:** реализация, тесты, эксперименты и этот отчёт подготовлены с помощью ИИ-ассистента Claude (Anthropic). Код других студентов не использовался.
## Запуск из чистого clone
**Выбранный вариант: Docker Compose + HAProxy.** Prerequisites: Docker Engine 24+ с Compose v2, Python 3.9+ на хосте (тесты — только stdlib), `make` (Linux/macOS; для Windows — PowerShell-скрипты ниже). Свободны `127.0.0.1:8080` (API через LB), `:8081` (api-ttl через LB), `:8404` (статистика HAProxy).
**Образы (закреплены тегами):** `haproxy:3.0.5-alpine`, `python:3.13.5-slim-bookworm` (база API), `postgres:16.10-alpine`, `redis:7.4.2-alpine`, `golang:1.24.7-alpine` (только сборка генератора трека 1). API и генератор собираются из исходников репозитория.
```sh
./scripts/init-secrets.sh # secrets/* и .env (значения не печатаются)
docker compose --env-file .env config --quiet
docker compose --env-file .env --profile ttl up -d --build --wait # = make up
curl -si http://127.0.0.1:8080/health/ready | grep -i x-instance-id # запросы чередуются между репликами
make test BASE_URL=http://127.0.0.1:8080 # публичный smoke через LB
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080
./scripts/start-replicas.sh # = make restore: вернуть остановленную реплику
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-student # API/auth/ACL, идемпотентность, TTL, гонка кэша, отказы БД/Redis
make lb-experiments # уровень 4: отказ каждой реплики (SIGTERM/SIGKILL) и rolling update под нагрузкой
make track1 # трек 5.1, ≈ 1 ч; затем evidence/track1/summary.md и *.svg
./scripts/collect-evidence.sh # всё, кроме трека, с выводом в evidence/
make down # безопасно: контейнеры удаляются, volume pgdata сохраняется
make destroy-data # НАМЕРЕННОЕ удаление данных (down -v), с подтверждением
```
**Windows (PowerShell 5.1, без make/WSL).** Docker Desktop запущен, Python с python.org. Используйте `127.0.0.1`, а не `localhost` (Windows сначала пробует `::1`), команды — по одной строке (в PowerShell 5.1 нет `&&`):
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\init-secrets.ps1
docker compose --env-file .env --profile ttl up -d --build --wait
$env:NO_PROXY = '127.0.0.1,localhost'
py -3 tests\smoke.py --base-url http://127.0.0.1:8080
py -3 tests\resilience.py --mode failover --action-script scripts\stop-one.cmd --base-url http://127.0.0.1:8080
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-replicas.ps1
py -3 tests\resilience.py --mode persistence --action-script scripts\restart.cmd --base-url http://127.0.0.1:8080
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\collect-evidence.ps1 # всё сразу; -WithTrack1 — с треком
```
`*.cmd` — обёртки над `*.ps1`: публичный тест запускает хук напрямую, а `.ps1` Windows так не исполняет. Rolling update (`scripts/rolling-update.sh`) — POSIX sh: на Windows запускайте из Git Bash/WSL.
**Действия оператора:** только создание secrets. Миграции применяет one-shot сервис `migrate` до старта реплик; повторно — `docker compose --env-file .env run --rm --no-deps migrate` (no-op). Пароль БД записан в volume при первой инициализации — не удаляйте `secrets/` при живом `pgdata`.
> **Где собраны доказательства.** В среде разработки Docker daemon работал, но Docker Hub и PyPI были закрыты политикой сети. Поэтому `evidence/` получены на **том же `compose.yaml`** с локально собранными образами-заменителями из бинарников хоста: HAProxy 3.0.0 из исходников, PostgreSQL 16.15, Redis 7.0.15, Python 3.13 с теми же библиотеками. Подмена — только поле `image` / сборка API через override-файл, не входящий в репозиторий; топология, сети, лимиты, healthcheck, хуки и конфиг HAProxy — те же. Перед защитой выполните `make up && ./scripts/collect-evidence.sh` (Windows: `scripts\collect-evidence.ps1`), чтобы `evidence/` содержал вывод именно ваших официальных образов; тот же сценарий гоняет `.github/workflows/app.yml`.
## Архитектура и решения
```
127.0.0.1:8080 / :8081 / :8404 (stats)
клиент ──HTTP──► lb: HAProxy 3.0 ──(сеть app, internal)──► api × API_REPLICAS (без ports)
│ DNS Docker: server-template api 8 api:8080 │ uvicorn, 1 процесс, пул ≤ 10
│ GET /health/ready каждые 1 с, fall 2, rise 2 │
│ maxconn 10 на реплику, очередь ≤ 2 с ▼ (сеть data, internal)
│ retry-on conn-failure + redispatch postgres:16 [pgdata] ← источник истины:
└ panic-mode: backup = те же реплики пользователи, чаты, сообщения, сессии,
ключи идемпотентности
migrate (one-shot, до реплик) ──────────────────────────────► redis:7 — кэш сессий (без persistence)
```
| Роль | Service | Образ | Health/readiness | Volume | Сеть/порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| load_balancer | `lb` | `haproxy:3.0.5-alpine` + `infra/haproxy/haproxy.cfg` | `wget /stats`; бэкенды — HTTP-проверка `/health/ready` | — | edge+app; `127.0.0.1:8080/8081/8404` | — |
| api | `api` (`deploy.replicas: ${API_REPLICAS:-2}`) | сборка `Dockerfile` | `python -m messenger healthcheck` → `/health/ready` | нет (stateless) | app+data, **порты не публикуются** | secrets `database_url`, `cache_url` |
| migrations | `migrate` (one-shot, `restart: "no"`) | тот же образ, `command: migrate` | завершение с кодом 0 — условие старта `api` | — | data | `database_url` |
| postgres | `postgres` | `postgres:16.10-alpine` | `pg_isready` | `pgdata` | data | `POSTGRES_PASSWORD_FILE` |
| redis | `redis` | `redis:7.4.2-alpine` (user redis) | `redis-cli ping` | — (кэш) | data | `requirepass` из secret |
| api-ttl (тест TTL) | `api-ttl`, профиль `ttl` | образ API, `SESSION_TTL_SECONDS=2` | как у api | — | app+data; только через LB `:8081` | как у api |
Лимиты: API — `API_CPUS`/`API_MEMORY` (по умолчанию 1 CPU / 512 MiB на реплику), LB 0.5 CPU / 128 MiB, PostgreSQL 1 CPU / 1 GiB, Redis 0.25 CPU / 128 MiB, migrate 0.5 / 256 MiB. Нет `container_name` — `api` масштабируется (`--scale`, `deploy.replicas`). Контейнер API: uid 10001, `read_only`, `cap_drop: ALL`, `no-new-privileges`. Сети `app` и `data` — `internal: true`: PostgreSQL, Redis и реплики API снаружи недоступны, единственная точка входа — LB.
**Что перенесено из lab2.** Весь API, PostgreSQL как источник истины, сессии (scrypt, opaque Bearer, TTL, logout), Redis-кэш сессий с outbox-инвалидацией, keyset-пагинация, тесты lab2. **Что изменено в lab3:**
1. **Stateless-реплики.** Всё, от чего зависит корректность, — в PostgreSQL (сессии, ключи идемпотентности), Redis — общий кэш. Sticky sessions нет: `balance roundrobin`.
2. **`X-Instance-Id`** — случайный alias процесса (`api-<8 hex>`), без hostname/IP; реплика пишет его в `/tmp/instance-id` (tmpfs) — так `stop-one.sh` находит контейнер.
3. **Миграции отдельно и однократно:** сервис `migrate` выполняется до реплик (`depends_on: service_completed_successfully`), под `pg_advisory_lock`. Реплики (`MIGRATE_ON_START=false`) только проверяют, что в `schema_migrations` есть все известные им версии с теми же checksum, и до этого не становятся ready. Более новая схема допустима (expand-фаза следующей версии).
4. **Общая идемпотентность** `POST /chats/{id}/messages` (миграция `0003_idempotency_keys.sql`).
5. **Graceful shutdown** под LB и **panic mode** HAProxy (ниже).
**Идемпотентность — транзакционная граница.** Одна транзакция: удалить просроченный ключ этой тройки → `INSERT message … WHERE EXISTS(membership)` → `INSERT idempotency_keys (user, chat, key, sha256(канонический JSON), message_id) ON CONFLICT DO NOTHING`. Если ключ уже есть — `ROLLBACK` своей вставки и чтение сохранённого результата: тот же hash → тот же 201 и то же Message (`Idempotent-Replayed: true`), другой → 409. Конкурентная вставка того же ключа с **любой** реплики ждёт на уникальном индексе COMMIT/ROLLBACK первой транзакции: после COMMIT получает конфликт, после ROLLBACK вставляет сама. Поэтому одновременные повторы через разные реплики дают ровно одно сообщение, а транзиентная ошибка (откат) ключ не занимает. Повтор заново проверяет сессию (Bearer) и членство в чате. Хеш — от канонического JSON (`sort_keys`, без пробелов): порядок ключей и форматирование не важны. Срок — `IDEMPOTENCY_TTL_SECONDS` (24 ч); очистка — фоновой задачей реплик пачками по 5000.
**Health, readiness, timeouts, SIGTERM — согласованно.**
| Параметр | Значение | Зачем |
| --- | --- | --- |
| Проверка LB | `GET /health/ready`, `inter 1s`, после первой ошибки `fastinter 500ms`, `fall 2`, `rise 2`, `timeout check 300ms` | Максимальное время обнаружения отказа ≈ 1 + 0.3 + 0.5 + 0.3 ≈ **2.1 с**; возврат — 2 успешные проверки (≈ 1–2 с) |
| `timeout connect` | 300 ms | к убитому контейнеру нет RST — ждём не дольше 300 мс, затем `retry-on conn-failure` + `redispatch` на другую реплику (повтор только если запрос ещё не отправлен — безопасно и для неидемпотентных POST) |
| `timeout server` | 15 s | > `REQUEST_TIMEOUT_SECONDS` = 10 с приложения |
| SIGTERM в реплике | 3 с drain (`SHUTDOWN_DRAIN_SECONDS`): `/health/ready` = 503, ответы с `Connection: close`, запросы ещё обслуживаются; затем listener закрывается, запросы в полёте завершаются (≤ 10 с); 2-й сигнал — немедленный выход | drain (3 с) > худшего времени обнаружения LB (≈ 2.1 с) — LB выводит реплику до закрытия listener |
| `stop_grace_period` | 15 s | drain + завершение запросов в полёте |
| uvicorn keep-alive | 30 s (> idle-пула HAProxy) | соединение первым закрывает LB, а не реплика |
| `maxconn` на реплику / `timeout queue` | 10 / 2 s | ограничение конкуренции: излишек ждёт в очереди LB, а не в event loop (обоснование — трек 5.1) |
| DNS | `resolvers docker` (127.0.0.11), `hold obsolete 5s` | новые/удалённые реплики (`--scale`, rolling update) подхватываются без перезапуска LB |
`depends_on`/healthcheck Compose лишь упорядочивают старт и показывают состояние контейнера, но не распределяют трафик и не исключают больной backend из маршрута. Это делает HAProxy своими проверками.
**Panic mode.** Если readiness не проходит ни у одной реплики (например, упала БД), LB всё равно отправляет запросы в живые процессы (`backup`-слоты на те же адреса, `option allbackups`, `resolve-opts allow-dup-ip`). Клиент получает ответы приложения: анониму 401, бизнес-запросам 503 `unavailable` в формате API, `/health/live` = 200. Без этого LB отвечал бы безликим 503 на всё. Мёртвый процесс в backup-слоте даёт conn-failure и 503 LB.
**Ответы, созданные LB** (нет живых реплик, 502/504, `/internal/*` → 404), — в формате ошибок API с `request_id` = `X-Request-Id` (uuid). `X-Instance-Id` у них нет, контракт это допускает. Расширения API описаны в `contracts/EXTENSIONS.md`.
**Соответствие переменных `.env.example`.** `APP_HOST`/`APP_PORT` — адрес uvicorn (`0.0.0.0:8080`); `SESSION_TTL_SECONDS` — срок сессии; `DATABASE_URL_FILE`/`CACHE_URL_FILE` — `/run/secrets/*`; `SESSION_STORE=postgres` — источник истины сессий; `API_REPLICAS` → `deploy.replicas`; `IDEMPOTENCY_TTL_SECONDS` → срок ключа. Дополнительно: `API_PORT`, `API_TTL_PORT`, `LB_STATS_PORT`, `API_CPUS`, `API_MEMORY`, `PG_CPUS`, `PG_MAX_CONNECTIONS`, `SESSION_CACHE`, `SESSION_CACHE_TTL_SECONDS`, `DB_POOL_MAX`, `KDF_CONCURRENCY`, `SHUTDOWN_DRAIN_SECONDS`, `LB_SERVER_MAXCONN`, `LB_QUEUE_TIMEOUT` (см. комментарии в `.env.example` и `compose.yaml`).
**Rolling update и миграции.** `scripts/rolling-update.sh`: собрать образ новой версии (`APP_VERSION` → label и env); один раз применить миграции (`run --rm migrate`); для каждой старой реплики поднять одну новую (`--scale N+1 --no-recreate`), дождаться healthy, остановить старую SIGTERM-ом (drain) и удалить. Число готовых реплик не опускается ниже N. **Ограничение:** миграции обязаны быть *expand-only* (добавлять, не ломая работающую версию: новые таблицы/nullable-колонки/индексы). Удаление и переименование делаются отдельным релизом (*contract*) после того, как старых реплик не осталось. Скрипт это не проверяет: это дисциплина разработки, проверенная демонстрацией ниже.
## Доказательства критериев
Все файлы — в `evidence/`. Стенд описан в примечании выше; версии и контейнеры — `evidence/stack.txt` (2 vCPU Intel Xeon 2.8 GHz, 8 GiB RAM, Docker 29.9.2, Compose 5.6.1). Прогон с **пустого volume** `pgdata`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke через LB | `tests/smoke.py --base-url http://127.0.0.1:8080` | `PASS: lab3 public API scenario` | `smoke.txt` |
| 3: стенд одной командой; ≥2 реплики, одна точка входа, общие БД и сессии | `docker compose --profile ttl up -d --build --wait` | `lb` (единственный с портами), `api-1`, `api-2`, `migrate` (exit 0), `postgres`, `redis`, `api-ttl` — healthy | `stack.txt` |
| 3: разные запросы одной сессии — разные реплики, без повторного входа | 6 запросов через LB; smoke/тесты с одним токеном | `X-Instance-Id` чередуется `api-0ac6…`/`api-ea54…`; 10 повторов POST с одним токеном обслужены 2 репликами | `instances.txt`, `test-idempotency.txt` |
| 3: остановка любой реплики; чтение/запись ≤ 10 с; подтверждённые сообщения целы | `tests/resilience.py --mode failover --action-script scripts/stop-one.sh` ×2 + `start-replicas.sh` | PASS дважды: ≥2 реплики до отказа, 0 неудачных попыток из 138–139 записей; `first_recovery_seconds` 4.7–4.8 (это время работы хука `docker stop`, записи не прерывались); остановленный контейнер (`status=exited`) в `failover-hook.txt` | `failover-1.txt`, `failover-2.txt`, `failover-hook.txt`, `restore-*.txt` |
| 3: повтор POST с тем же ключом без дублей, в т. ч. конкурентно и через другую реплику | `student-tests/test_idempotency.py` | 30 одновременных POST одного ключа: 14 + 16 ответов от двух реплик, одно тело, **1 строка**; 2 разных тела на один ключ: 1 сообщение, 10×201 + 10×409; повторы с другой реплики; 400 на неверный ключ; неуспешный запрос ключ не занимает; повтор после logout — 401; ключ старше 24 ч переиспользуется | `test-idempotency.txt` |
| 3: неподтверждённую запись можно повторить с тем же ключом | failover-тест (повтор неопределённого POST тем же ключом), серия отказов (повтор после 502/таймаута) | дублей текста 0, потерянных подтверждённых 0 во всех прогонах | `failover-*.txt`, `lb/failover-series.json` |
| 3: persistence | `tests/resilience.py --mode persistence --action-script scripts/restart.sh` | PASS тем же токеном; новые `StartedAt`/PID у LB, обеих реплик, PostgreSQL, Redis; volume сохранён | `persistence.txt`, `restart-hook.txt` |
| 3: миграции отдельно, однократно, повтор без дублей | пустой volume → сервис `migrate`; `run --rm migrate` | `applied: [0001, 0002, 0003]` один раз; повтор — `applied: []`; реплики логируют `schema compatible; replica ready` | `migrations.txt`, `migrations-rerun.txt` |
| Сохранены возможности lab2 | `test_api.py` (auth, ACL, валидация, пагинация, rollback, гонка регистрации), `test_expiry.py` (через LB :8081), `test_cache_race`, `test_failures.py` | 18/18, 3/3, all passed, 2/2 | `test-api.txt`, `test-expiry.txt`, `test-cache-race.txt`, `test-failures.txt` |
| 4: health/readiness/timeouts/SIGTERM согласованы; LB исключает недоступный backend | таблица выше; серия отказов SIGTERM | после SIGTERM реплика получает последний запрос через 0.95–1.53 с, ошибок 0 | `lb/failover-series.json` |
| 4: последовательно остановить каждую реплику; RPS, ошибки, время восстановления | `research/lb_experiments.py failover-series --mode both` | таблица ниже: SIGTERM — 0 ошибок; SIGKILL — 5–8 ответов 502 за ≤ 0.1 с; восстановление — 5.6–6.0 с до healthy | `lb/failover-series.json`, `lb-failover-series.txt` |
| 4: идемпотентность параллельными запросами с одним ключом | см. уровень 3 | 30 параллельных → 1 сообщение | `test-idempotency.txt` |
| 4: CPU/RAM-лимиты; API без портов; нет `container_name` | `compose.yaml` | у всех сервисов `deploy.resources.limits`; у `api` нет `ports`, сети `app`/`data` internal | `compose.yaml`, `stack.txt` |
| 4: rolling update под нагрузкой; миграции однократны и совместимы | `research/lb_experiments.py rolling-update` (3 обновления подряд), `research/expand_migration_demo.sh` | 0 ошибок за 27–28 с замены, образы сменились, потерь и дублей нет; новая версия без миграции не ready (`missing 0004`), миграция применена один раз, старые реплики остались ready | `lb/rolling-update-*.json`, `rolling-update.txt`, `lb/expand-migration.txt` |
| 5, трек 1 | `research/track1.py run …` (15 конфигураций, ключевые ×3) + `report` | см. раздел трека | `track1/*.json`, `track1/summary.md`, `track1/*.svg` |
| Нагрузка (профиль) | `tests/load.py --duration 30 --concurrency 4` через LB | 236.8 успешных RPS, 0 ошибок, p50/p95/p99 = 15.3/30.8/47.0 мс | `load.json` |
## Эксперименты и отказы
**Последовательный отказ каждой реплики под нагрузкой** (`evidence/lb/failover-series.json`). 8 потоков closed-loop через LB, у каждого свой пользователь: 1 POST (с ключом; при ошибке повтор тем же ключом и телом) на 3 GET истории; клиентский таймаут 2 с. Фазы: 5 с до отказа → действие → 10 с с одной репликой → `docker start` → 5 с. 2 реплики × 1 CPU / 512 MiB, `maxconn 10`.
| Воздействие | Реплика | Ошибки после действия | Последняя ошибка | Реплика ещё отвечала | Макс. пауза между записями | RPS до / во время / после | p99 до / во время, мс | До healthy после старта | Потери / дубли |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SIGTERM (`docker stop`) | api-1 | 0 | — | 0.95 с | 0.12 с | 265 / 252 / 253 | 101 / 68 | 5.6 с | 0 / 0 |
| SIGTERM | api-2 | 0 | — | 1.53 с | 0.18 с | 279 / 220 / 242 | 83 / 89 | 6.0 с | 0 / 0 |
| SIGKILL (`docker kill`) | api-1 | 5 × 502 | 0.08 с | 0.04 с | 0.32 с | 296 / 187 / 237 | 93 / 310 | 5.7 с | 0 / 0 |
| SIGKILL | api-2 | 8 × 502 | 0.10 с | 0.05 с | 0.31 с | 280 / 212 / 218 | 79 / 308 | 5.7 с | 0 / 0 |
SIGTERM: реплика 3 с отвечает 503 на readiness и дообслуживает запросы, LB выводит её за ~1 с — ни одной ошибки. SIGKILL: ошибки — только запросы «в полёте» на убитом процессе (502), дальше `retry-on conn-failure` + `redispatch` и проверка (`fall 2`) выводят реплику. Неопределённые POST повторены тем же ключом — дублей нет. Падение RPS «во время» — работа на одной реплике (её CPU и пул). «До healthy» — старт контейнера, проверка схемы и healthcheck Docker; в маршрут LB реплика возвращается через 1.3–3.6 с после старта.
**Настройка, подтверждённая измерением (до/после).** Сначала стояли `timeout connect 1s` и проверка с таймаутом по `inter` (1 с). При SIGKILL к убитому контейнеру нет RST, поэтому каждая попытка соединения и каждая проверка висели по 1 с: максимальная пауза между записями — 0.99–1.06 с, p99 ≈ 1010 мс, RPS во время отказа — 142–165. После `timeout connect 300ms` + `timeout check 300ms`: пауза 0.26–0.32 с, p99 ≈ 310 мс, RPS 187–215 (сохранены `evidence/lb/failover-series-connect1s.json` и текущий ряд).
**Rolling update под нагрузкой** (`evidence/lb/rolling-update-3.0.1.json`, `-3.0.2-expand.json`, `-3.0.3.json`): три замены подряд — 0 ошибок из 5274–5710 запросов за 27–28 с, p99 135–173 мс, потерянных/дублированных сообщений 0; image id обеих реплик сменился (`rolling-update.txt`). Вторая замена несла новую expand-миграцию 0004 (`lb/expand-migration.txt`): контейнер новой версии до миграции остался NOT-READY с логом `schema is behind … missing 0004`; `migrate` применил её один раз; старые реплики 3.0.1 остались ready.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| SIGTERM одной реплики | 0 ошибок, LB выводит её до закрытия | 0 ошибок, последний запрос на неё через ≤ 1.5 с | новые запросы не прерывались; 0 потерь |
| SIGKILL одной реплики | ошибки только у запросов в полёте | 5–8 ответов 502 за ≤ 0.1 с | ≤ 0.32 с до следующей успешной записи; 0 потерь |
| Рестарт всего стенда (restart hook) | данные и токен живы | PASS | 0 потерь |
| Остановка Redis | работа через PostgreSQL | всё 2xx, `/users/me` за 5 мс | outbox дообработан после старта; отозванный токен — 401 |
| Остановка PostgreSQL | ограниченный 503, аноним — 401 | 503 `unavailable` за 2.0 с, `/health/live` = 200 через panic mode LB | ready через 2.3 с после старта БД |
| Rolling update ×3 | без ошибок | 0 ошибок | 0 потерь |
### Трек 5.1. Цена масштабирования
**Вопрос и гипотезы.** Что даёт добавление API-реплик и где предел?
- H1. При фиксированном суммарном CPU/RAM больше реплик не дают больше пропускной способности: Python-API ограничен CPU, а у каждой реплики свои накладные расходы.
- H2. При росте ресурсов пропускная способность растёт до насыщения общего ресурса, после чего новые реплики не помогают.
- H3. При перегрузке без ограничения конкуренции полезная пропускная способность не держит плато, а проваливается (congestion collapse). Ограничение `maxconn` на LB это устраняет.
**Методика (повторяемая):** `make track1` = `research/track1.py run all` + `report`.
- **Стенд.** Тот же `compose.yaml` + `research/compose.track1.yaml`. Реплики API привязаны к ядру `API_CPUSET=0`, их суммарный бюджет задаётся квотой `API_CPUS`; LB, PostgreSQL, Redis и генератор — на ядре `AUX_CPUSET=1`. Перед каждой конфигурацией реплики и LB пересоздаются (`--force-recreate`), запуск только после того, как LB видит все реплики UP.
- **Нагрузка.** Генератор `research/loadgen` — Go, только stdlib, внутри сети стенда (без docker-proxy).
- Модель **open-loop**: запросы по расписанию, задержка — от запланированного момента, без coordinated omission.
- 48 синтетических пользователей по одному чату с историей; смесь 70% GET истории (limit 50), 20% POST сообщения (уникальный ключ), 10% GET `/users/me`.
- Ступени 40…800 req/s по 3 с прогрева + 10 с измерения; серия останавливается после двух ступеней с > 30% ошибок.
- **Метрики.**
- Ёмкость при SLO: максимальная полезная пропускная способность при p99 ≤ 250 мс и ошибках ≤ 1%.
- Максимум при ошибках ≤ 1%.
- Пик полезной пропускной способности.
- Одновременно: CPU%/RAM контейнеров (`docker stats`), очередь HAProxy (stats CSV), соединения и события ожидания PostgreSQL (одна сессия `psql \watch 1`), доля периодов CFS с троттлингом (`cpu.stat`), счётчики пула psycopg в репликах до/после.
- **Повторы.** Ключевые конфигурации (серия A, `maxconn 10`) — 3 прогона, в выводах медиана. Остальные — по 1 прогону, это отмечено.
**Исходные данные:** `evidence/track1/<config>[-rN].json` (все ступени и ресурсы), `summary.md`/`summary.json`, графики `*.svg`.
**Серия A — фиксированный бюджет API 1 CPU / 512 MiB** (scrypt-параллелизм делится так же: 4/2/1), медиана 3 прогонов:
| Конфигурация | Ёмкость при SLO, rps | Макс. при ошибках ≤ 1 %, rps | Пик, rps | CPU API при 80 rps | CFS-троттлинг при 80 rps | p99 при 80 rps |
| --- | --- | --- | --- | --- | --- | --- |
| 1 × 1.0 CPU | **240** (280/240/240) | **280** | 280 | 28 % | 0 % | 27 мс |
| 2 × 0.5 CPU | 200 (120/200/200) | 200 | 235 | 32 % | 6.7 % | 48 мс |
| 4 × 0.25 CPU | 160 (160/120/160) | 200 | 200 | 45 % | 4.7 % | 66 мс |
![Фиксированный бюджет: полезная пропускная способность](evidence/track1/fixed-cpu-goodput.svg)
![Фиксированный бюджет: p99](evidence/track1/fixed-cpu-p99.svg)
H1 подтверждена, и дробление даже вредит. Механизмы:
- **Накладные расходы на реплику.** На одной и той же нагрузке 80 rps суммарный CPU API растёт с 28 до 45%: у каждой реплики свои health-проверки LB (1/с), фоновые циклы (кэш, очистка), event loop и рантайм. Стоимость запроса на пике растёт с 3.2 до 4.4 мс CPU.
- **Квота CFS.** Реплика с квотой 0.25–0.5 ядра, выбравшая квоту за период 100 мс, замораживается до конца периода: 5–7% периодов с троттлингом уже при 80 rps и до 36% на пике. Отсюда хвост задержки при одинаковом суммарном CPU.
- **RAM.** У каждой реплики фиксированные ~30–45 MiB рантайма плюс по 32 MiB на одновременный scrypt. При 128 MiB на реплику и scrypt-параллелизме 4 первые прогоны получили **cgroup OOM kill** при регистрации пользователей (`dmesg: Memory cgroup out of memory`). Дробить RAM без пересчёта параллелизма KDF нельзя.
**Серия B — рост ресурсов** (реплики по 0.25 ядра на изолированном ядре, 1 прогон; 4×0.25 — медиана серии A) и **серия C — вся машина** (2 vCPU без изоляции, общие с LB/БД/генератором, 1 прогон):
| Конфигурация | Суммарно CPU API | Пик, rps | Макс. при ошибках ≤ 1 %, rps |
| --- | --- | --- | --- |
| 1 × 0.25 | 0.25 | 84 | 80 |
| 2 × 0.25 | 0.5 | 160 | 160 |
| 3 × 0.25 | 0.75 | 178 | 160 |
| 4 × 0.25 | 1.0 | 200 | 200 |
| 1 × 1.0 (для сравнения) | 1.0 | 280 | 280 |
| 2 × 1.0, вся машина | ≤ 2 (2 vCPU хоста) | 320 | 320 |
| 4 × 1.0, вся машина | ≤ 2 | 312 | 280 |
![Рост ресурсов](evidence/track1/growth-peak.svg)
Почему рост реплик перестаёт помогать (H2):
- До 0.5 ядра рост почти линеен (84 → 160 rps), дальше выгода падает: 0.75 → 178, 1.0 → 200. Четыре реплики по 0.25 уступают одной реплике на целом ядре (280) по причинам серии A.
- На всей машине 2 реплики дают +14% к одной (320 против 280), а 4 реплики — уже не лучше двух. На пике суммарная загрузка контейнеров — 159–171% из 200%, остальное съедают dockerd/containerd и сэмплер: **хост насыщен**.
- CPU на запрос по компонентам (machine-2×1.0, на пике):
| Компонент | мс CPU/запрос |
| --- | --- |
| API | 3.5 |
| PostgreSQL | 0.6 |
| генератор | 0.5 |
| LB | 0.23 |
| Redis | 0.12 |
API в ~6 раз дороже PostgreSQL на запрос. Значит, на этой машине первым кончается CPU для API, а БД и LB далеки от насыщения: PostgreSQL ~20% CPU; события ожидания — почти только `CPU`, изредка `IO:WALSync`, `pg_test_fsync` 0.25 мс.
- Каждая новая реплика добавляет процессы, которые конкурируют за те же 2 ядра, и пул из 10 соединений к БД: 10 → 20 → 41 соединение. Время удержания соединения на запрос (среднее по всей серии): 16 мс у 1×1.0 → 18 мс у 2×1.0 → 40 мс у 4×1.0.
- **Оценка следующего предела (экстраполяция, не измерено).** При изобилии CPU для API первым насытится PostgreSQL на одном ядре — около 1 / 0.6 мс ≈ 1600 rps на этой смеси. Затем `max_connections=100` при пуле 10 ограничивает число реплик ~9 (с учётом migrate и служебных соединений). Дальше нужен пул на стороне БД (PgBouncer) или меньший пул на реплику.
**Насыщение пула.** При 1×1.0 под перегрузкой запрос в среднем по серии ждёт свободное соединение 279–308 мс (3 прогона), а держит его 16 мс. При этом сам SQL выполняется ~1 мс: соединение «держит» корутина, которая ждёт своей очереди в перегруженном event loop. `/users/me` без БД (из кэша Redis) в тех же ступенях отвечает за ~25 мс, history/post — около 1 с. Ошибки — `PoolTimeout`/`TooManyRequests` пула, а не LB.
Серия P (1×1.0, по 1 прогону), пик / ёмкость при SLO:
| Пул | Пик, rps | Ёмкость при SLO, rps |
| --- | --- | --- |
| 5 | 320 | 280 |
| 10 | 280 | 240 |
| 20 | 280 | 200 |
| 40 | 280 | 200 |
Больший пул не помогает: ограничитель — CPU event loop, а не число соединений. Меньший пул лишь ограничивает конкуренцию. Это подводит к улучшению.
**Подтверждённое улучшение: ограничение конкуренции на LB (`maxconn 10` на реплику, `timeout queue 2s`)** — 1×1.0 CPU, пул 10, медиана 3 прогонов каждого варианта:
| Поданная нагрузка | Без лимита: полезная / ошибки / p50 | `maxconn 10`: полезная / ошибки / p50 |
| --- | --- | --- |
| 280 req/s | 280 / 0 % / 72 мс | 280 / 0 % / **12 мс** |
| 320 req/s | 276 / 13.8 % / 744 мс | **320 / 0 %** / 162 мс |
| 360 req/s | 277 / 22.9 % / 794 мс | **360 / 0.1 %** / 1323 мс |
| 400 req/s | 253 / 36.8 % / 931 мс | **354** / 11.4 % / 1670 мс |
| 460 req/s | 223 / 51.6 % / 1103 мс | **328** / 28.7 % / 2026 мс |
| Ёмкость при SLO | 240 (280/240/240) | **280** (320/280/240) |
| Макс. при ошибках ≤ 1 % | 280 (280/280/280) | **360** (360/360/320) — **+28 %**, каждый из 3 прогонов выше каждого базового |
![maxconn против перегрузки](evidence/track1/admission-goodput.svg)
H3 подтверждена. Без лимита LB отдаёт реплике всё сразу: сотни корутин в event loop борются за CPU и 10 соединений, время удержания соединения раздувается, запросы истекают по таймауту пула. CPU тратится на работу, которую потом выбрасывают, и полезная пропускная способность падает с 280 до 223 rps. С `maxconn 10` в реплике не больше 10 запросов; остальные ждут в дешёвой очереди HAProxy и при переполнении получают быстрый 503. Полезная пропускная способность держит плато 330–360 rps вместо провала.
Проверенные варианты (по 1 прогону):
| Вариант | Макс. при ошибках ≤ 1 %, rps |
| --- | --- |
| `maxconn 10`, `timeout queue 2s` | 360 (медиана) |
| `maxconn 20` | 320 |
| `maxconn 10`, `timeout queue 250ms` | 239: очередь 250 мс слишком коротка и отбрасывает всплески, которые иначе уложились бы |
| 2×0.5 с `maxconn 10` | 280 (без лимита 200) |
Значения `maxconn 10` и `timeout queue 2s` **приняты по умолчанию** в `compose.yaml`; уровни 3–4 повторно проверены уже с ними.
**Ограничения измерений:**
- Одна машина на 2 vCPU. Генератор, LB, БД и рантайм Docker делят её с API. Изоляция ядер снимает конкуренцию только для API.
- Абсолютные числа зависят от CPU хоста. Переносимы соотношения и механизмы, не rps.
- Ключевые конфигурации повторены 3 раза; разброс ёмкости при SLO — одна ступень (±40 rps), из-за этого шага сетки ёмкость определена с точностью до ступени. Остальные конфигурации — 1 прогон.
- Тёплый кэш, данные — тысячи сообщений: стоимость БД здесь минимальна; большие истории — в треке 5.2 lab2.
- Числа получены на локальных образах-заменителях: HAProxy 3.0.0 вместо 3.0.5, PostgreSQL 16.15 вместо 16.10, Redis 7.0 вместо 7.4, psycopg без C-расширения (pure-Python + системная libpq) вместо `psycopg[binary]`. Последнее завышает CPU API на запрос: в официальном образе ожидаемы более высокие абсолютные значения. Повторите `make track1`.
- Сэмплер сам потребляет CPU хоста. Первая версия с `docker exec` раз в секунду заметно занижала результаты и заменена одной сессией `psql`.
## Ответы на вопросы защиты
- **Отказ процесса vs отказ узла.** Отказ процесса (SIGKILL реплики) оставляет живыми хост, сеть, Docker и остальные контейнеры: LB видит отказ соединения, перенаправляет запросы, Docker перезапускает контейнер, volume на месте. При отказе узла пропадает всё, что на нём: все реплики, LB, PostgreSQL и его диск. На одном Docker-хосте этот стенд отказ узла не выдерживает — для этого нужны другие узлы, репликация БД и переносимый LB (трек 5.2, не выбран).
- **Почему depends_on/healthcheck — не балансировщик.** `depends_on` задаёт только порядок старта, healthcheck Docker лишь помечает контейнер unhealthy. Ни то, ни другое не распределяет запросы, не исключает больной backend из маршрута и не повторяет запрос на другой реплике. Это делает LB: активные проверки, `fall`/`rise`, `redispatch`.
- **Какие POST можно повторять после timeout и что защищает Idempotency-Key.** Без ключа повторять безопасно только то, что не создаёт новый объект, — в обязательном API таких POST нет: повтор регистрации даст 409, повтор создания чата создаст ещё один чат. `POST /messages` с тем же `Idempotency-Key` и тем же телом можно повторять сколько угодно и через любую реплику: результат первой успешной транзакции сохранён атомарно с сообщением, повтор возвращает его же, другой body — 409. LB сам повторяет только то, что не было отправлено (`retry-on conn-failure`).
- **Что сломается с сессиями в локальной памяти.** Токен, выданный репликой A, будет неизвестен реплике B: при roundrobin каждый второй запрос — 401. Logout на одной реплике не отзовёт токен на другой. Рестарт или отказ реплики разлогинит её пользователей. Sticky sessions лишь маскируют проблему и ломаются при отказе реплики. Здесь сессии в PostgreSQL, Redis — общий кэш.
## Ограничения и следующие шаги
- **Выдерживается:** остановка/убийство любой одной API-реплики (без ошибок при SIGTERM, ≤ 8 ошибок 502 при SIGKILL), рестарт всего стенда с volumes, rolling update под нагрузкой, отказ Redis, отказ PostgreSQL (ограниченные 503).
- **Не выдерживается:** отказ хоста; отказ единственного LB или PostgreSQL — это SPOF стенда.
- `scripts/stop-one.sh` находит реплику по alias через `docker exec` (файл `/tmp/instance-id`) — это требует работающего процесса. Убитую реплику так не найти, но этот хук останавливает живую реплику.
- Публичный failover-тест сам выбирает реплику, которая обслужила запрос. Поэтому поочерёдная остановка каждой реплики показана отдельно (`lb/failover-series.json`: api-1 и api-2, SIGTERM и SIGKILL).
- Окно устаревания кэша сессий при сетевом разделении реплики и Redis — как в lab2 (≤ `SESSION_CACHE_TTL_SECONDS`).
- Rolling update на Windows — только из Git Bash/WSL (скрипт POSIX sh).
- `evidence/` получены на образах-заменителях (см. примечание в начале). Повторите `./scripts/collect-evidence.sh` на официальных образах.