143 lines
20 KiB
Markdown
143 lines
20 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
Целевая оценка: **4** (весь уровень 3 и все пункты уровня 4). Автор и группа не указаны; их нужно заполнить перед сдачей. Трек оценки 5 не заявляется.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Engine с поддержкой Swarm, Python 3.9+, свободный порт 8080 и доступ к Docker Hub при первой сборке. Проверенная среда: macOS arm64 → Colima/Ubuntu → один Swarm manager. Все контейнеры и хранилища поднимаются из этого репозитория. Go на хосте нужен только для `make test-own`; контейнерные тесты используют Go 1.26.4 из Dockerfile.
|
||
|
||
```sh
|
||
make up
|
||
make test
|
||
make test-integration
|
||
make test-persistence
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
make wait
|
||
make test-grade4
|
||
make measure-load
|
||
make down
|
||
```
|
||
|
||
`make up` инициализирует Swarm, если он ещё не активен, помечает локальный узел для постоянных хранилищ, создаёт случайные локальные секреты и Docker secrets, собирает API и goose, запускает хранилища, применяет миграции отдельным одноразовым Swarm job и дожидается готовности двух API через HAProxy. Повторный запуск применяет миграции **до** обновления API, затем последовательно заменяет реплики. Значения секретов в командах и выводе не показываются. Файлы конфигурации окружения автоматически не загружаются; параметры передаются переменными процесса, например `PORT=8081 make up`.
|
||
|
||
Рабочий адрес: <http://localhost:8080>, Swagger: <http://localhost:8080/swagger/>. `STACK_NAME` по умолчанию `mtusi-lab3`; `API_REPLICAS=2`. Собственный тест уровня 4 рассчитан именно на две реплики. Пример: `STACK_NAME=demo PORT=8081 make up`; те же переменные нужны последующим командам.
|
||
|
||
Используется **Docker Swarm**, `stack.yaml` — основной стенд. `compose.yaml`, `scripts/compose.sh`, `tests/own/grade4.py` оставлены как материалы перенесённой lab2; команды текущей работы используют `scripts/swarm.py` и `tests/own/swarm_grade4.py`.
|
||
|
||
```sh
|
||
# Структура, OpenAPI и локальные unit/race-тесты:
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||
make test-all
|
||
# Состояние, версии, контейнеры, лимиты, опубликованные порты:
|
||
python3 scripts/swarm.py status
|
||
make migrate-status
|
||
# Принудительная поочерёдная замена API:
|
||
make rolling-update
|
||
```
|
||
|
||
`make down` удаляет сервисы и сети стека, **сохраняя volumes и Swarm secrets**. Для намеренного удаления учебных данных после остановки и удаления контейнеров: `docker volume rm mtusi-lab3_postgres_data mtusi-lab3_redis_data`. Это необратимо; для обычной остановки команда не нужна. Swarm автоматически не выключается, чужие контейнеры не останавливаются.
|
||
|
||
### Образы и доступность узлам
|
||
|
||
Закреплены PostgreSQL `17.6-alpine3.22`, Redis `7.4.5-alpine3.21`, HAProxy `3.2.6-alpine`; Go 1.26.4 и Alpine 3.23 в Dockerfile закреплены также digest. `make up` собирает `mtusi-messenger:lab3` и `mtusi-migrations:lab3` в локальном Docker Engine. На одном узле эти образы доступны всем tasks, поэтому используется `--resolve-image never`. Контейнер тестов отдельно собирается целью `tests`.
|
||
|
||
Для нескольких узлов образы нужно заранее опубликовать в доступном всем узлам registry, например:
|
||
|
||
```sh
|
||
docker build -t registry.example.edu/student/messenger:lab3-v1 .
|
||
docker build --target migrations -t registry.example.edu/student/migrations:lab3-v1 .
|
||
docker push registry.example.edu/student/messenger:lab3-v1
|
||
docker push registry.example.edu/student/migrations:lab3-v1
|
||
```
|
||
|
||
В `API_IMAGE`/`MIGRATIONS_IMAGE` следует передать опубликованные имена, лучше `@sha256:...`. При ручном развёртывании: `docker stack deploy --with-registry-auth -c stack.yaml mtusi-lab3`, предварительно создав secrets и выполнив миграционный job по описанному порядку. Это **не проверенный многоузловой режим**: локальные диагностические helpers используют `docker inspect/exec` контейнеров на текущем engine; для удалённых tasks их требуется адаптировать. Автоматический `make up` рассчитан на один узел.
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
localhost:8080 → HAProxy (Swarm service, host published port)
|
||
↓ HTTP round-robin, readiness checks, Docker DNS
|
||
API task 1 API task 2
|
||
↘ ↙
|
||
PostgreSQL + Redis AOF
|
||
```
|
||
|
||
Только HAProxy публикует порт. API находятся в overlay `backend` и `data`; PostgreSQL/Redis — только в `data`. LB не подключён к `data` и не получает секреты. PostgreSQL получает пароль; API — пароль БД и общий ключ курсоров. Сессии общие в Redis, пароль проверяется через scrypt; хранение токенов, пагинация, SQL-транзакции и ограничения перенесены из lab2. Sticky sessions отсутствуют. `X-Instance-Id` равен Swarm Task ID, стабилен для жизни процесса и присутствует в том числе в ответах об ошибках.
|
||
|
||
HAProxy использует `tasks.api` и `server-template` на 8 адресов. DNS обновляется с `hold valid/obsolete = 1s`; API service использует `endpoint_mode: dnsrr`. `host` относится к публикации **порта LB**, а не к сети API. Такой режим проверен с Colima, где ingress routing mesh не обеспечил доступ с macOS. У LB одна task, её замена выполняется stop-first; отказ самого LB не входит в заявленную доступность.
|
||
|
||
| Компонент | CPU limit | RAM limit | Публичный порт |
|
||
| --- | --- | --- | --- |
|
||
| API, каждая из двух реплик | 1 | 256 MiB | нет |
|
||
| PostgreSQL | 1 | 512 MiB | нет |
|
||
| Redis | 0,5 | 128 MiB | нет |
|
||
| HAProxy | 0,5 | 128 MiB | 8080 |
|
||
| Одноразовые миграции | 1 | 128 MiB | нет |
|
||
| Контейнер Go-тестов | 1 | 1 GiB | нет |
|
||
|
||
### Идемпотентность
|
||
|
||
`Idempotency-Key` обязателен и проверяется по `[A-Za-z0-9._:-]{1,128}`. Уникальный индекс PostgreSQL `(sender_id, chat_id, idempotency_key)` задаёт область пользователя и пути; единственная операция — `POST /chats/{id}/messages`. Ключ и результат находятся в одной строке сообщения: нет окна между сохранением сообщения и фиксацией результата.
|
||
|
||
`INSERT ... ON CONFLICT DO NOTHING RETURNING created_at` либо создаёт сообщение, либо ждёт конкурента на уникальном индексе. После конфликта отдельный SELECT в READ COMMITTED видит зафиксированного победителя. Совпадающий текст даёт то же Message и 201; другой текст — 409. JSON декодируется до сравнения, поэтому форматирование JSON не влияет на результат. В lab3 тело содержит только `text`; вложения не реализуются до lab4. Все повторы заново проверяют сессию и членство. 5xx не записываются как результат. Если INSERT успел закоммититься до обрыва ответа, следующий запрос возвращает сохранённое сообщение.
|
||
|
||
Ключи хранятся вместе с сообщениями бессрочно, что покрывает требуемые 24 часа. Очистка/удаление сообщений не реализованы. Старые строки lab2 имеют NULL-ключ, индекс разрешает несколько NULL.
|
||
|
||
### Готовность, таймауты и SIGTERM
|
||
|
||
- HAProxy проверяет `/health/ready` каждую 1 секунду, `fall=2`, `rise=1`, connect/check timeout по 1 секунде. При двух неуспешных проверках backend исключается; консервативный бюджет обнаружения — около 4 секунд плюс планирование ОС. Восстановление проверяется фактическими запросами, а не только настройками.
|
||
- Readiness проверяет обе зависимости с общим дедлайном 2 секунды; отдельная операция хранилища ограничена 1 секундой. `/health/live` не зависит от БД/Redis.
|
||
- HTTP: ReadHeader 5s, Read 10s, Write 15s, Idle 60s; HAProxy client/server timeout 20s. Автоматические HTTP retry отключены: клиент явно повторяет неопределённый POST сообщения с тем же ключом.
|
||
- При SIGTERM приложение сразу переводится в draining: новые бизнес-запросы и readiness получают 503, уже выполняющиеся запросы продолжаются. Через 3 секунды для исключения backend вызывается graceful Shutdown с дедлайном 8s. Swarm даёт контейнеру 15s до SIGKILL.
|
||
- Rolling update API: `parallelism=1`, `start-first`, delay 5s, monitor 15s, автоматический rollback при неудаче. Healthcheck контейнера проверяет реальную readiness с интервалом 2s. Общие БД, Redis, ключи и сессии не заменяются при обновлении API.
|
||
|
||
### Миграции
|
||
|
||
Goose запускается отдельным `replicated-job` с одной task. Фиксированное имя job не позволяет двум helpers одновременно запустить миграцию одного стека. API миграции не выполняют. Миграция 002 аддитивна: добавляет nullable column и unique index, старые lab2 INSERT остаются допустимы. На первом запуске API масштабируются с 0 до 2 только после успеха миграций.
|
||
|
||
Создание индекса обычное, не `CONCURRENTLY`, и на большой таблице может блокировать записи. Поэтому переход со значительной историей lab2 требует окна обслуживания; безостановочное изменение больших схем не заявляется. Проверенный rolling update выполняет замену совместимой версии приложения на уже подготовленной схеме. Откат схемы при работающих API не выполняется.
|
||
|
||
## Проверки и результаты
|
||
|
||
Реальные результаты текущей работы находятся в файлах `evidence/swarm-*`. Старые файлы без префикса перенесены из lab2 и не служат доказательством lab3. Публичные `tests/smoke.py`, `tests/resilience.py`, `tests/load.py` и контракт не ослаблялись.
|
||
|
||
| Требование | Проверка | Доказательство |
|
||
| --- | --- | --- |
|
||
| API lab3, ключи, права, сессии | `make test` | `evidence/swarm-smoke.txt` |
|
||
| Миграции до API, повторный deploy | `make up`, `make migrate-status` | `evidence/swarm-deploy.txt`, `swarm-migrations.txt` |
|
||
| Общие данные и ограничения, гонки, rollback, SQL-пагинация | `make test-integration` | `evidence/swarm-integration.txt` |
|
||
| Unit/race-тесты | `go test -race -count=1 ./...` | `evidence/swarm-go-tests.txt` |
|
||
| Реальные две реплики, порты, CPU/RAM | `python3 scripts/swarm.py status` | `evidence/swarm-status.json` |
|
||
| Полный перезапуск API/LB/БД/Redis, прежний токен | `make test-persistence` | `evidence/swarm-persistence.txt`, snapshots до/после, `swarm-restart-verification.txt` |
|
||
| Публичный сценарий отказа | `make test-failover` | `evidence/swarm-failover.txt` |
|
||
| Остановка обеих исходных API tasks по очереди | `make test-grade4` | `evidence/swarm-grade4.json`, `.txt` |
|
||
| Параллельный одинаковый ключ через разные реплики | 16 одновременных запросов, сравнение ответов и истории | `evidence/swarm-grade4.json` |
|
||
| Rolling update под нагрузкой | четыре клиента параллельно `service update --force` | `evidence/swarm-grade4.json` |
|
||
| Нагрузка и ресурсы | `make measure-load` | `evidence/swarm-load.json`, `swarm-resources.json` |
|
||
|
||
При отказах hook сопоставляет `TARGET_INSTANCE_ID` с конкретной running task именно этого стека, останавливает её контейнер через SIGKILL и не перезапускает старую task. Swarm создаёт новую с другим ID. Собственный сценарий запоминает обе исходные task, сначала останавливает одну, ждёт восстановления двух реплик, затем останавливает вторую. Проверяется исчезновение остановленного ID и отсутствие дублей после неопределённых запросов.
|
||
|
||
Нагрузка при отказах и обновлении: 4 клиента, closed loop, POST + чтение с общей сессией, пауза 30ms между итерациями. В метриках RPS — успешные итерации записи с последующим чтением; ошибки учитывают оба запроса. После каждого воздействия перечитывается вся история, сравниваются подтверждения и проверяются уникальные тела сообщений. Ключ неопределённого POST сохраняется до успешного повтора. Отдельная нагрузка: 3s прогрева, 30s POST, concurrency 4, без retry.
|
||
|
||
Проверено 19 октября 2026 года: Docker 29.5.2, Ubuntu 24.04.4 arm64 в Colima, **2 vCPU и 1,91 GiB RAM** (точные значения в `swarm-environment.json`).
|
||
|
||
| Воздействие | Успешные записи + чтения | Неудачные попытки | Успешные RPS | Восстановление |
|
||
| --- | --- | --- | --- | --- |
|
||
| Отказ API 1 | 1181 | 2 | 75.954 | 0.547 s |
|
||
| Отказ API 2 | 1045 | 7 | 67.552 | 1.314 s |
|
||
| Rolling update (43.729 s) | 3333 | 0 | 76.22 | максимальный интервал без успеха 0.084 s |
|
||
|
||
Во всех сценариях подтверждённые сообщения сохранились, повтор старого ключа вернул исходный результат, дубли отсутствуют. Отдельный публичный failover: 113 успешных записей, 2 неудачные попытки, восстановление за 1,913 s. Полный restart заменил реальные контейнеры всех четырёх сервисов; volumes и имена секретов совпали, прежний токен остался действительным.
|
||
|
||
Отдельная нагрузка: **673.966 RPS**, 20229 успешных POST за 30.015 s, ошибок 0. p50/p95/p99 = 5.606/8.855/11.532 ms. За измерение число сообщений выросло с 14882 до 35111; собрано 10 снимков Docker stats. Синтетические данные сохраняются после тестов; повторный запуск увеличивает историю.
|
||
|
||
|
||
## Ограничения и источники
|
||
|
||
Один manager и один физический/виртуальный узел; нет HA PostgreSQL, Redis, LB или самого узла. Постоянные хранилища закреплены на узле с label `mtusi_lab3_storage=true`; локальные volumes не превращаются в распределённое хранилище. Потеря этого узла приводит к недоступности всего стенда. При аварийной остановке API краткие ошибки разрешены и измеряются. HTTP используется только для локального учебного стенда с синтетическими данными.
|
||
|
||
Это один воспроизводимый прогон, не оценка максимальной производительности: closed-loop генератор и клиент ограничивают RPS, есть coordinated omission. Для сравнений результаты нужно повторять на одинаковых ресурсах. Принудительная замена той же версии доказывает поочерёдный рестарт под нагрузкой, но не совместимость произвольных будущих версий.
|
||
|
||
Использованы Go/Echo, pgx, go-redis, goose и HAProxy; документация Docker Swarm, HAProxy health checks/DNS, PostgreSQL INSERT/ON CONFLICT. Реализация и проверки подготовлены при помощи Codex; фактические выводы команд сохранены в evidence. README задания сохранён без изменений.
|