11.3. Healthchecks и readiness

detection time = interval × failureThreshold + timeout

t=0     база отказала
t=15    все три реплики получили unhealthy
t=15    все три перезапускаются одновременно
t=15..45  трафик не обслуживается никем
t=45    реплики поднялись, начали переподключение к базе
t=45    база (восстанавливающаяся) получает лавину подключений
t=60    liveness снова падает — база не справилась
        цикл повторяется

@app.get("/readyz")
async def readyz(response: Response):
    checks = {}
    critical_ok = True

    checks["db"] = await check_db()
    if checks["db"] != "ok":
        critical_ok = False          # без базы работать нельзя

    checks["cache"] = await check_cache()
    # кэш необязателен: отмечаем, но готовность не теряем

    if not critical_ok:
        response.status_code = 503
    return {"status": "ready" if critical_ok else "degraded", "checks": checks}

ПЛОХО:
  SIGTERM ──► сервер сразу перестаёт принимать ──► клиенты получают отказ
              (балансировщик ещё не знает, что мы уходим)

ХОРОШО:
  t=0    SIGTERM
  t=0    readiness начинает отвечать 503 ← мы говорим «не шлите сюда»
  t=0..D приложение ПРОДОЛЖАЕТ принимать запросы ← балансировщик ещё шлёт
  t=D    балансировщик убрал нас из пула
  t=D    перестаём принимать новые соединения
  t=D..  дозавершаем текущие запросы
  t=D+R  закрываем ресурсы, выходим с кодом 0

stop_grace_period > D + R + запас
                    │   └── максимальная длительность запроса
                    └────── interval × failureThreshold readiness-пробы

healthcheck:
  disable: true

mkdir -p /tmp/probes && cd /tmp/probes

cat > app.py <<'PY'
"""Сервис, который можно сломать по требованию."""
import json
import os
import signal
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

_healthy = True
_ready = True
_server = None
_draining = False
DRAIN = float(os.environ.get("DRAIN_SECONDS", "0"))


class H(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/healthz":
            self._json(200 if _healthy else 503, {"alive": _healthy})
        elif self.path == "/readyz":
            ok = _ready and not _draining
            self._json(200 if ok else 503,
                       {"ready": ok, "draining": _draining})
        elif self.path == "/break":
            globals()["_healthy"] = False
            self._json(200, {"broken": True})
        else:
            self._json(200, {"pid": os.getpid(), "ts": time.time()})

    def _json(self, code, payload):
        body = json.dumps(payload).encode()
        self.send_response(code)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *a):
        pass


def on_term(signum, _frame):
    """Слив трафика: сначала перестаём быть ready, потом закрываемся."""
    global _draining
    print(f"[{time.time():.1f}] SIGTERM: начинаю слив, readiness → 503", flush=True)
    _draining = True

    def finish():
        if DRAIN:
            time.sleep(DRAIN)
            print(f"[{time.time():.1f}] слив завершён, закрываю приём", flush=True)
        _server.shutdown()

    threading.Thread(target=finish, daemon=True).start()


if __name__ == "__main__":
    signal.signal(signal.SIGTERM, on_term)
    _server = HTTPServer(("0.0.0.0", 8000), H)
    print(f"[{time.time():.1f}] запущен, DRAIN={DRAIN}", flush=True)
    _server.serve_forever()
    print(f"[{time.time():.1f}] остановлен штатно", flush=True)
    sys.exit(0)
PY

cat > compose.yaml <<'EOF'
name: probes

x-base: &base
  image: python:3.13-slim
  volumes:
    - ./app.py:/app.py:ro
  command: ["python", "-u", "/app.py"]

services:
  # Умолчания Docker: interval 30s, retries 3, timeout 30s
  defaults:
    <<: *base
    ports:
      - "127.0.0.1:8601:8000"
    healthcheck:
      test: ["CMD", "python", "-c",
             "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=2).status==200 else 1)"]

  # Настроенные значения
  tuned:
    <<: *base
    ports:
      - "127.0.0.1:8602:8000"
    healthcheck:
      test: ["CMD", "python", "-c",
             "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=2).status==200 else 1)"]
      interval: 5s
      timeout: 2s
      retries: 3
      start_period: 10s
      start_interval: 1s
