forked from mtusi2026/mtusi2026lab3
218 lines
18 KiB
Markdown
218 lines
18 KiB
Markdown
# Лабораторная 3. Балансировка и отказ API-реплики
|
||
|
||
Запустить несколько взаимозаменяемых экземпляров API за единой точкой входа и сохранить корректность при остановке одного из них.
|
||
|
||
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
|
||
|
||
[Карта курса](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)
|
||
|
||
## Откуда начинаем
|
||
|
||
Нужен минимум lab2: PostgreSQL, общие действующие сессии, миграции. Добавляются X-Instance-Id и обязательный Idempotency-Key при отправке сообщения.
|
||
|
||
**Архитектура:** Клиент → LB → API × 2+ → общие PostgreSQL и хранилище сессий. Compose или Swarm — на выбор.
|
||
|
||
## Реализованный запуск Compose + Nginx
|
||
|
||
В этой реализации публичный порт есть только у Nginx. API масштабируется как
|
||
один Compose-service без `container_name`; сессии, сообщения и результаты
|
||
идемпотентности находятся в общей PostgreSQL. Redis используется только как
|
||
необязательный общий cache с безопасным fallback в PostgreSQL.
|
||
|
||
Из чистого clone выполните одну последовательность (после копирования
|
||
`.env.example` замените локальный пароль):
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
# отредактировать DATABASE_PASSWORD в .env
|
||
docker compose --env-file .env build api
|
||
docker compose --env-file .env up -d postgres redis
|
||
docker compose --env-file .env run --rm migrate
|
||
docker compose --env-file .env up -d --scale api=2 api nginx
|
||
curl --fail http://localhost:8080/health/ready
|
||
```
|
||
|
||
`migrate` — отдельный one-shot процесс; в API Flyway отключён. При обновлении
|
||
схемы сначала выполняется совместимая миграция той же командой, затем API
|
||
заменяются по одной. Nginx 1.27.4 обновляет адреса `api` через Docker DNS каждые
|
||
2 секунды, применяет `least_conn`, не использует sticky session и повторяет
|
||
ошибку соединения/502/503/504 на другой реплике. Readiness проверяет завершение
|
||
V3-схемы, доступность PostgreSQL и состояние Spring `ACCEPTING_TRAFFIC`.
|
||
|
||
Проверки после запуска:
|
||
|
||
```sh
|
||
make test
|
||
make test-idempotency
|
||
chmod +x scripts/stop-one.sh scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
В Windows PowerShell те же проверки можно выполнить с
|
||
`scripts/stop-one.cmd` и `scripts/restart.cmd`; `.sh` остаются основными
|
||
POSIX hooks для CI/защиты.
|
||
|
||
`test-idempotency` одновременно отправляет 32 одинаковых запроса и требует,
|
||
чтобы ответы пришли минимум от двух `X-Instance-Id`, но в истории появилось
|
||
ровно одно сообщение. `stop-one.sh` сопоставляет полученный `X-Instance-Id` с
|
||
hostname контейнера и останавливает только эту API-реплику. После демонстрации
|
||
её можно вернуть командой:
|
||
|
||
```sh
|
||
docker compose --env-file .env up -d --scale api=2 api
|
||
```
|
||
|
||
### Проверки уровня 4
|
||
|
||
Обе реплики последовательно останавливаются с восстановлением между опытами:
|
||
|
||
```sh
|
||
make test-failover-each \
|
||
ACTION_SCRIPT=scripts/stop-one.sh \
|
||
RESTORE_SCRIPT=scripts/restore-api.sh
|
||
```
|
||
|
||
В Windows используйте `.cmd` варианты. Тест сохраняет по каждой реплике
|
||
successful RPS, число ошибок и время первой успешной операции после stop.
|
||
|
||
Эквивалент rolling update для Compose — последовательная замена каждого
|
||
исходного API-контейнера с ожиданием readiness новой реплики перед заменой
|
||
следующей. Проверка одновременно держит четыре потока записи:
|
||
|
||
```sh
|
||
make test-rolling ACTION_SCRIPT=scripts/rolling-update.sh
|
||
```
|
||
|
||
Nginx обновляет Docker DNS раз в 2 секунды. Сетевой отказ определяется не
|
||
позднее connect timeout 500 ms, зависший ответ — read timeout 4 s; адрес
|
||
пассивно исключается на 2 s после первой ошибки. Поэтому верхняя граница
|
||
обнаружения одного неотвечающего backend — 4 s, а две upstream-попытки
|
||
укладываются примерно в 8.5 s. Docker readiness каждой API проверяется раз в
|
||
2 s с timeout 2 s. Nginx OSS использует readiness при начальном/операторском
|
||
запуске через Compose и пассивное исключение во время работы.
|
||
|
||
Для `POST /chats/{id}/messages` Nginx может повторить запрос на второй backend
|
||
даже после начала отправки: тело буферизуется, а обязательный общий
|
||
`Idempotency-Key` делает такой retry безопасным. Для остальных POST параметр
|
||
`non_idempotent` не включён, чтобы не размножать пользователей или чаты.
|
||
|
||
## Отказ узла: отдельный трёхузловой Swarm-стенд
|
||
|
||
Дополнительные студенческие проверки находятся в `student_tests/`; исходные
|
||
тесты курса в `tests/` не перемещаются, Spring-тесты остаются в `src/test/java`.
|
||
|
||
Для трека отказа узла добавлен одноразовый локальный стенд из трёх настоящих
|
||
Docker daemons в privileged DinD-контейнерах: manager и два workers. Он не
|
||
заменяет основной Compose-стенд и использует отдельный порт `18080`.
|
||
|
||
```powershell
|
||
make swarm-up
|
||
make test-node-failover PYTHON=python
|
||
make swarm-down
|
||
```
|
||
|
||
`swarm-up` строит образы из текущего исходного кода, публикует их в одноразовый
|
||
локальный registry, доступный всем узлам,
|
||
создаёт overlay network, отдельно выполняет миграцию и запускает API с двумя
|
||
replicas и `max_replicas_per_node=1`. Тест выбирает worker с API-задачей и
|
||
жёстко останавливает весь Docker daemon этого узла. Swarm должен создать новую
|
||
API-задачу на свободном узле; через LB одновременно выполняются чтения/записи,
|
||
после чего проверяются старые и подтверждённые во время отказа сообщения.
|
||
|
||
Защищён только API worker. PostgreSQL, Redis и Nginx закреплены на manager;
|
||
PostgreSQL использует локальный volume и не реплицирован. Потеря manager/DB
|
||
узла не переживается и в отчёте не заявляется. Один manager также означает
|
||
SPOF control plane; DinD underlay и физический host остаются SPOF эксперимента.
|
||
|
||
## Что сделать
|
||
|
||
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
|
||
|
||
# После реализации запустите свой сервер/стенд по REPORT.md.
|
||
# По умолчанию тест использует http://localhost:8080.
|
||
make test
|
||
```
|
||
|
||
`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
|
||
|
||
```sh
|
||
# 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.
|
||
```
|
||
|
||
|
||
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
|
||
|
||
```sh
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||
make validate PYTHON=.venv/bin/python
|
||
```
|
||
|
||
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте.
|
||
|
||
## Сценарий защиты
|
||
|
||
1. Запустить стенд и показать ≥2 разных X-Instance-Id через LB с одной сессией.
|
||
2. Запустить make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Скрипт теста выполняет запросы во время action, учитывает ошибки и повторяет сообщения с исходным ключом.
|
||
3. Показать, какой контейнер действительно остановлен; заголовок сам по себе не доказательство разных процессов. Повторить для второй реплики после восстановления первой.
|
||
4. Проверить restart всего стенда с сохранением volumes и неизменным токеном. Для 4/5 — соответствующие эксперименты.
|
||
|
||
## Что должно быть в PR
|
||
|
||
compose.yaml или stack.yaml, конфигурация LB, scripts/restart.sh, scripts/stop-one.sh, Dockerfile, миграции, результаты отказов.
|
||
|
||
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
|
||
|
||
## Вопросы на защите
|
||
|
||
- Чем отказ процесса отличается от отказа узла?
|
||
- Почему 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/)
|