docs: record verified failover and rolling replacement evidence
This commit is contained in:
@@ -1,37 +1,96 @@
|
||||
# Отчёт — лабораторная 3
|
||||
# ЛР 3 — балансировка и отказ API-реплики
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
Автор: **Маслов, БВТ2301**. Цель: **5, трек 1 — цена масштабирования**.
|
||||
Площадка сдачи: Gitea, личная ветка `solution/bvt2301-maslov`.
|
||||
|
||||
## Запуск из чистого clone
|
||||
## Запуск
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
Нужны Docker с Compose v2+ и Python 3.14 с uv; публичные преподавательские проверки работают также на Python 3.9+. Все команды выполняются в корне этого репозитория; соседние лабораторные не нужны.
|
||||
|
||||
## Архитектура и решения
|
||||
```sh
|
||||
uv sync --locked
|
||||
make bootstrap
|
||||
VCS_REF=$(git rev-parse HEAD) docker compose up -d --build --wait
|
||||
make check validate PYTHON=.venv/bin/python
|
||||
NO_PROXY=localhost,127.0.0.1 make test BASE_URL=http://127.0.0.1:8083
|
||||
make test-student BASE_URL=http://127.0.0.1:8083
|
||||
make verify
|
||||
```
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
Bootstrap создаёт независимые случайные credentials в `secrets/` и `.env`, существующие файлы сохраняет. Каталог secrets имеет права 0700; файлы читаются непривилегированным UID10001 через read-only mounts. Секреты не находятся в Git или образе. Начальная база создаётся образом PostgreSQL; отдельный одноразовый `migrate` применяет SQL под advisory lock. API стартуют после успешной миграции. Изменённая применённая миграция отклоняется по SHA-256.
|
||||
|
||||
## Доказательства критериев
|
||||
Основной адрес — `http://127.0.0.1:8083`. Порт можно изменить через `PUBLIC_PORT`; API и хранилища host ports не публикуют. В `.env.example` `API_REPLICAS` задаёт Compose scale, `API_CPUS` и `API_MEMORY` — квоты каждой API, `DB_POOL_SIZE` — максимум соединений каждого процесса. `SESSION_STORE=postgres` описывает выбранную архитектуру; переключателя на локальные сессии нет. Срок идемпотентности фиксирован контрактом в 86400 секунд, его уменьшение конфигурацией не поддерживается. `APP_ENV` — поясняющее поле skeleton, код его не использует.
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
```sh
|
||||
# Одна выбранная реплика остаётся остановленной:
|
||||
NO_PROXY=localhost,127.0.0.1 make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8083
|
||||
# Явно вернуть требуемое число реплик:
|
||||
docker compose up -d --no-build --wait
|
||||
# Перезапуск API, PostgreSQL, Valkey и LB с сохранением volumes:
|
||||
NO_PROXY=localhost,127.0.0.1 make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8083
|
||||
# Поочерёдно заменить все API, добавляя готовую реплику перед остановкой старой:
|
||||
make rolling-update
|
||||
# Безопасная остановка с сохранением данных:
|
||||
docker compose stop
|
||||
# Удалить контейнеры и сеть, сохранив данные:
|
||||
make down
|
||||
# Только намеренный сброс учебных данных ЭТОГО проекта:
|
||||
docker compose down --volumes
|
||||
```
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
Тесты создают синтетических пользователей и сообщения. Нагрузочные и аварийные сценарии запускаются явно. Для нового измерения выбирать новое имя output, сохраняя предыдущие результаты.
|
||||
|
||||
## Эксперименты и отказы
|
||||
## Архитектура
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
```mermaid
|
||||
flowchart LR
|
||||
C[Клиент] --> LB[HAProxy]
|
||||
LB --> A[API процесс 1]
|
||||
LB --> B[API процесс 2]
|
||||
A --> PG[(PostgreSQL)]
|
||||
B --> PG
|
||||
A --> V[(Valkey: disposable User cache)]
|
||||
B --> V
|
||||
```
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
Перенесена собственная реализация ЛР2: строгая валидация UTF-8 JSON и типов, ACL, keyset pagination `(created_at,id)`, Argon2id, случайные Bearer-сессии с абсолютным expiry, PostgreSQL и ограниченный по времени Valkey-кэш карточек User. Преподавательские README, COURSE, contracts и tests сохранены. Пароль не сохраняется открытым; для сессии хранится SHA-256 случайного 256-битного токена. Каждый защищённый запрос сначала проверяет действительность сессии в PostgreSQL. Кэш не может восстановить отозванную сессию или разрешить доступ при отказе БД.
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
Новые части: `X-Instance-Id` — UUID alias, генерируемый один раз внутри процесса API; HAProxy его не подменяет. Round robin применяется без sticky sessions. Одна сессия обслуживается любым процессом. Порты API доступны только внутри сети Compose; `container_name` не используется. Один uvicorn worker на контейнер, масштабирование — числом контейнеров.
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
HAProxy 3.2.1 закреплён digest, использует Docker DNS 127.0.0.11 и server-template до 8 адресов. DNS hold valid/obsolete/nx — 1 с. HTTP readiness проверяет PostgreSQL каждые 1 с, fall2/rise1, fastinter250ms. Номинальный бюджет исключения отказавшего адреса — около 2 с плюс длительность зависшей readiness; connect timeout1с, HTTP server timeout8с. PostgreSQL-клиент имеет checkout deadline4с, pool wait1с, connect2с, statement2.5с и lock1с. Поэтому в реальном отказе возможны короткие ошибки; время подтверждается экспериментом. HAProxy не повторяет POST автоматически (`retries 0`).
|
||||
|
||||
`/health/live` проверяет процесс; `/health/ready` — доступность обязательного синхронного PG-пути. Valkey необязателен для корректности и при runtime-отказе обходится с circuit backoff. Uvicorn завершает принятые запросы с бюджетом5с; контейнеру выделено10с. До импорта uvicorn действует ранний обработчик SIGTERM. Поочерёдная замена сначала добавляет готовую реплику, ждёт проверки и DNS, затем отправляет SIGTERM одной старой. Это проверка замены процессов одной версии; совместимость разных версий приложения отдельно не заявляется. Миграция002 — только расширение схемы, старый код ЛР2 не теряет свои таблицы.
|
||||
|
||||
Ресурсы обычного стенда: API2×0.5CPU/384MiB, PostgreSQL1CPU/512MiB, Valkey0.25CPU/128MiB, LB0.5CPU/128MiB. API работают под UID10001, root filesystem read-only, tmpfs16MiB, capabilities удалены. Python3.14.7 и uv0.13.7 закреплены digest; зависимости — `uv.lock`.
|
||||
|
||||
## Атомарность повторной отправки
|
||||
|
||||
1. API проверяет Bearer и членство в чате, затем валидирует body и ASCII ключ `[A-Za-z0-9._:-]{1,128}`.
|
||||
2. Область — пользователь, POST, нормализованный UUID чата и ключ. Другие чаты и пользователи независимы. В ЛР3 body содержит только text; схема вложений появляется в ЛР4.
|
||||
3. В одной PG-транзакции берётся `pg_advisory_xact_lock` по первым64битам SHA-256 области. Коллизия lock лишь дополнительно сериализует независимые запросы: окончательное сравнение выполняется по полному составному PK.
|
||||
4. Если результат моложе24ч, сравнивается SHA-256 канонического JSON. Другой text даёт409; тот же —201 с прежним Message, включая id и created_at. Порядок JSON-полей не влияет на hash.
|
||||
5. Для нового/истёкшего ключа в той же транзакции вставляется Message и результат идемпотентности с expiry по clock_timestamp PostgreSQL. COMMIT подтверждает оба изменения; исключение откатывает оба.
|
||||
|
||||
При неизвестном исходе POST клиент сохраняет исходные key/body и повторяет их. Повтор заново проверяет сессию/ACL. Ошибки5xx не сохраняются как успешный replay result. Записи истёкших ключей могут оставаться в таблице до обслуживания; expiry проверяется независимо от физического удаления. Контракт не обещает дедупликацию после24ч. Создание чата, регистрации и входа этим механизмом не защищены.
|
||||
|
||||
## Проверки и исследование
|
||||
|
||||
Проверки выполняются последовательно относительно изменений одного стенда. Первый собственный прогон был испорчен ошибочной пересборкой всех API/LB во время тестов: 503 и connection refused; этот прогон не засчитан. Повтор на готовом стенде: **87passed, 279.66с**; детали в `evidence/http-tests.json`.
|
||||
|
||||
Результаты аварийных сценариев, матрицы масштабирования и чистого clone добавляются после их выполнения. Для уровня5 предусмотрены фиксированная суммарная квота API1CPU/1024MiB и серия с ростом ресурсов0.5CPU/256MiB на реплику; 1/2/4 процесса, C1/8/32, два повтора,2с прогрева и6с измерения. Смешанный closed-loop профиль:80% чтений истории limit20 и20% отправок с уникальными ключами. Перед каждой ячейкой в отдельном исследовательском проекте очищается только его новая БД и создаётся100 сообщений. Отдельно сравнивается пул1/10 при N2/C32 в трёх чередующихся повторах. Пока измерений нет, выигрыш не заявляется.
|
||||
|
||||
## Вопросы защиты
|
||||
|
||||
**Чем отказ процесса отличается от отказа узла?** Остановка одной API оставляет другие процессы, LB и общую БД живыми. Потеря этого Docker-host одновременно лишает нас всех контейнеров и локальных volumes. Этот стенд проверяет отказ процесса, многосерверной HA здесь нет.
|
||||
|
||||
**Почему depends_on/healthcheck не являются балансировщиком?** depends_on определяет порядок запуска и начальную готовность. Healthcheck помечает состояние контейнера. Маршрутизацию клиентских запросов, исключение backend и DNS выполняет отдельный HAProxy. Его конфигурация нужна и после старта.
|
||||
|
||||
**Какие POST повторять после timeout и что защищает ключ?** POST сообщения можно повторить с теми же key/body в пределах24ч: запись Message и результата общая и атомарная. Ключ не повторяет данные на клиенте и не защищает другой endpoint; registration/chat/login при неизвестном результате требуют отдельного решения. Timeout не означает гарантированный rollback.
|
||||
|
||||
**Что сломается при локальных сессиях?** После round robin другая API не узнает токен, появятся случайные401; остановка владельца лишит сессии доступа. Sticky session скрыла бы часть ошибок до первого отказа. Общая PG-сессия сохраняет identity и абсолютный expiry через любую API и restart.
|
||||
|
||||
## Границы и источники
|
||||
|
||||
Один LB, PostgreSQL, Valkey и Docker-host; потеря БД/host не маскируется ростом API. TLS, репликация PostgreSQL, backup/PITR и промышленное наблюдение здесь не добавлены. HTTP доступен только на loopback, данные синтетические. Closed-loop имеет coordinated omission; короткий локальный прогон не задаёт production SLA. Пул — на процесс: рост реплик увеличивает возможное суммарное число PG-соединений.
|
||||
|
||||
Источники: [HAProxy3.2 configuration](https://docs.haproxy.org/3.2/configuration.html), [PG18 explicit locks](https://www.postgresql.org/docs/18/explicit-locking.html), [Compose services](https://docs.docker.com/reference/compose-file/services/). Библиотеки перечислены в `pyproject.toml`, точные версии — `uv.lock`. Помощь ИИ использована при разборе требований, подготовке реализации и проверок; результаты подтверждаются сохранёнными запусками.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"date": "2026-11-15T16:16:15.978617+00:00",
|
||||
"source_commit": "b14fb9a162d8012e83699cd8facdab178587d04b",
|
||||
"runtime_image_revision": "df4eee9",
|
||||
"command": "BASE_URL=http://127.0.0.1:8083 .venv/bin/python -m pytest student-tests -q --tb=short",
|
||||
"result": "PASS",
|
||||
"output": "........................................................................ [ 82%]\n............... [100%]\n87 passed in 279.66s (0:04:39)",
|
||||
"prior_attempt": {
|
||||
"result": "INVALID_ENVIRONMENT",
|
||||
"passed": 27,
|
||||
"failed": 19,
|
||||
"errors": 41,
|
||||
"reason": "Test requests overlapped with a mistaken full Compose image recreation; LB/API were unavailable. Repeated after completion without concurrent mutations."
|
||||
}
|
||||
}
|
||||
@@ -95,6 +95,21 @@ async def load(base, token, chat, concurrency, duration):
|
||||
}
|
||||
|
||||
|
||||
def cpu_counters(env):
|
||||
ids = compose(env, "ps", "-q", "api").split()
|
||||
code = (
|
||||
"import json,pathlib; print(json.dumps({p: "
|
||||
"pathlib.Path('/sys/fs/cgroup/'+p).read_text() for p in "
|
||||
"['cpu.stat','memory.current','memory.peak']}))"
|
||||
)
|
||||
return {
|
||||
cid[:12]: json.loads(
|
||||
command(["docker", "exec", cid, "python", "-c", code], env)
|
||||
)
|
||||
for cid in ids
|
||||
}
|
||||
|
||||
|
||||
def sample(env, stop, output):
|
||||
while not stop.is_set():
|
||||
try:
|
||||
@@ -277,6 +292,7 @@ def main():
|
||||
)
|
||||
assert r.status_code == 201
|
||||
asyncio.run(load(base, token, chat, c, a.warmup))
|
||||
counters_before = cpu_counters(env)
|
||||
samples = []
|
||||
stop = threading.Event()
|
||||
thread = threading.Thread(target=sample, args=(env, stop, samples))
|
||||
@@ -286,6 +302,7 @@ def main():
|
||||
finally:
|
||||
stop.set()
|
||||
thread.join()
|
||||
counters_after = cpu_counters(env)
|
||||
ids = compose(env, "ps", "-q").split()
|
||||
inspect = json.loads(command(["docker", "inspect", *ids], env))
|
||||
result.update(
|
||||
@@ -298,6 +315,8 @@ def main():
|
||||
api_memory_mib_each=memory,
|
||||
dataset_initial_messages=100,
|
||||
samples=samples,
|
||||
cgroup_before=counters_before,
|
||||
cgroup_after=counters_after,
|
||||
actual_limits=[
|
||||
{
|
||||
"role": x["Config"]["Labels"][
|
||||
|
||||
Reference in New Issue
Block a user