EOF

docker compose up -d > /dev/null 2>&1
for _ in $(seq 60); do
    [ "$(docker compose ps --format '{{.Health}}' tuned)" = "healthy" ] && break
    sleep 1
done
sleep 2

echo "═══ параметры проб ═══"
for svc in defaults tuned; do
    docker inspect "$(docker compose ps -q $svc)" --format \
        "  $svc: interval={{.Config.Healthcheck.Interval}} timeout={{.Config.Healthcheck.Timeout}} retries={{.Config.Healthcheck.Retries}}" \
        | sed 's/000000000ns/s/g; s/0000000ns/00ms/g'
done

echo "═══ ломаем оба и засекаем время до unhealthy ═══"
for svc in defaults tuned; do
    port=$([ "$svc" = "defaults" ] && echo 8601 || echo 8602)
    curl -s -m 3 "http://127.0.0.1:$port/break" > /dev/null
done
start="$(date +%s)"
detected_d=0; detected_t=0
for i in $(seq 140); do
    [ "$detected_d" -eq 0 ] && [ "$(docker compose ps --format '{{.Health}}' defaults)" = "unhealthy" ] \
        && detected_d=$(( $(date +%s) - start ))
    [ "$detected_t" -eq 0 ] && [ "$(docker compose ps --format '{{.Health}}' tuned)" = "unhealthy" ] \
        && detected_t=$(( $(date +%s) - start ))
    [ "$detected_d" -ne 0 ] && [ "$detected_t" -ne 0 ] && break
    sleep 1
done
printf '  defaults: обнаружено через %s с\n' "${detected_d:-не обнаружено}"
printf '  tuned:    обнаружено через %s с\n' "${detected_t:-не обнаружено}"

═══ параметры проб ═══
  defaults: interval=30s timeout=30s retries=3
  tuned: interval=5s timeout=2s retries=3
═══ ломаем оба и засекаем время до unhealthy ═══
  defaults: обнаружено через 92 с
  tuned:    обнаружено через 16 с

cd /tmp/probes
echo "═══ статус после обнаружения ═══"
for svc in defaults tuned; do
    cid="$(docker compose ps -q $svc)"
    printf '  %-9s health=%-10s status=%-8s перезапусков=%s\n' \
        "$svc" \
        "$(docker inspect "$cid" --format '{{.State.Health.Status}}')" \
        "$(docker inspect "$cid" --format '{{.State.Status}}')" \
        "$(docker inspect "$cid" --format '{{.RestartCount}}')"
done

echo "═══ события Docker ═══"
timeout 3 docker events --since 3m --filter event=health_status --format '  {{.Actor.Attributes.name}}: {{.Status}}' 2>/dev/null | head -4 || true

═══ статус после обнаружения ═══
  defaults  health=unhealthy  status=running  перезапусков=0
  tuned     health=unhealthy  status=running  перезапусков=0
═══ события Docker ═══
  probes-tuned-1: health_status: unhealthy
  probes-defaults-1: health_status: unhealthy

cd /tmp/probes && docker compose down > /dev/null 2>&1

cd /tmp/probes
cat > compose.drain.yaml <<'EOF'
name: drain

x-base: &base
  image: python:3.13-slim
  volumes:
    - ./app.py:/app.py:ro
  command: ["python", "-u", "/app.py"]

services:
  # Без слива: закрывается сразу по SIGTERM
  naive:
    <<: *base
    environment:
      DRAIN_SECONDS: "0"
    ports:
      - "127.0.0.1:8611:8000"
    stop_grace_period: 30s

  # Со сливом: 8 секунд обслуживает, будучи не-ready
  draining:
    <<: *base
    environment:
      DRAIN_SECONDS: "8"
    ports:
      - "127.0.0.1:8612:8000"
    stop_grace_period: 30s
EOF

docker compose -f compose.drain.yaml up -d > /dev/null 2>&1
sleep 5

load() {   # load <порт> <секунд> — считает успешные и неудачные запросы
    local port="$1" dur="$2" ok=0 err=0 deadline
    deadline=$(( $(date +%s) + dur ))
    while [ "$(date +%s)" -lt "$deadline" ]; do
        if curl -s -m 2 -o /dev/null "http://127.0.0.1:$port/" 2>/dev/null; then
            ok=$((ok + 1))
        else
            err=$((err + 1))
        fi
        sleep 0.05
    done
    echo "$ok $err"
}

