diff --git a/README.md b/README.md index e2239183..10381de4 100644 --- a/README.md +++ b/README.md @@ -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/)