5.8. HEALTHCHECK

HEALTHCHECK [опции] CMD команда
HEALTHCHECK NONE

   container стартовал
          │
          ▼
   ┌──────────────┐  проверки идут с интервалом --start-interval
   │  starting    │  неудачи НЕ увеличивают счётчик
   └──────┬───────┘
          │  первая успешная проверка
          │  ИЛИ истёк --start-period
          ▼
   ┌──────────────┐  проверки с интервалом --interval
   │   healthy    │◄─────────────────┐
   └──────┬───────┘                  │ успешная проверка
          │ неудача                  │ сбрасывает счётчик
          ▼                          │
   счётчик неудач++ ─────────────────┘
          │
          │ счётчик достиг --retries
          ▼
   ┌──────────────┐
   │  unhealthy   │
   └──────────────┘

   без --start-period (retries=3, interval=10s):
   0s   старт
   10s  проверка 1 — неудача (приложение ещё грузится), счётчик 1
   20s  проверка 2 — неудача, счётчик 2
   30s  проверка 3 — неудача, счётчик 3 → UNHEALTHY
   40s  приложение готово, но статус уже испорчен

HEALTHCHECK CMD curl -f http://localhost:8000/health-with-db || exit 1

   база данных недоступна 30 секунд
        │
        ▼
   все 10 реплик API становятся unhealthy
        │
        ▼
   оркестратор перезапускает все 10 одновременно
        │
        ▼
   база поднялась, но получает лавину переподключений
        │
        ▼
   отказ усугубляется

HEALTHCHECK --interval=15s --timeout=3s --start-period=30s --retries=3 \
  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)"

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 CMD ...

docker inspect <container> --format '{{json .State.Health}}'

mkdir -p /tmp/healthcheck && cd /tmp/healthcheck

cat > server.py <<'PY'
"""Сервер с управляемым временем старта и состоянием здоровья."""
import http.server
import os
import socketserver
import threading
import time

STARTUP_DELAY = int(os.environ.get("STARTUP_DELAY", "0"))
FAIL_AFTER = int(os.environ.get("FAIL_AFTER", "0"))

ready = False
started_at = time.time()


class Handler(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        healthy = ready
        if FAIL_AFTER and (time.time() - started_at) > FAIL_AFTER:
            healthy = False

        if self.path == "/healthz":
            code = 200 if healthy else 503
            body = b"ok" if healthy else b"unhealthy"
        else:
            code, body = 200, b"hello"

        self.send_response(code)
        self.send_header("Content-Type", "text/plain")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, fmt, *args):
        pass


def warmup():
    global ready
    if STARTUP_DELAY:
        print(f"инициализация {STARTUP_DELAY} c...", flush=True)
        time.sleep(STARTUP_DELAY)
    ready = True
    print("готов принимать запросы", flush=True)


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

with socketserver.TCPServer(("0.0.0.0", 8000), Handler) as httpd:
    print("слушаю 8000", flush=True)
    httpd.serve_forever()
PY

cat > Dockerfile.basic <<'EOF'
FROM python:3.13-slim
COPY server.py /server.py
EXPOSE 8000

HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
  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", "/server.py"]
EOF

docker build -q -f Dockerfile.basic -t hc:basic . > /dev/null
docker run -d --name hc-basic hc:basic > /dev/null

echo "наблюдаем переход статуса:"
for i in $(seq 1 6); do
    printf '  %2ds: %s\n' "$((i*3))" \
        "$(docker inspect hc-basic --format '{{.State.Health.Status}}')"
    sleep 3
done

наблюдаем переход статуса:
   3s: starting
   6s: healthy
   9s: healthy
  12s: healthy
  15s: healthy
  18s: healthy

docker ps --filter name=hc-basic --format 'table {{.Names}}\t{{.Status}}'

NAMES      STATUS
hc-basic   Up 20 seconds (healthy)

docker inspect hc-basic --format '{{json .State.Health}}' | python3 -m json.tool | head -20

{
    "Status": "healthy",
    "FailingStreak": 0,
    "Log": [
        {
            "Start": "2026-07-30T14:22:10.481Z",
            "End": "2026-07-30T14:22:10.612Z",
            "ExitCode": 0,
            "Output": ""
        }
    ]
}