for svc in naive draining; do
    port=$([ "$svc" = "naive" ] && echo 8611 || echo 8612)
    echo "═══ $svc ═══"
    # Нагрузка идёт всё время остановки
    load "$port" 14 > /tmp/probes/load-$svc.txt &
    load_pid=$!
    sleep 3
    printf '  readiness до остановки: %s\n' \
        "$(curl -s -m 2 -o /dev/null -w '%{http_code}' "http://127.0.0.1:$port/readyz")"
    docker compose -f compose.drain.yaml stop "$svc" > /dev/null 2>&1 &
    stop_pid=$!
    sleep 2
    printf '  readiness во время слива: %s\n' \
        "$(curl -s -m 2 -o /dev/null -w '%{http_code}' "http://127.0.0.1:$port/readyz" 2>/dev/null || echo 'нет ответа')"
    wait $stop_pid 2>/dev/null
    wait $load_pid 2>/dev/null
    read -r ok err < /tmp/probes/load-$svc.txt
    printf '  запросов: успешных=%s неудачных=%s\n' "$ok" "$err"
    docker compose -f compose.drain.yaml logs "$svc" --no-log-prefix 2>/dev/null | tail -3 | sed 's/^/  /'
done

docker compose -f compose.drain.yaml down > /dev/null 2>&1

═══ naive ═══
  readiness до остановки: 200
  readiness во время слива: нет ответа
  запросов: успешных=54 неудачных=141
  [1785412901.4] SIGTERM: начинаю слив, readiness → 503
  [1785412901.4] остановлен штатно
═══ draining ═══
  readiness до остановки: 200
  readiness во время слива: 503
  запросов: успешных=196 неудачных=0
  [1785412918.2] SIGTERM: начинаю слив, readiness → 503
  [1785412926.2] слив завершён, закрываю приём
  [1785412926.2] остановлен штатно

cd /tmp/probes
cat > grace-calc.py <<'PY'
"""Расчёт stop_grace_period из параметров балансировщика и приложения."""
from __future__ import annotations


def compute(interval: float, failures: int, max_request: float,
            margin: float = 5.0) -> dict[str, float]:
    """
    interval    — период readiness-пробы балансировщика
    failures    — сколько неудач подряд до исключения из пула
    max_request — длительность самого долгого запроса
    margin      — запас
    """
    detection = interval * failures
    total = detection + max_request + margin
    return {
        "обнаружение балансировщиком": detection,
        "дозавершение запросов": max_request,
        "запас": margin,
        "stop_grace_period": total,
    }


SCENARIOS = [
    ("веб-API, короткие запросы", 5, 3, 2),
    ("веб-API, отчёты до 30 с", 5, 3, 30),
    ("worker очереди, задача до 60 с", 0, 0, 60),
    ("умолчания Docker (interval 30s)", 30, 3, 2),
]

print(f"{'сценарий':<34} {'обнаруж.':>9} {'запрос':>8} {'grace':>8}")
print("─" * 62)
for name, interval, failures, req in SCENARIOS:
    r = compute(interval, failures, req)
    print(f"{name:<34} {r['обнаружение балансировщиком']:>8.0f}с "
          f"{r['дозавершение запросов']:>7.0f}с {r['stop_grace_period']:>7.0f}с")

print()
print("Умолчание Docker: 10 с")
print("Оно достаточно только для сценария с короткими запросами")
print("и быстрой пробой — и то без запаса.")
PY

python3 grace-calc.py

сценарий                            обнаруж.   запрос    grace
──────────────────────────────────────────────────────────────
веб-API, короткие запросы                15с       2с      22с
веб-API, отчёты до 30 с                  15с      30с      50с
worker очереди, задача до 60 с            0с      60с      65с
умолчания Docker (interval 30s)          90с       2с      97с

Умолчание Docker: 10 с
Оно достаточно только для сценария с короткими запросами
и быстрой пробой — и то без запаса.

