Восстановить README с условием лабораторной

Вернуть исходную методичку задания без изменений, как требует CONTRIBUTING.md.
This commit is contained in:
2026-11-06 19:19:17 +03:00
parent 48b8446800
commit 937dd0f7a9
+75 -34
View File
@@ -1,63 +1,104 @@
# Лабораторная 3. Балансировка и отказ API-реплики
Решение сохраняет API и постоянные данные ЛР2, добавляет HAProxy, масштабируемый пул API-реплик, общие PostgreSQL/Valkey, `X-Instance-Id` и атомарный `Idempotency-Key` для POST сообщений. На «5» выбран трек 1: измерение цены масштабирования при фиксированном и растущем бюджете ресурсов.
Запустить несколько взаимозаменяемых экземпляров API за единой точкой входа и сохранить корректность при остановке одного из них.
## Запуск
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
Требуется Docker Compose v2. Создайте `.env` по `.env.example`, задайте уникальный `POSTGRES_PASSWORD` и запустите:
[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md)
```sh
cp .env.example .env
# замените POSTGRES_PASSWORD случайным локальным значением
## Откуда начинаем
docker compose --env-file .env up -d --build --scale api=2
curl -i http://127.0.0.1:8080/health/ready
```
Нужен минимум lab2: PostgreSQL, общие действующие сессии, миграции. Добавляются X-Instance-Id и обязательный Idempotency-Key при отправке сообщения.
Публичен только `127.0.0.1:${APP_PORT}` у HAProxy. У API нет опубликованных host ports. Миграция выполняется отдельным одноразовым сервисом под PostgreSQL advisory lock до старта реплик. Она применима повторно, записывает версии в `schema_migrations` и меняет схему до приема HTTP трафика.
**Архитектура:** Клиент → LB → API × 2+ → общие PostgreSQL и хранилище сессий. Compose или Swarm — на выбор.
HAProxy использует DNS `api` для обнаружения IP Compose-задач, round robin и активный `GET /health/ready` с интервалом 1 секунду (backend исключается после двух неудач, возвращается после двух успехов). DNS-записи проверяются раз в 2 секунды. Connect timeout — 1 секунда, запрос к upstream — 10 секунд. API обрабатывает SIGTERM и закрывает listener; Compose ждёт до 10 секунд перед SIGKILL.
## Что сделать
## Проверки
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 не реплицирована, не заявляйте выживание её узла.
## Как начать и проверить
```sh
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
make validate
make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-idempotency BASE_URL=http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080
# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test
```
Failover проверка останавливает одну конкретную реплику по `X-Instance-Id` (равен Docker hostname/short ID), затем оставляет её остановленной. `docker compose ps` показывает фактическое состояние. Верните реплики командой `docker compose --env-file .env up -d --scale api=2`.
Rolling replacement с сохранением второй реплики и живого LB:
`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
```sh
make rolling-update
# 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.
```
Скрипт сначала добавляет временную третью реплику, ждёт её readiness, затем удаляет старые контейнеры по одному и возвращает пул к двум. Во время операции запустите параллельно `make load` и проверьте, что сообщения читаются после замены.
## Трек 1: масштабирование
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
```sh
make track1
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
```
Исследование сравнивает 1/2/4 реплики при фиксированном бюджете и 1/2/4/8 при растущем бюджете с общим пределом CPU 2 ядра и памяти 1 GiB, затем выполняет серию с фиксированными лимитами 0,5 CPU / 256 MiB на реплику. Для каждой точки задаётся одинаковая нагрузка `tests/load.py`; healthcheck --wait до 180 секунд и пять секунд стабилизации после смены топологии, затем 30 секунд и concurrency 16 (можно задавать `BENCH_SECONDS`, `BENCH_CONCURRENCY`). Результаты и график создаются в `evidence/track1-results.json` и `evidence/track1-rps.svg`. Для сдачи требуется не менее трёх прогонов каждой точки; сводить нужно медианы и разброс, а в отчёте указать лимиты Docker Desktop, версию runtime, длительность, успешные RPS, долю ошибок и p50/p95/p99.
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте.
Для поиска точки насыщения есть повторяемый rate-controlled профиль и парный тест лимита API:
## Сценарий защиты
```sh
make track1-offered # 8 API: предложенные 250/500/750/1000 RPS, 3 повтора
make track1-offered-scale # 8 против 12 API при 1000 RPS, 3 повтора
```
1. Запустить стенд и показать ≥2 разных X-Instance-Id через LB с одной сессией.
2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Скрипт теста выполняет запросы во время action, учитывает ошибки и повторяет сообщения с исходным ключом.
3. Показать, какой контейнер действительно остановлен; заголовок сам по себе не доказательство разных процессов. Повторить для второй реплики после восстановления первой.
4. Проверить restart всего стенда с сохранением volumes и неизменным токеном. Для 4/5 — соответствующие эксперименты.
`track1-offered` ограничивает число одновременно ожидающих запросов, повторно использует HTTP-клиент в потоках и считает throughput по полной длительности вместе с drain. `track1-offered-scale` возвращает пул к 8 репликам перед очисткой тестовых таблиц, затем поднимает вариант. JSON, график и наблюдение об исчерпании соединений PostgreSQL сохраняются в `evidence/`.
## Что должно быть в PR
Генератор closed-loop, поэтому он подвержен coordinated omission и включает стоимость клиента. На одном Docker-host база и LB также ограничивают результат. Замеры процесса не являются доказательством роста пропускной способности production-системы.
compose.yaml или stack.yaml, конфигурация LB, scripts/restart.sh, scripts/stop-one.sh, Dockerfile, миграции, результаты отказов.
## Лимиты и хранение
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
Контейнеры имеют лимиты ресурсов. API реплики не имеют отдельных volumes; общее состояние сообщений и идемпотентных ключей лежит в PostgreSQL. PostgreSQL — источник истины сессий; Valkey хранит только восстанавливаемую TTL-подсказку и включён с AOF. Именованные volumes `postgres_data` и `valkey_data` общие для сервиса, не удаляются restart/failover проверками. На одном узле остаются SPOF: host, HAProxy, PostgreSQL и Valkey-хост (при потере Valkey сессии продолжают проверяться через PostgreSQL).
## Вопросы на защите
- Чем отказ процесса отличается от отказа узла?
- Почему depends_on/healthcheck сами по себе не являются балансировщиком?
- Какие POST можно повторять после timeout и что защищает Idempotency-Key?
- Что сломается при увеличении числа API, если сессии находятся в локальной памяти?
## Первичные материалы
- [Compose services](https://docs.docker.com/reference/compose-file/services/)
- [Swarm routing mesh](https://docs.docker.com/engine/swarm/ingress/)
- [Swarm services](https://docs.docker.com/engine/swarm/services/)