docker rm -f hc-basic > /dev/null

echo "=== без --start-period, приложение стартует 25 секунд ==="
docker run -d --name hc-slow -e STARTUP_DELAY=25 hc:basic > /dev/null

for i in $(seq 1 7); do
    printf '  %2ds: статус=%-10s неудач=%s\n' "$((i*5))" \
        "$(docker inspect hc-slow --format '{{.State.Health.Status}}')" \
        "$(docker inspect hc-slow --format '{{.State.Health.FailingStreak}}')"
    sleep 5
done
docker rm -f hc-slow > /dev/null

=== без --start-period, приложение стартует 25 секунд ===
   5s: статус=starting   неудач=1
  10s: статус=unhealthy  неудач=3
  15s: статус=unhealthy  неудач=5
  20s: статус=unhealthy  неудач=7
  25s: статус=unhealthy  неудач=9
  30s: статус=healthy    неудач=0
  35s: статус=healthy    неудач=0

cat > Dockerfile.startperiod <<'EOF'
FROM python:3.13-slim
COPY server.py /server.py
EXPOSE 8000

HEALTHCHECK --interval=5s --timeout=3s --start-period=40s --start-interval=2s --retries=3 \
  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", "/server.py"]
EOF

docker build -q -f Dockerfile.startperiod -t hc:sp . > /dev/null
docker run -d --name hc-sp -e STARTUP_DELAY=25 hc:sp > /dev/null

echo "=== с --start-period=40s ==="
for i in $(seq 1 7); do
    printf '  %2ds: статус=%-10s неудач=%s\n' "$((i*5))" \
        "$(docker inspect hc-sp --format '{{.State.Health.Status}}')" \
        "$(docker inspect hc-sp --format '{{.State.Health.FailingStreak}}')"
    sleep 5
done
docker rm -f hc-sp > /dev/null

=== с --start-period=40s ===
   5s: статус=starting   неудач=0
  10s: статус=starting   неудач=0
  15s: статус=starting   неудач=0
  20s: статус=starting   неудач=0
  25s: статус=starting   неудач=0
  30s: статус=healthy    неудач=0
  35s: статус=healthy    неудач=0

docker run -d --name hc-fail -e FAIL_AFTER=10 hc:basic > /dev/null

echo "=== приложение начинает отвечать 503 через 10 секунд ==="
for i in $(seq 1 8); do
    printf '  %2ds: статус=%-10s неудач=%s\n' "$((i*5))" \
        "$(docker inspect hc-fail --format '{{.State.Health.Status}}')" \
        "$(docker inspect hc-fail --format '{{.State.Health.FailingStreak}}')"
    sleep 5
done

=== приложение начинает отвечать 503 через 10 секунд ===
   5s: статус=healthy    неудач=0
  10s: статус=healthy    неудач=0
  15s: статус=healthy    неудач=1
  20s: статус=healthy    неудач=2
  25s: статус=unhealthy  неудач=3
  30s: статус=unhealthy  неудач=4
  35s: статус=unhealthy  неудач=5
  40s: статус=unhealthy  неудач=6

docker ps --filter name=hc-fail --format '{{.Names}} {{.Status}}'
docker inspect hc-fail --format 'Running: {{.State.Running}}  RestartCount: {{.RestartCount}}'

hc-fail Up 45 seconds (unhealthy)
Running: true  RestartCount: 0

docker rm -f hc-fail > /dev/null
docker run -d --name hc-restart --restart=always -e FAIL_AFTER=8 hc:basic > /dev/null
sleep 35
docker inspect hc-restart --format 'health={{.State.Health.Status}} restarts={{.RestartCount}}'
docker rm -f hc-restart > /dev/null

health=unhealthy restarts=0

docker run -d --name hc-events -e FAIL_AFTER=8 hc:basic > /dev/null

timeout 30 docker events --filter 'container=hc-events' --filter 'event=health_status' \
    --format '{{.Time}} {{.Status}}' 2>/dev/null
docker rm -f hc-events > /dev/null

1785492141 health_status: healthy
1785492166 health_status: unhealthy