cd /tmp/probes
cat > cascade.py <<'PY'
"""Что происходит при liveness, зависящей от общей базы."""
from __future__ import annotations

REPLICAS = 3
DETECTION = 15          # секунд до unhealthy
RESTART = 20            # секунд на перезапуск и прогрев
DB_OUTAGE = 30          # база недоступна столько


def simulate(liveness_checks_db: bool) -> None:
    label = "liveness проверяет базу" if liveness_checks_db else "liveness проверяет только процесс"
    print(f"\n── {label} ──")
    print(f"  реплик: {REPLICAS}, отказ базы: {DB_OUTAGE} с")

    if not liveness_checks_db:
        print(f"  t=0     база отказала")
        print(f"  t=0     readiness → 503 у всех реплик (честно)")
        print(f"  t=0     liveness → 200, перезапусков нет")
        print(f"  t={DB_OUTAGE}    база вернулась")
        print(f"  t={DB_OUTAGE}    readiness → 200, трафик восстановлен")
        print(f"  ИТОГО недоступность: {DB_OUTAGE} с (равна отказу базы)")
        return

    t = 0
    print(f"  t=0     база отказала")
    t += DETECTION
    print(f"  t={t}    все {REPLICAS} реплики → unhealthy ОДНОВРЕМЕННО")
    print(f"  t={t}    все {REPLICAS} перезапускаются")
    t += RESTART
    print(f"  t={t}    реплики поднялись, лавина подключений к базе")
    if t < DB_OUTAGE:
        print(f"  t={t}    база ещё недоступна → liveness падает снова")
        t += DETECTION + RESTART
        print(f"  t={t}    второй круг перезапусков")
    print(f"  ИТОГО недоступность: не менее {t} с при отказе базы в {DB_OUTAGE} с")
    print(f"  усиление: ×{t / DB_OUTAGE:.1f}")


simulate(liveness_checks_db=False)
simulate(liveness_checks_db=True)
PY

python3 cascade.py

── liveness проверяет только процесс ──
  реплик: 3, отказ базы: 30 с
  t=0     база отказала
  t=0     readiness → 503 у всех реплик (честно)
  t=0     liveness → 200, перезапусков нет
  t=30    база вернулась
  t=30    readiness → 200, трафик восстановлен
  ИТОГО недоступность: 30 с (равна отказу базы)

── liveness проверяет базу ──
  реплик: 3, отказ базы: 30 с
  t=0     база отказала
  t=15    все 3 реплики → unhealthy ОДНОВРЕМЕННО
  t=15    все 3 перезапускаются
  t=35    реплики поднялись, лавина подключений к базе
  ИТОГО недоступность: не менее 35 с при отказе базы в 30 с
  усиление: ×1.2

cd /tmp/probes
cat > degraded.py <<'PY'
"""Readiness с разделением обязательных и необязательных зависимостей."""
import json
import os
import socket
from http.server import BaseHTTPRequestHandler, HTTPServer

CRITICAL = {"db": ("db", 5432)}          # без них работать нельзя
OPTIONAL = {"cache": ("cache", 6379)}    # без них медленнее, но можно


def reachable(host: str, port: int, timeout: float = 1.0) -> bool:
    s = socket.socket()
    s.settimeout(timeout)
    try:
        s.connect((host, port))
        return True
    except OSError:
        return False
    finally:
        s.close()


class H(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/healthz":
            # Liveness: только процесс
            self._json(200, {"alive": True})
            return

        checks = {}
        critical_ok = True
        for name, (host, port) in CRITICAL.items():
            ok = reachable(host, port)
            checks[name] = "ok" if ok else "недоступен"
            critical_ok = critical_ok and ok
        for name, (host, port) in OPTIONAL.items():
            checks[name] = "ok" if reachable(host, port) else "недоступен (необязателен)"

        degraded = any("недоступен" in v for v in checks.values())
        status = "ready" if critical_ok and not degraded else \
                 "degraded" if critical_ok else "not_ready"
        self._json(200 if critical_ok else 503, {"status": status, "checks": checks})

    def _json(self, code, payload):
        body = json.dumps(payload, ensure_ascii=False).encode()
        self.send_response(code)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *a):
        pass


