diff --git a/REPORT.md b/REPORT.md index c2679005..93f70072 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,72 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Бондаренко Мария Максимовна, БПИ2302 +- Целевая оценка: 4 -## Запуск из чистого clone +## 1. Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +### Зависимости и предусловия +- Установленный Docker и Docker Compose. +- Python 3.9+ для запуска локальных тестов. -## Архитектура и решения +### Пошаговые команды запуска и проверки -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +1. Создать .env из шаблона и заполнить локальные секреты. Задать в .env: POSTGRES_PASSWORD, SECRET_HMAC_KEY +2. Собрать и запустить стенд: + docker compose --env-file .env up -d --build +3. Дождаться готовности всех сервисов: + docker compose ps + curl -s http://localhost:8080/health/ready +4. Публичные проверки: + make test + make test-persistence ACTION_SCRIPT=scripts/restart.sh + make test-failover ACTION_SCRIPT=scripts/stop-one.sh +При повторном запуске последнего теста (test-failover) необходимо перезапустить контейнеры api-1 и api-2 с помощью команды docker compose start api-1 api-2 или docker compose restart +5. Остановка и очистка данных: + docker compose stop + docker compose down -v -## Доказательства критериев +## 2. Архитектура и решения -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +- Точка входа и балансировка: Публичный доступ осуществляется строго через единую точку входа Nginx. Балансировщик распределяет HTTP-запросы между двумя API-репликами (api-1:8080 и api-2:8080) по алгоритму Round-Robin +- Пассивный Health Check и отказоустойчивость LB: В nginx настроены параметры max_fails=1 fail_timeout=5s и директива proxy_next_upstream error timeout http_502 http_503 http_504. В случае временной недоступности или сбоя одной из реплик Nginx автоматически перенаправляет запрос на соседний экземпляр без выдачи ошибки клиенту +- Идентификация реплик: Каждый ответ API содержит заголовок X-Instance-Id, жестко заданный через переменные окружения, что позволяет отслеживать конкретную реплику, обслужившую запрос +- Изолированный запуск миграций: Миграция структуры БД выделена в самостоятельный одноразовый сервис migrate, который ожидает готовности PostgreSQL и выполняет migrations/init.sql до старта API-реплик, предотвращая состояние гонки при создании таблиц +- Атомарная идемпотентность: В PostgreSQL создана таблица idempotency_keys с первичным ключом (user_id, method, path, key). Обработка Idempotency-Key выполняется в рамках одной транзакции СУБД с использованием INSERT ... ON CONFLICT DO NOTHING, что исключает появление дубликатов сообщений при параллельных повторных запросах через разные реплики API +- Безопасность и лимиты: Порты бэкендов api-1 и api-2 не публикуются наружу в обход Nginx. В compose.yaml для всех сервисов заданы аппаратные ограничения ресурсов. В Dockerfile и compose.yaml настроен Graceful Shutdown + + +## 3. Доказательства выполнения критериев + +| Критерий README | Команда / Сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| Проверка публичного API | make test | PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. | tests/smoke.py | +| Сохранение данных при перезапуске | make test-persistence ACTION_SCRIPT=scripts/restart.sh | PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. | scripts/restart.sh, tests/resilience.py | +| Выдерживание отказа реплики API | make test-failover ACTION_SCRIPT=scripts/stop-one.sh | PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. | scripts/stop-one.sh, tests/resilience.py | +| Поочерёдное обновление | ./scripts/rolling-update.sh | Поочерёдная перезаборка api-1 и api-2 с ожиданием /health/ready и перезагрузкой Nginx | scripts/rolling-update.sh | +| Нагрузочное тестирование при Rolling Update | python3 tests/load.py --duration 60 --concurrency 4 --output evidence/load-rolling.json | | evidence/load-rolling.json | +| Ресурсные лимиты и изоляция | Описание в compose.yaml | Все сервисы имеют лимиты CPU/RAM; API доступен только через Nginx | compose.yaml | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +## 4. Эксперименты и отказы -## Эксперименты и отказы +### 4.1. Тест отказоустойчивости -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +В ходе автоматизированного теста resilience.py производилась параллельная запись сообщений с проверкой балансировки: +- Наблюдаемые реплики до отказа: 2 (api-replica-1, api-replica-2) +- Воздействие: Выполнение scripts/stop-one.sh и принудительная остановка реплики TARGET_INSTANCE_ID с таймаутом docker compose stop -t 3 +- Результат: Зафиксировано 77 успешных записей при 2 неудачных попытках в момент переключения; время восстановления составило 1.125 сек. Все подтвержденные сообщения сохранились без дублирования -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +### 4.2. Нагрузка во время поочерёдной замены -## Ограничения и следующие шаги +Во время проведения поочерёдного обновления контейнеров (scripts/rolling-update.sh) выполнялся нагрузочный сценарий tests/load.py: +- Параметры: Длительность 60 с, параллелизм (concurrency) = 4. +- Метрики: +- - Успешные запросы: 1272 +- - Ошибки: 0 (error_ratio: 0.0) +- - Средняя пропускная способность: 21.112 RPS +- - Латентность успешных запросов: p50 = 188.0 ms, p95 = 297.0 ms, p99 = 406.0 ms -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +## 5. Ограничения и следующие шаги + +- Пассивный Health Check в Nginx OSS: Балансировщик Nginx OSS использует пассивное обнаружение отказов и повторный запрос через proxy_next_upstream. Активный поллинг ендпоинта /health/ready со стороны балансировщика без использования сторонних модулей или Nginx Plus не поддерживается +- Ограничения хоста: Тестирование проводилось на локальном стенде (Windows/Docker Desktop). При дальнейшем масштабировании узлов потребуется переход на оркестрацию уровня Docker Swarm \ No newline at end of file diff --git a/evidence/load-rolling.json b/evidence/load-rolling.json index 5e2f4c14..a06838e8 100644 --- a/evidence/load-rolling.json +++ b/evidence/load-rolling.json @@ -2,16 +2,16 @@ "lab": 3, "workload": "closed-loop POST messages; no automatic retries", "requested_duration_seconds": 60.0, - "elapsed_seconds": 60.172, + "elapsed_seconds": 60.25, "concurrency": 4, - "successful_requests": 2801, + "successful_requests": 1272, "failed_requests": 0, "error_ratio": 0.0, - "successful_rps": 46.55, + "successful_rps": 21.112, "successful_latency_ms": { - "p50": 47.0, - "p95": 188.0, - "p99": 875.0 + "p50": 188.0, + "p95": 297.0, + "p99": 406.0 }, "note": "Latency percentiles cover successes only. Timeouts/errors are counted separately; closed-loop has coordinated omission and client overhead." }