Run two API replicas behind HAProxy with verified failover
This commit is contained in:
@@ -1,4 +1,6 @@
|
||||
.git
|
||||
docs/plans
|
||||
LAB_NOTES.md
|
||||
.github
|
||||
.env
|
||||
.env.*
|
||||
|
||||
+1
-11
@@ -1,13 +1,3 @@
|
||||
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
|
||||
# These are logical interface suggestions; map actual framework names in REPORT.md.
|
||||
APP_HOST=0.0.0.0
|
||||
# Copy to .env; create secrets/postgres_password and secrets/database_url locally.
|
||||
APP_PORT=8080
|
||||
APP_ENV=lab
|
||||
SESSION_TTL_SECONDS=3600
|
||||
# Choose credentials locally. File paths contain no secret values.
|
||||
DATABASE_URL_FILE=/run/secrets/database_url
|
||||
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
|
||||
SESSION_STORE=postgres
|
||||
CACHE_URL_FILE=/run/secrets/cache_url
|
||||
API_REPLICAS=2
|
||||
IDEMPOTENCY_TTL_SECONDS=86400
|
||||
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
FROM python:3.12.12-slim-bookworm
|
||||
|
||||
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
|
||||
WORKDIR /app
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir -r requirements.txt && useradd --system --uid 10001 --home /app app
|
||||
COPY --chown=app:app src/ src/
|
||||
COPY --chown=app:app migrations/ migrations/
|
||||
COPY --chown=app:app scripts/migrate.py scripts/migrate.py
|
||||
USER app
|
||||
EXPOSE 8080
|
||||
CMD ["python", "-m", "src.server"]
|
||||
@@ -1,37 +1,57 @@
|
||||
# Отчёт — лабораторная 3
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор: Самохвалов Андрей Ремович, БПИ-2302.
|
||||
- Цель: оценка 5, трек 1 (цена масштабирования). Уровень 4 и исследование трека дополняются следующими блоками.
|
||||
- Ветка: `solution/bpi2302-samohvalov`; commit/PR после публикации.
|
||||
- Источники: `README.md`, `COURSE.md`, `contracts/`, публичные тесты репозитория, [HAProxy 3.0 configuration](https://docs.haproxy.org/3.0/configuration.html), [Docker Compose services](https://docs.docker.com/reference/compose-file/services/). Код и текст подготовлены с помощью Codex; результаты ниже получены реальным запуском.
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
Нужны Docker с Compose, Python 3.9+ и `make`. Dockerfile собирает исходники в `python:3.12.12-slim-bookworm`; БД — `postgres:17.6-bookworm`, балансировщик — `haproxy:3.0.11-alpine`. Python-пакеты закреплены в `requirements.txt`. Стенд рассчитан на localhost и синтетические данные.
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
mkdir -p secrets
|
||||
python3 - <<'PY'
|
||||
from pathlib import Path
|
||||
from secrets import token_urlsafe
|
||||
password = token_urlsafe(32)
|
||||
Path('secrets/postgres_password').write_text(password)
|
||||
Path('secrets/database_url').write_text(f'postgresql://messenger:{password}@postgres:5432/messenger')
|
||||
PY
|
||||
chmod 600 .env secrets/*
|
||||
docker compose --env-file .env config --quiet
|
||||
docker compose --env-file .env up -d --build --wait --scale api=2
|
||||
make check
|
||||
make test
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||||
docker compose --env-file .env up -d --wait --scale api=2 # восстановить остановленную реплику
|
||||
```
|
||||
|
||||
Для повторного failover после восстановления балансировщик должен обслуживать обе реплики; повторите команду и сверьте, какой контейнер остановлен. `docker compose --env-file .env ps -a` показывает реальный процесс. `migrate` — одноразовый сервис, который под advisory lock применяет SQL-миграции до запуска API; повторный `up` безопасно проверяет уже применённые версии. `docker compose --env-file .env down` сохраняет volume. Только для намеренного удаления учебных данных: `docker compose --env-file .env down -v`.
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
Клиент → HAProxy (`lb`, единственный опубликованный порт) → две FastAPI-реплики (`api`) → общий PostgreSQL (`postgres`). Сессии, сообщения и записи идемпотентности хранятся в PostgreSQL. Каждая реплика принимает любой действующий Bearer без sticky session. `X-Instance-Id` — случайный alias, постоянный в пределах процесса. Внешний порт PostgreSQL и API не опубликован.
|
||||
|
||||
## Доказательства критериев
|
||||
Балансировка round-robin использует `server-template` на четыре слота, Docker DNS `127.0.0.11`, повторное разрешение адресов и `/health/ready` раз в 1 секунду (`fall 2`, `rise 1`). Сбой backend обнаруживается примерно за 2 проверки; проверка через публичный endpoint важнее расчётного интервала. HAProxy имеет connect timeout 2 с и client/server timeout 15 с. Compose ждёт готовности БД и однократной миграции; API имеет 10-секундный `stop_grace_period`, Uvicorn получает SIGTERM как главный процесс контейнера. На API установлены ограничения 0.5 CPU/256 MiB на реплику, на LB — 0.5 CPU/128 MiB. Дополнительное исследование фиксированного суммарного бюджета выполняется позже.
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
Создание чата и членов атомарно. POST сообщения требует ключ `[A-Za-z0-9._:-]{1,128}`; PostgreSQL unique key `(user_id, chat_id, request_key)` резервируется в транзакции вместе с сообщением и ссылкой на результат. Конкурентный повтор ждёт исход первой транзакции. При одинаковом тексте возвращается тот же `201 Message`, при другом — `409`. Ключ другой пары пользователь/чат независим. Повтор проверяет Bearer и членство до чтения сохранённого результата. Записи старше 24 часов по тому же ключу удаляются перед новым запросом; массовая очистка исторических ключей пока не автоматизирована.
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
## Проверки уровня 3
|
||||
|
||||
## Эксперименты и отказы
|
||||
| Критерий | Команда/наблюдение | Результат |
|
||||
| --- | --- | --- |
|
||||
| Контракт | `make check`; локальный `make test BASE_URL=http://127.0.0.1:8083` через LB | PASS; публичный lab3 smoke |
|
||||
| Реальные реплики | 12 GET `/health/live` через LB, `docker compose ps -a` | Два разных `X-Instance-Id`, два healthy API-контейнера; только LB опубликован наружу |
|
||||
| Конкурентная идемпотентность | `python -m unittest discover -s student-tests` на временной PostgreSQL | 7 тестов PASS; два конкурентных вызова, одна запись `messages` |
|
||||
| Полный рестарт | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, прежние данные и токен; времена `StartedAt` обеих API, LB и PostgreSQL изменились |
|
||||
| Отказ API-1 | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; `docker compose ps -a` | PASS, 2 реплики до отказа, 112 записей, 1 переходная ошибка, первая успешная запись через 2.935 с; API-1 `Exited (0)` |
|
||||
| Отказ API-2 | Восстановить API-1, сдвинуть round-robin одним GET, повторить failover | PASS, 2 реплики до отказа, 110 записей, 1 переходная ошибка, первая успешная запись через 3.985 с; API-2 `Exited (0)` |
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
Сырые безопасные агрегаты и времена контейнеров: `evidence/failover-2026-10-02.txt`. После опытов обе реплики восстановлены. Проверки выполнялись на macOS/Colima arm64 с локальным портом 8083, поскольку 8080 занят стендом lab2. На чистом clone `.env.example` использует 8080. `make validate` локально не запускался: зависимость `openapi-spec-validator` недоступна из-за DNS к `files.pythonhosted.org`; обязательный контракт не менялся, штатный CI job `contracts.yml` выполняет validate.
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
## Ограничения и дальнейшие измерения
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
Стенд имеет один Docker-host, один LB и один PostgreSQL: отказ узла или БД не переживает. `depends_on` гарантирует порядок запуска, а маршрутизацию выполняет HAProxy. Проверка failover измеряет краткие ошибки и время восстановления, но не RPS до/после и не rolling update; это и исследование 1/2/4 реплик на фиксированном бюджете с повторениями будут добавлены для уровня 4/5. Текущий локальный HTTP разрешён только для изолированного стенда с синтетическими данными; удалённая демонстрация требует TLS.
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
name: mtusi2026lab3
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:17.6-bookworm
|
||||
environment:
|
||||
POSTGRES_DB: messenger
|
||||
POSTGRES_USER: messenger
|
||||
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
|
||||
secrets: [postgres_password]
|
||||
volumes: [postgres_data:/var/lib/postgresql/data]
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
|
||||
interval: 2s
|
||||
timeout: 2s
|
||||
retries: 20
|
||||
|
||||
migrate:
|
||||
build: .
|
||||
command: ["python", "scripts/migrate.py"]
|
||||
environment:
|
||||
DATABASE_URL_FILE: /run/secrets/database_url
|
||||
secrets: [database_url]
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
restart: "no"
|
||||
|
||||
api:
|
||||
build: .
|
||||
scale: 2
|
||||
environment:
|
||||
APP_HOST: 0.0.0.0
|
||||
APP_PORT: 8080
|
||||
DATABASE_URL_FILE: /run/secrets/database_url
|
||||
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
|
||||
secrets: [database_url]
|
||||
depends_on:
|
||||
migrate:
|
||||
condition: service_completed_successfully
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).close()"]
|
||||
interval: 2s
|
||||
timeout: 3s
|
||||
retries: 20
|
||||
start_period: 5s
|
||||
stop_grace_period: 10s
|
||||
cpus: 0.5
|
||||
mem_limit: 256m
|
||||
|
||||
lb:
|
||||
image: haproxy:3.0.11-alpine
|
||||
volumes:
|
||||
- ./infra/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
|
||||
ports:
|
||||
- "127.0.0.1:${APP_PORT:-8080}:8080"
|
||||
depends_on:
|
||||
api:
|
||||
condition: service_healthy
|
||||
cpus: 0.5
|
||||
mem_limit: 128m
|
||||
|
||||
secrets:
|
||||
postgres_password:
|
||||
file: ./secrets/postgres_password
|
||||
database_url:
|
||||
file: ./secrets/database_url
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
@@ -0,0 +1,40 @@
|
||||
Lab 3 local Compose evidence, 2026-10-02, macOS/Colima arm64.
|
||||
All public requests used HAProxy at http://127.0.0.1:8083; API and PostgreSQL
|
||||
had no published host ports. The local .env and secrets are ignored by Git.
|
||||
|
||||
docker compose --env-file .env config --quiet -> PASS
|
||||
docker compose --env-file .env up -d --build --wait --scale api=2 ->
|
||||
api-1 healthy, api-2 healthy, postgres healthy, migrate exited 0, lb running.
|
||||
make check -> PASS
|
||||
make test BASE_URL=http://127.0.0.1:8083 -> PASS: lab3 public API scenario.
|
||||
12 GET /health/live through LB observed two X-Instance-Id values.
|
||||
|
||||
Isolated PostgreSQL integration run before Compose:
|
||||
python -m unittest discover -s student-tests -v -> 7 tests, OK.
|
||||
Concurrent same-key requests returned identical Message; SQL count was 1.
|
||||
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8083
|
||||
API-1 stop: observed_instances_before=2, successful_writes=112,
|
||||
failed_attempts=1, first_recovery_seconds=2.935, PASS.
|
||||
docker compose ps -a: api-1 Exited (0), api-2 healthy, lb/postgres running.
|
||||
Restored api-1 using docker compose up -d --wait --scale api=2.
|
||||
A repeat selected api-1 again; it was not counted as the second-replica proof.
|
||||
Restored api-1, sent one GET to advance round-robin, and repeated:
|
||||
API-2 stop: observed_instances_before=2, successful_writes=110,
|
||||
failed_attempts=1, first_recovery_seconds=3.985, PASS.
|
||||
docker compose ps -a: api-2 Exited (0), api-1 healthy, lb/postgres running.
|
||||
Restored api-2; both replicas healthy.
|
||||
|
||||
Persistence hook proof, times UTC; named postgres_data volume preserved:
|
||||
before:
|
||||
api-1 2026-10-02T08:46:12.886332892Z
|
||||
api-2 2026-10-02T08:48:59.563753865Z
|
||||
lb 2026-10-02T08:42:41.675055235Z
|
||||
postgres 2026-10-02T08:42:32.879514014Z
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
-> PASS: confirmed data and existing session survived.
|
||||
after:
|
||||
api-1 2026-10-02T08:49:48.469504932Z
|
||||
api-2 2026-10-02T08:49:48.407940425Z
|
||||
lb 2026-10-02T08:49:54.047109297Z
|
||||
postgres 2026-10-02T08:49:45.282318374Z
|
||||
@@ -0,0 +1,26 @@
|
||||
global
|
||||
log stdout format raw local0
|
||||
|
||||
defaults
|
||||
mode http
|
||||
log global
|
||||
option httplog
|
||||
timeout connect 2s
|
||||
timeout client 15s
|
||||
timeout server 15s
|
||||
|
||||
resolvers docker
|
||||
nameserver docker 127.0.0.11:53
|
||||
resolve_retries 2
|
||||
timeout retry 1s
|
||||
hold valid 1s
|
||||
|
||||
frontend public
|
||||
bind *:8080
|
||||
default_backend api
|
||||
|
||||
backend api
|
||||
balance roundrobin
|
||||
option httpchk GET /health/ready
|
||||
http-check expect status 200
|
||||
server-template api 1-4 api:8080 check inter 1s fall 2 rise 1 resolvers docker init-addr none
|
||||
Executable
+5
@@ -0,0 +1,5 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
cd "$(dirname "$0")/.."
|
||||
docker compose --env-file .env stop api lb postgres
|
||||
docker compose --env-file .env up -d --wait --scale api=2
|
||||
Executable
+13
@@ -0,0 +1,13 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
cd "$(dirname "$0")/.."
|
||||
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
|
||||
for container in $(docker compose --env-file .env ps -q api); do
|
||||
instance=$(docker exec "$container" python -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8080/health/live', timeout=2).headers['X-Instance-Id'])")
|
||||
if [ "$instance" = "$TARGET_INSTANCE_ID" ]; then
|
||||
docker stop -t 5 "$container" >/dev/null
|
||||
exit 0
|
||||
fi
|
||||
done
|
||||
echo "target API instance not found" >&2
|
||||
exit 1
|
||||
Reference in New Issue
Block a user