Добавить балансировщик HAProxy, две реплики API и поочерёдную замену

This commit is contained in:
2026-10-30 21:43:16 +03:00
parent 91f1b3c06e
commit 18899b388d
17 changed files with 498 additions and 2 deletions
+16
View File
@@ -18,3 +18,19 @@ __pycache__
node_modules
evidence
.DS_Store
# в образ идут только requirements.txt, src/ и migrations/
tests
student-tests
contracts
examples
scripts
infra
*.md
Makefile
Dockerfile*
compose*.yaml
lab.json
requirements-dev.txt
.gitignore
.idea
.vscode
+14 -1
View File
@@ -7,7 +7,20 @@ 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
SESSION_STORE=redis
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
IDEMPOTENCY_TTL_SECONDS=86400
# info / debug / warning
LOG_LEVEL=info
# Сколько секунд после SIGTERM ждать незавершённые запросы (не больше 10).
SHUTDOWN_TIMEOUT=8
# Пул соединений с PostgreSQL и таймауты в секундах.
DB_POOL_MIN_SIZE=2
DB_POOL_MAX_SIZE=10
DB_POOL_TIMEOUT=3
DB_CONNECT_TIMEOUT=3
DB_STATEMENT_TIMEOUT=5
# Пул соединений с Redis и таймаут операций в секундах.
CACHE_POOL_MAX_SIZE=20
CACHE_TIMEOUT=2
+37
View File
@@ -0,0 +1,37 @@
FROM python:3.13.16-slim-bookworm
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1 \
PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /app
# сначала зависимости: слой переиспользуется, пока не меняется requirements.txt
COPY requirements.txt .
RUN pip install -r requirements.txt
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --no-create-home --shell /usr/sbin/nologin app
COPY src/ .
COPY migrations/ migrations/
USER 10001:10001
ARG APP_VERSION=dev
ENV APP_HOST=0.0.0.0 \
APP_PORT=8080 \
APP_ENV=lab \
APP_VERSION=$APP_VERSION
EXPOSE 8080
HEALTHCHECK --interval=5s --timeout=4s --start-period=20s --start-interval=1s --retries=3 \
CMD ["python", "healthcheck.py"]
STOPSIGNAL SIGTERM
# exec-форма: python запускается как PID 1 и сам получает SIGTERM
CMD ["python", "main.py"]
+45 -1
View File
@@ -2,9 +2,11 @@ PYTHON ?= python3
BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
COMPOSE = docker compose --env-file .env
COMPOSE_TEST = $(COMPOSE) -f compose.yaml -f compose.test.yaml
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
.PHONY: help check validate test load test-persistence test-failover
.PHONY: help check validate test load test-persistence test-failover env up down clean restore student-test test-failures explain failover-each failover-hard rolling-update
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@@ -28,3 +30,45 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
env:
./scripts/init-env.sh
up: env
$(COMPOSE) up -d --build
BASE_URL="$(BASE_URL)" ./scripts/wait-ready.sh
down:
$(COMPOSE_TEST) down
# удаляет контейнеры вместе с данными PostgreSQL и Redis
clean:
$(COMPOSE_TEST) down -v
# возвращает реплики, остановленные scripts/stop-one.sh
restore:
$(COMPOSE) up -d --no-recreate --no-build api
BASE_URL="$(BASE_URL)" ./scripts/wait-ready.sh
student-test:
BASE_URL="$(BASE_URL)" $(PYTHON) -m unittest discover -s student-tests -v
# останавливает и запускает redis/postgres, поднимает отдельный API на порту 8081
test-failures:
BASE_URL="$(BASE_URL)" $(PYTHON) -m unittest discover -s student-tests/failures -v
explain:
./scripts/explain_history.sh
# по очереди останавливает каждую реплику под нагрузкой
failover-each:
BASE_URL="$(BASE_URL)" $(PYTHON) scripts/chaos.py stop --output evidence/failover-each.json
# то же с SIGKILL и с зависшей репликой (docker pause)
failover-hard:
BASE_URL="$(BASE_URL)" $(PYTHON) scripts/chaos.py kill --output evidence/failover-kill.json
BASE_URL="$(BASE_URL)" $(PYTHON) scripts/chaos.py pause --output evidence/failover-pause.json
# заменяет реплики новым образом под нагрузкой: make rolling-update APP_VERSION=2
rolling-update:
BASE_URL="$(BASE_URL)" $(PYTHON) scripts/chaos.py rolling --output evidence/rolling-update.json
+14
View File
@@ -0,0 +1,14 @@
# Только для тестов срока жизни: отдельный API с короткими TTL, опубликованный на 8081.
# В основной стенд не входит, там API доступен только через балансировщик.
services:
api-short-ttl:
extends:
file: compose.yaml
service: api
environment:
SESSION_TTL_SECONDS: "2"
IDEMPOTENCY_TTL_SECONDS: "2"
ports:
- "127.0.0.1:8081:8080"
deploy:
replicas: 1
+171
View File
@@ -0,0 +1,171 @@
name: mtusi-messenger-lab3
# Настройки и секреты берутся из .env (создаёт scripts/init-env.sh, в Git не попадает).
# Секреты доходят до контейнеров только файлами в /run/secrets, в переменных окружения контейнеров их нет.
x-app: &app
build:
context: .
args:
APP_VERSION: ${APP_VERSION:-dev}
image: mtusi-messenger:lab3
x-app-env: &app-env
APP_HOST: 0.0.0.0
APP_PORT: "8080"
APP_ENV: ${APP_ENV:-lab}
LOG_LEVEL: ${LOG_LEVEL:-info}
SHUTDOWN_TIMEOUT: ${SHUTDOWN_TIMEOUT:-8}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
SESSION_STORE: ${SESSION_STORE:-redis}
IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400}
DATABASE_URL_FILE: /run/secrets/database_url
CACHE_URL_FILE: /run/secrets/cache_url
DB_POOL_MIN_SIZE: ${DB_POOL_MIN_SIZE:-2}
DB_POOL_MAX_SIZE: ${DB_POOL_MAX_SIZE:-10}
DB_POOL_TIMEOUT: ${DB_POOL_TIMEOUT:-3}
DB_CONNECT_TIMEOUT: ${DB_CONNECT_TIMEOUT:-3}
DB_STATEMENT_TIMEOUT: ${DB_STATEMENT_TIMEOUT:-5}
CACHE_POOL_MAX_SIZE: ${CACHE_POOL_MAX_SIZE:-20}
CACHE_TIMEOUT: ${CACHE_TIMEOUT:-2}
services:
lb:
build: infra/haproxy
image: mtusi-messenger-lb:lab3
# единственный опубликованный порт стенда
ports:
- "127.0.0.1:8080:8080"
networks:
- edge
depends_on:
api:
condition: service_started
healthcheck:
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8404/lb-health"]
interval: 5s
timeout: 3s
retries: 5
deploy:
resources:
limits:
cpus: "0.5"
memory: 128M
restart: unless-stopped
api:
<<: *app
environment: *app-env
secrets:
- database_url
- cache_url
networks:
- edge
- data
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy
# SIGTERM -> приём закрыт -> незавершённые запросы до SHUTDOWN_TIMEOUT -> выход раньше SIGKILL
stop_grace_period: 10s
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
cpus: "1.0"
memory: 256M
restart: unless-stopped
# миграции выполняет один контейнер до старта реплик, а не каждая реплика
migrate:
<<: *app
command: ["python", "migrate.py"]
environment:
DATABASE_URL_FILE: /run/secrets/database_url
secrets:
- database_url
networks:
- data
depends_on:
postgres:
condition: service_healthy
healthcheck:
disable: true
deploy:
resources:
limits:
cpus: "0.5"
memory: 128M
restart: "no"
postgres:
image: postgres:17.11-alpine
environment:
POSTGRES_USER: messenger
POSTGRES_DB: messenger
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets:
- postgres_password
networks:
- data
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"]
interval: 5s
timeout: 3s
retries: 10
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
restart: unless-stopped
redis:
image: redis:7.4.11-alpine
# сессии хранятся только здесь, поэтому включён AOF с fsync на каждую запись;
# запуск через docker-entrypoint.sh, чтобы процесс работал от пользователя redis, а не от root
command:
- sh
- -c
- exec docker-entrypoint.sh redis-server --appendonly yes --appendfsync always --requirepass "$$(cat /run/secrets/redis_password)"
secrets:
- redis_password
networks:
- data
volumes:
- redisdata:/data
healthcheck:
test: ["CMD-SHELL", "redis-cli --no-auth-warning -a \"$$(cat /run/secrets/redis_password)\" ping | grep -q PONG"]
interval: 5s
timeout: 3s
retries: 10
deploy:
resources:
limits:
cpus: "0.5"
memory: 128M
restart: unless-stopped
networks:
# балансировщик и реплики
edge:
# реплики и хранилища; балансировщик сюда не входит, выхода наружу нет
data:
internal: true
volumes:
pgdata:
redisdata:
secrets:
postgres_password:
environment: POSTGRES_PASSWORD
redis_password:
environment: REDIS_PASSWORD
database_url:
environment: DATABASE_URL
cache_url:
environment: CACHE_URL
+7
View File
@@ -0,0 +1,7 @@
FROM haproxy:3.2.26-alpine
# конфигурация внутри образа: версия балансировщика и его настройки меняются только сборкой
COPY haproxy.cfg /usr/local/etc/haproxy/haproxy.cfg
COPY errors/ /usr/local/etc/haproxy/errors/
RUN ["haproxy", "-c", "-f", "/usr/local/etc/haproxy/haproxy.cfg"]
+8
View File
@@ -0,0 +1,8 @@
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 119
Cache-Control: no-cache
Connection: close
X-Request-Id: lb-400
{"error": {"code": "invalid_request", "message": "Некорректный HTTP-запрос", "request_id": "lb-400"}}
+8
View File
@@ -0,0 +1,8 @@
HTTP/1.1 408 Request Timeout
Content-Type: application/json
Content-Length: 124
Cache-Control: no-cache
Connection: close
X-Request-Id: lb-408
{"error": {"code": "invalid_request", "message": "Запрос не получен вовремя", "request_id": "lb-408"}}
+8
View File
@@ -0,0 +1,8 @@
HTTP/1.1 414 URI Too Long
Content-Type: application/json
Content-Length: 132
Cache-Control: no-cache
Connection: close
X-Request-Id: lb-414
{"error": {"code": "invalid_request", "message": "Слишком длинный адрес запроса", "request_id": "lb-414"}}
+8
View File
@@ -0,0 +1,8 @@
HTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
Content-Length: 140
Cache-Control: no-cache
Connection: close
X-Request-Id: lb-431
{"error": {"code": "invalid_request", "message": "Слишком большие заголовки запроса", "request_id": "lb-431"}}
+68
View File
@@ -0,0 +1,68 @@
global
log stdout format raw local0 info
maxconn 2000
defaults
mode http
log global
# в лог не попадают query string и заголовки: только путь, код, тайминги и выбранный сервер
log-format "%ci %HM %HPO status=%ST server=%s retries=%rc Tq=%TR Tw=%Tw Tc=%Tc Tr=%Tr Ta=%Ta"
# новое соединение с API на каждый запрос: остановленная реплика сразу видна как отказ соединения,
# а такой запрос до приложения не дошёл, поэтому его безопасно отправить на другую
option http-server-close
retries 2
retry-on conn-failure
option redispatch 1
timeout connect 1s
timeout http-request 10s
timeout queue 3s
# больше любого ответа API: 3 с на соединение из пула + 5 с на запрос + 2 с на Redis
timeout server 12s
timeout client 30s
timeout http-keep-alive 30s
timeout check 1s
# запрос, который не удалось разобрать: своего id у него ещё нет, поэтому ответы готовые, в формате контракта
errorfile 400 /usr/local/etc/haproxy/errors/400.http
errorfile 408 /usr/local/etc/haproxy/errors/408.http
errorfile 414 /usr/local/etc/haproxy/errors/414.http
errorfile 431 /usr/local/etc/haproxy/errors/431.http
resolvers docker
nameserver dns 127.0.0.11:53
accepted_payload_size 8192
# DNS Docker убирает остановленные контейнеры и добавляет новые, список реплик обновляется сам
timeout resolve 1s
timeout retry 1s
hold valid 2s
hold obsolete 0s
hold nx 2s
frontend api_in
bind *:8080
unique-id-format %[uuid(4)]
default_backend api
# ответы самого балансировщика в формате ошибок контракта
http-error status 500 content-type application/json lf-string '{"error":{"code":"internal_error","message":"Внутренняя ошибка сервера","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"Сервис временно недоступен","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"Сервис временно недоступен","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
http-error status 504 content-type application/json lf-string '{"error":{"code":"unavailable","message":"Сервис временно недоступен","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
backend api
balance roundrobin
# без sticky session: любой запрос может уйти на любую реплику
option httpchk GET /health/ready
http-check expect status 200
# проверка раз в секунду, две неудачи подряд исключают реплику, две удачи возвращают
default-server check inter 1s fall 2 rise 2 resolvers docker resolve-prefer ipv4 init-addr none
# до 6 реплик; адреса приходят из DNS по имени сервиса
server-template api 1-6 api:8080
# только внутри контейнера lb, порт не опубликован
frontend internal
bind *:8404
monitor-uri /lb-health
stats enable
stats uri /stats
stats refresh 0
no log
+25
View File
@@ -0,0 +1,25 @@
#!/bin/sh
# Создаёт .env из .env.example и дописывает в него случайные пароли. Файл .env исключён из Git.
set -eu
cd "$(dirname "$0")/.."
[ -f .env ] || cp .env.example .env
if grep -q '^POSTGRES_PASSWORD=' .env; then
# пароль PostgreSQL задаётся один раз при создании volume, новый пароль к старым данным не подойдёт
echo ".env уже содержит пароли, ничего не меняю"
exit 0
fi
postgres_password=$(openssl rand -hex 24)
redis_password=$(openssl rand -hex 24)
cat >> .env <<END
# Локальные секреты, созданы scripts/init-env.sh. Compose кладёт их в контейнеры файлами /run/secrets/*.
POSTGRES_PASSWORD=$postgres_password
REDIS_PASSWORD=$redis_password
DATABASE_URL=postgresql://messenger:$postgres_password@postgres:5432/messenger
CACHE_URL=redis://:$redis_password@redis:6379/0
END
chmod 600 .env
echo "пароли записаны в .env"
+5
View File
@@ -0,0 +1,5 @@
#!/bin/sh
# Перезапускает балансировщик, все реплики API и оба хранилища. Volumes не трогает.
set -eu
cd "$(dirname "$0")/.."
docker compose --env-file .env restart postgres redis api lb
+38
View File
@@ -0,0 +1,38 @@
#!/bin/sh
# Поочерёдно заменяет реплики API новым образом: сначала новая готова, потом старая останавливается.
# Миграции выполняются один раз до замены, поэтому они должны быть совместимы с работающей версией.
set -eu
cd "$(dirname "$0")/.."
compose="docker compose --env-file .env"
$compose build api
$compose run --rm migrate
old=$($compose ps -q api)
count=$(echo "$old" | wc -l | tr -d ' ')
wait_healthy() {
for attempt in $(seq 1 60); do
unhealthy=0
# переменная цикла отдельная: в sh нет локальных переменных, а $container нужен внешнему циклу
for replica in $($compose ps -q api); do
[ "$(docker inspect -f '{{.State.Health.Status}}' "$replica")" = healthy ] || unhealthy=1
done
if [ "$unhealthy" = 0 ]; then
return 0
fi
sleep 1
done
echo "новая реплика не стала healthy за 60 секунд, замена остановлена" >&2
exit 1
}
for container in $old; do
$compose up -d --no-deps --no-recreate --no-build --scale api=$((count + 1)) api
wait_healthy
# балансировщику нужно две удачные проверки с периодом 1 с, с запасом
sleep 3
docker stop "$container"
docker rm "$container"
done
echo "замена завершена, реплик: $($compose ps -q api | wc -l | tr -d ' ')"
+14
View File
@@ -0,0 +1,14 @@
#!/bin/sh
# Останавливает реплику API, которая обслужила тест, и оставляет её остановленной.
# Вернуть реплику: make restore
set -eu
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
cd "$(dirname "$0")/.."
# X-Instance-Id равен короткому id контейнера; ищем только среди контейнеров сервиса api этого стенда
container=$(docker compose --env-file .env ps -q api | grep "^$TARGET_INSTANCE_ID" || true)
if [ -z "$container" ]; then
echo "реплика $TARGET_INSTANCE_ID не найдена среди контейнеров сервиса api" >&2
exit 3
fi
docker stop "$container"
+12
View File
@@ -0,0 +1,12 @@
#!/bin/sh
# Ждёт, пока /health/ready ответит 200, не дольше 60 секунд.
BASE_URL=${BASE_URL:-http://localhost:8080}
for attempt in $(seq 1 60); do
if curl -fs -o /dev/null "$BASE_URL/health/ready"; then
echo "готов: $BASE_URL"
exit 0
fi
sleep 1
done
echo "стенд не стал готов за 60 секунд: $BASE_URL" >&2
exit 1