print(f"запущен, pid={os.getpid()}", flush=True)
HTTPServer(("0.0.0.0", 8000), H).serve_forever()
PY

cat > compose.degraded.yaml <<'EOF'
name: degraded

services:
  api:
    image: python:3.13-slim
    volumes:
      - ./degraded.py:/app.py:ro
    command: ["python", "-u", "/app.py"]
    ports:
      - "127.0.0.1:8620:8000"

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: x
    tmpfs:
      - /var/lib/postgresql/data:size=256m

  cache:
    image: redis:8-alpine
EOF

docker compose -f compose.degraded.yaml up -d > /dev/null 2>&1
sleep 12

show() { curl -s -m 5 -w ' [HTTP %{http_code}]' "http://127.0.0.1:8620/readyz" \
         | python3 -c "
import json, sys
raw = sys.stdin.read()
body, _, code = raw.rpartition(' [HTTP ')
d = json.loads(body)
print(f\"  {d['status']:<10} {code.rstrip(']')}  {d['checks']}\")
"; }

echo "═══ всё работает ═══"
show
echo "═══ кэш недоступен (необязательная зависимость) ═══"
docker compose -f compose.degraded.yaml stop cache > /dev/null 2>&1
sleep 3
show
echo "═══ база недоступна (обязательная) ═══"
docker compose -f compose.degraded.yaml stop db > /dev/null 2>&1
sleep 3
show
echo "═══ liveness при этом ═══"
printf '  /healthz: HTTP %s\n' "$(curl -s -m 3 -o /dev/null -w '%{http_code}' http://127.0.0.1:8620/healthz)"

docker compose -f compose.degraded.yaml down > /dev/null 2>&1

═══ всё работает ═══
  ready      200  {'db': 'ok', 'cache': 'ok'}
═══ кэш недоступен (необязательная зависимость) ═══
  degraded   200  {'db': 'ok', 'cache': 'недоступен (необязателен)'}
═══ база недоступна (обязательная) ═══
  not_ready  503  {'db': 'недоступен', 'cache': 'недоступен (необязателен)'}
═══ liveness при этом ═══
  /healthz: HTTP 200

cd /tmp/probes
cat > Dockerfile.hc <<'EOF'
FROM python:3.13-slim
COPY app.py /app.py
HEALTHCHECK --interval=30s --timeout=10s --retries=5 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=2).status==200 else 1)"
CMD ["python", "-u", "/app.py"]
EOF

docker build -q -f Dockerfile.hc -t probes:hc . > /dev/null

cat > compose.prio.yaml <<'EOF'
name: prio

services:
  from-image:
    image: probes:hc

  overridden:
    image: probes:hc
    healthcheck:
      test: ["CMD", "python", "-c",
             "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=1).status==200 else 1)"]
      interval: 3s
      timeout: 1s
      retries: 2

  disabled:
    image: probes:hc
    healthcheck:
      disable: true
EOF

docker compose -f compose.prio.yaml up -d > /dev/null 2>&1
sleep 6

for svc in from-image overridden disabled; do
    cid="$(docker compose -f compose.prio.yaml ps -q $svc)"
    hc="$(docker inspect "$cid" --format '{{if .Config.Healthcheck}}{{json .Config.Healthcheck.Test}} interval={{.Config.Healthcheck.Interval}}{{else}}(нет){{end}}')"
    printf '  %-12s %s\n' "$svc" "$(echo "$hc" | sed 's/000000000ns/s/' | cut -c1-90)"
done

docker compose -f compose.prio.yaml down > /dev/null 2>&1
docker rmi -f probes:hc > /dev/null 2>&1
cd /tmp && rm -rf /tmp/probes

  from-image   ["CMD-SHELL","python -c \"import urllib.request,sys; ..."] interval=30s
  overridden   ["CMD","python","-c","import urllib.request,sys; ..."] interval=3s
  disabled     ["NONE"]

docker run -d --name pr --health-cmd='python -c "import sys; sys.exit(0)"' \
    --health-interval=3s --health-retries=2 --health-timeout=2s \
    python:3.13-slim sleep 60 > /dev/null
sleep 8
docker inspect pr --format 'health={{.State.Health.Status}} проверок={{len .State.Health.Log}}'
docker rm -f pr > /dev/null