cat > Dockerfile.badcheck <<'EOF'
FROM python:3.13-slim
COPY server.py /server.py
# ОШИБКА: curl не установлен в slim-образе
HEALTHCHECK --interval=5s --retries=2 CMD curl -f http://localhost:8000/healthz || exit 1
CMD ["python", "-u", "/server.py"]
EOF

docker build -q -f Dockerfile.badcheck -t hc:bad . > /dev/null
docker run -d --name hc-bad hc:bad > /dev/null
sleep 14

docker inspect hc-bad --format '{{.State.Health.Status}}'
echo "--- вывод последней проверки ---"
docker inspect hc-bad --format '{{range .State.Health.Log}}{{.ExitCode}}: {{.Output}}{{end}}' | tail -2
docker rm -f hc-bad > /dev/null

unhealthy
--- вывод последней проверки ---
127: /bin/sh: 1: curl: not found

cat > Dockerfile.nodeps <<'EOF'
FROM python:3.13-slim
COPY server.py /server.py
EXPOSE 8000

# Вариант 1: urllib из стандартной библиотеки
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
  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", "/server.py"]
EOF

docker build -q -f Dockerfile.nodeps -t hc:nodeps . > /dev/null
docker run -d --name hc-nodeps hc:nodeps > /dev/null
sleep 25
docker inspect hc-nodeps --format 'статус: {{.State.Health.Status}}'
docker rm -f hc-nodeps > /dev/null

статус: healthy

cat > Dockerfile.tcp <<'EOF'
FROM alpine:3.21
RUN apk add --no-cache python3
COPY server.py /server.py
EXPOSE 8000
# BusyBox wget есть в Alpine по умолчанию
HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 \
  CMD wget -q -O /dev/null http://127.0.0.1:8000/healthz || exit 1
CMD ["python3", "-u", "/server.py"]
EOF

docker build -q -f Dockerfile.tcp -t hc:tcp . > /dev/null
docker run -d --name hc-tcp hc:tcp > /dev/null
sleep 20
docker inspect hc-tcp --format 'статус: {{.State.Health.Status}}'
docker rm -f hc-tcp > /dev/null

статус: healthy

cat > Dockerfile.inherit <<'EOF'
FROM hc:basic
# Базовый образ имеет HEALTHCHECK; отменяем его
HEALTHCHECK NONE
EOF

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

docker image inspect hc:basic --format 'базовый: {{if .Config.Healthcheck}}задан{{else}}нет{{end}}'
docker image inspect hc:none  --format 'после NONE: {{index .Config.Healthcheck.Test 0}}'

базовый: задан
после NONE: NONE

docker run -d --name hc-override --no-healthcheck hc:basic > /dev/null
sleep 3
docker inspect hc-override --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}проверка отключена{{end}}'
docker rm -f hc-override > /dev/null

docker run -d --name hc-custom \
    --health-cmd='python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen(\"http://127.0.0.1:8000/\", timeout=2).status==200 else 1)"' \
    --health-interval=5s \
    --health-start-period=15s \
    --health-retries=2 \
    hc:basic > /dev/null
sleep 18
docker inspect hc-custom --format 'своя проверка: {{.State.Health.Status}}'
docker rm -f hc-custom > /dev/null

проверка отключена
своя проверка: healthy

services:
  api:
    image: hc:basic
    environment:
      APP_PORT: "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: 10s
      timeout: 3s
      start_period: 30s
      start_interval: 2s
      retries: 3

  worker:
    image: myapp:worker
    depends_on:
      api:
        condition: service_healthy

cd /tmp
docker rmi -f $(docker images -q --filter 'reference=hc:*') 2>/dev/null || true
rm -rf /tmp/healthcheck

mkdir -p /tmp/vhc && cd /tmp/vhc
printf 'FROM python:3.13-slim\nHEALTHCHECK --interval=3s --start-period=5s --retries=2 CMD python -c "import sys; sys.exit(0)"\nCMD ["sleep","60"]\n' > Dockerfile
docker build -q -t vhc:1 . > /dev/null
docker run -d --name vhc-t vhc:1 > /dev/null
sleep 8
docker ps --filter name=vhc-t --format '{{.Status}}'
docker rm -f vhc-t > /dev/null; docker rmi -f vhc:1 > /dev/null; cd /tmp && rm -rf /tmp/vhc