Files
mtusi2026lab3/REPORT.md
T

84 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 3. k3s, Pingap и взаимозаменяемые API
Автор: Медведев Андрей Михайлович, БПИ2303. Целевая оценка — 5, трек 1 «Цена масштабирования». Основной стенд перенесён на k3s + Pingap по выбору автора. Исходное задание предлагает Compose/Swarm; принятие альтернативы преподавателем не заявляется. Оригинальные README, COURSE, контракты и публичные tests сохранены.
Код, тесты и отчёт подготовлены с помощью Codex. Инструкция запуска — [RUN.md](RUN.md). Исторический вариант Compose/HAProxy описан в [архивном отчёте](docs/archive/compose-report.md); его численные результаты не выдаются за измерения Pingap.
## Архитектура и запуск
Клиент обращается к localhost:28203. Порт ведёт через k3d к Service типа LoadBalancer и Deployment Pingap. Pingap получает адреса API через headless Service с clusterIP: None; отдельный ingress-controller не используется, Traefik выключен при создании кластера. Внешние маршруты находятся в TOML в git и попадают в ConfigMap через Kustomize.
В стенде один server k3s 1.37.1 и две API-реплики. Pingap 0.16.0 и сторонние образы закреплены digest. Собственный образ получает tag из hash Dockerfile и backend. Перед использованием проверяются pinned RepoDigest, соответствие alias и наличие образа в containerd. Экспорт linux/amd64 устраняет ошибку импорта неполного многоплатформенного index Docker29.
PostgreSQL и Valkey общие для API. Каждая API возвращает реальное имя своего Pod в X-Instance-Id. Сессии проверяются в PostgreSQL при каждом защищённом запросе; Valkey кэширует только неизменяемые профили. Sticky sessions нет. В API нет постоянных пользовательских файлов или локальных сессий. PostgreSQL и Valkey используют PVC; у API нет опубликованного host-порта в обход Pingap.
Миграции выполняет отдельный Job до запуска API. Readiness PostgreSQL проверяет TCP, затем runner выполняет настоящий SELECT 1: временный сервер инициализации PostgreSQL по Unix-сокету не должен запускать миграции преждевременно. Повторный up сохраняет volumes; произвольные несовместимые миграции под трафиком не заявляются.
## Общая идемпотентность
Idempotency-Key обязателен для POST сообщения. Его область — пользователь и чат, TTL — 24 часа. PostgreSQL хранит hash семантического payload и ссылку на результат. Резервирование ключа, списание квоты и создание сообщения находятся в одной транзакции. Конкурентные одинаковые запросы получают один Message с 201, другой payload даёт 409; откат не сохраняет сообщение или окончательный результат ключа.
Вход Basic разрешён только для создания сессии, бизнес-запросы требуют opaque Bearer. Пароли используют Argon2id, токены — 32 случайных байта с хранением только SHA-256. Logout удаляет persisted session и действует на всех репликах. Пагинация ограничена 100 элементами и использует ключ (created_at,id); это не snapshot конкурентных транзакций.
## Ресурсы, обнаружение и остановка
По умолчанию каждая API имеет limit 1 CPU и 512 МиБ, GOMEMLIMIT=400MiB; PostgreSQL — 2 CPU/768 МиБ, Valkey — 0,25 CPU/128 МиБ, Pingap — 0,5 CPU/128 МиБ. K3d server ограничен 8 ГиБ. Пул PostgreSQL API по умолчанию равен 8, одновременно выполняются не более четырёх HTTP-запросов, очередь ограничена 32, ожидание очереди — 1 секунда. Обычный request context равен 5 секундам; SQL connect/statement/lock timeouts — 1/2/1 секундам.
DNS discovery Pingap обновляется раз в секунду. Активная HTTP-проверка /health/ready имеет частоту 1 секунду и connection/read timeout по 1 секунде. Это настройки обнаружения, а фактическое восстановление проверяется публичным failover-сценарием. При shutdown API предусмотрены preStop 15 секунд и собственный drain до 8 секунд при pod grace 35 секунд. Для Pingap заданы последовательные grace 8 + shutdown 10 секунд при pod grace 25 секунд.
Аварийный hook scale-down выбирает фактически обслуживший Pod, проверяет UID и нативный container ID и останавливает именно его процесс. CRI inventory подтверждает отсутствие RUNNING-процесса этого Pod UID, включая возможную смену контейнера при устаревшем Pod.status. Hook оставляет одну API-реплику; configure возвращает две. Штатный rollout использует maxSurge=1, maxUnavailable=0 и ждёт завершения старых подов, а не только Deployment Ready.
## Подтверждённые проверки k3s-варианта
- Публичный smoke и HTTP acceptance прошли: регистрация, Basic/Bearer, logout, rollback, pagination, конкурентная регистрация, двенадцать одинаковых POST, конфликт payload и одна сессия через разные реальные API. Вывод — evidence/k3s/smoke.txt и acceptance.txt.
- Два публичных failover-сценария подтвердили доступ к данным и отсутствие дублей после остановки разных API-процессов. Pod UID, container ID и survivor записаны отдельно; файлы — evidence/k3s/failover-1.txt, failover-2.txt и stopped-*-after.json. Эти функциональные проверки не используются как бенчмарк пропускной способности host.
- Полный restart API, PostgreSQL, Valkey и Pingap сохранил подтверждённые сообщения и исходный токен. before/after принадлежат одному run_id; отдельная проверка требует замены всех исходных workload Pod UID. Файлы — evidence/k3s/persistence.txt и restart-postcondition.txt.
- Проверка stdin через настоящий scoped wrapper выполнила SELECT в PostgreSQL. Cleanup дополнительно читает нулевое количество собственных пользователей после удаления; пустой stdin и один exit0 psql не считаются успехом.
- Unit-тесты проверяют чужой cluster/context, Namespace UID, partial claim, image identity, target overrides, обходы resource scope, сохранение основной ошибки при teardown и блокировку измерений при активной или неизвестной игре. Формат и lint новых TypeScript helpers проверены отдельно.
- Offline skeleton check и полная OpenAPI validation прошли. Go-код и нормативные контракты при переносе не менялись; его предыдущие race/lint результаты остаются в evidence/ и относятся к тому же backend.
## Трек 1. Цена масштабирования
Полная серия k3s/Pingap выполнена на AMD Ryzen 7 5700X, 8 cores/16 threads, Linux x86_64. До и после измерений game-running возвращал ровно 1. Отдельный случайный кластер и его БД принадлежали только эксперименту; после завершения кластер удалён до записи complete summary. Исходные данные — [summary.json](evidence/k3s/research/run-R4F28Q/summary.json), hardware.json и отдельные JSON каждого прогона.
Профиль — closed-loop POST текстовых сообщений одного отправителя, concurrency 16, длительность 5 секунд, два повтора. БД очищается между прогонами. Перед измерением runner ждёт rollout, удаления terminating Pod и реального DNS/HTTP через Pingap, проверяет число API, limits и pool_max. Генератор создаёт пользователей, сессию и чат до запуска часов; отдельного длительного прогрева нет. После каждого прогона проверяются сохранённые сообщения и неизменность Pod UID. В каждом наборе осталось от 398 до 612 сообщений.
В серии с постоянным бюджетом суммарные limits API равны 2 CPU/2048 МиБ: одна API получает 2 CPU/2048 МиБ, две — по 1 CPU/1024 МиБ, четыре — по 0,5 CPU/512 МиБ. В растущей серии каждая API получает 1 CPU/512 МиБ: всего 1/2/4 CPU и 512/1024/2048 МиБ. Остальные компоненты не масштабируются. Requests API остаются по 100m CPU/128 МиБ; это одинаковый опыт по суммарным limits, без утверждения о пропорциональных reservations.
Таблица показывает среднее двух успешных RPS и среднее двух p50/p95/p99; ошибки суммированы. Это средние перцентилей, а не перцентили объединённого распределения.
| Серия / API | Успешные RPS | p50, мс | p95, мс | p99, мс | Ошибки |
| --- | ---: | ---: | ---: | ---: | ---: |
| Постоянный бюджет / 1 | 117,05 | 133,48 | 175,29 | 204,46 | 0 |
| Постоянный бюджет / 2 | 115,47 | 133,55 | 275,40 | 363,95 | 0 |
| Постоянный бюджет / 4 | 98,08 | 121,03 | 467,08 | 1025,96 | 0 |
| Рост бюджета / 1 | 116,82 | 129,36 | 171,00 | 200,46 | 0 |
| Рост бюджета / 2 | 104,94 | 141,83 | 329,44 | 529,45 | 0 |
| Рост бюджета / 4 | 116,12 | 108,49 | 337,80 | 484,03 | 0 |
| Пул 8 / 1 | 117,10 | 129,32 | 175,24 | 225,22 | 0 |
| Пул 1 / 1 | 113,17 | 133,45 | 187,42 | 279,27 | 0 |
График [масштабирования](evidence/k3s/research/run-R4F28Q/scaling.svg) показывает средние и диапазоны двух повторов; график [пула](evidence/k3s/research/run-R4F28Q/pool.svg) показывает средние столбцами. Во всех 16 прогонах HTTP-ошибок было ноль. Самый большой наблюдавшийся API cgroup memory.peak — 108,29 МиБ. Summary содержит реальные CPU usage counters и память каждого API, а также десять снимков pg_stat_activity за прогон. CPU counters накопительные; доля загрузки CPU из одного такого снимка не выводится.
### Насыщение и подтверждённое улучшение
Рост числа API не дал пропорционального роста throughput. При постоянном бюджете средние RPS равны 117,05 → 115,47 → 98,08; при росте ресурсов — 116,82 → 104,94 → 116,12. Разброс у четырёх API заметен: 77,31–118,84 RPS в постоянном бюджете. Поэтому это наблюдаемое насыщение данного горячего отправителя, а не точный универсальный предел сервера.
В постоянной серии суммы числа сессий, ожидающих Lock/transactionid, по двадцати снимкам равны 58 → 133 → 244 при 1 → 2 → 4 API; IO/WalSync присутствует в 18/19/20 снимках. Это счётчик наблюдений, а не число уникальных сессий или процент времени. Код CreateMessage в repository.go резервирует idempotency key и вызывает ChargeMessage в одной транзакции; SQL обновляет message_count одной строки users до COMMIT. Такой отправитель сериализует записи по общей строке, а COMMIT ждёт WAL. Эти наблюдения объясняют, почему добавление API не устраняет узкое место PostgreSQL.
Подтверждённое улучшение для допустимой отказоустойчивой конфигурации — использовать две API вместо четырёх при тех же 2 CPU/2048 МиБ суммарных limits. Средний p95 снизился 467,08 → 275,40 мс, на 41,04%. Оба p95 двух API, 267,10 и 283,71 мс, ниже обоих результатов четырёх API, 342,11 и 592,05 мс. Две реплики сохраняют возможность выдержать проверенный отказ одной API. Средние RPS выросли, но диапазоны перекрываются, поэтому устойчивое улучшение throughput не заявляется. Это экспериментальная конфигурация; обычный запуск по-прежнему даёт двум API по 512 МиБ.
Отдельная гипотеза уменьшить SQL-пул 8 → 1 проверена в порядке ABBA при одной API и неизменных 2 CPU/2048 МиБ. Она не подтвердилась: средний p95 175,24 → 187,42 мс и RPS 117,10 → 113,17. Настройка pool=1 не объявляется улучшением и не становится default. Отрицательный результат сохранён вместе с остальными данными.
### Rollout под нагрузкой
При двух API Deployment заменил обе исходные реплики под непрерывной 30-секундной нагрузкой, concurrency 8, maxSurge=1/maxUnavailable=0. После появления новых UID и завершения старых подов генератор ещё работал, а количество сообщений выросло 39 → 2028. Идентификаторы и счётчики находятся в replacements.json.
За весь прогон получено 2725 успешных запросов, 0 HTTP-ошибок, 90,61 RPS; p50/p95/p99 равны 58,55/219,17/566,77 мс. Проверена замена подов одного образа, не upgrade с несовместимой миграцией. Нулевые ошибки в этом опыте не являются общим обещанием zero downtime.
Первый незавершённый запуск был отвергнут из-за многострочного json_agg при разборе метрик. Вывод исправлен приведением к jsonb::text; таблица и графики используют только полностью завершённый run-R4F28Q. Диагностический RED сохранён отдельно в research-json-red.json.
## Ограничения
Это один Docker-host и один k3s server. Отказ API-процесса проверен, отказ host, PostgreSQL или единственного входа не покрыт HA. Local-path PVC переживает проверяемый restart, но не заменяет удалённый backup и репликацию. Closed-loop генератор имеет coordinated omission; latency относится к успешным запросам, ошибки считаются отдельно. Переходные ошибки фиксируются, обещания zero downtime нет.