re:re:actable
Урок 053 минуты чтения

Что такое healthcheck

На этой странице
Кратко

Healthcheck — команда, которую Docker периодически выполняет внутри контейнера, чтобы понять, что приложение не просто запущено, а работает. Код выхода 0 — healthy, иначе — после нескольких неудач — unhealthy. Задаётся инструкцией HEALTHCHECK в Dockerfile или полем healthcheck в Compose. Статус используют depends_on: condition: service_healthy, балансировщики и оркестраторы. Сам Docker unhealthy-контейнер не перезапускает.

Вопрос

Что такое healthcheck и как его настроить?

Running не значит ready

Процесс жив, но:

  • PostgreSQL ещё инициализирует базу и не принимает подключения;
  • API стартовал, но не подключился к БД;
  • Node.js завис в бесконечном цикле, а порт слушается;
  • Nginx работает, но upstream недоступен.

В Dockerfile

HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
ПараметрСмысл
--intervalКак часто проверять
--timeoutСколько ждать ответа одной проверки
--start-periodВремя на старт: неудачи в этот период не считаются
--retriesСколько неудач подряд до статуса unhealthy

Если в образе нет wget/curl (slim, distroless), проверку пишут на Node.js:

// healthcheck.js
fetch("http://localhost:3000/health")
  .then((r) => process.exit(r.ok ? 0 : 1))
  .catch(() => process.exit(1));
HEALTHCHECK CMD ["node", "healthcheck.js"]

В Compose

services:
  api:
    build: .
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s
 
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10
 
  redis:
    image: redis:8-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

CMD выполняет команду напрямую, CMD-SHELL — через /bin/sh -c (нужен для ||, переменных и пайпов).

Посмотреть статус

docker ps                                    # Up 2 minutes (healthy)
docker inspect -f '{{json .State.Health}}' api

Что должен проверять /health

ТипВопросПример
LivenessПроцесс жив и не завис?GET /health → 200 без обращения к БД
ReadinessГотов принимать трафик?Проверить пул БД, прогрев кэша
DependencyЖивы ли внешние сервисы?Отдельный эндпоинт для мониторинга

Healthcheck контейнера обычно — лёгкий liveness. Если он проверяет БД, то падение базы сделает unhealthy все реплики API разом. Различие liveness/readiness особенно важно в Kubernetes, где это разные пробы.

Частые ошибки

  • Считать running-контейнер готовым.
  • Делать тяжёлый healthcheck с запросом к БД каждые 2 секунды.
  • Забыть start_period для медленно стартующего сервиса.
  • Использовать curl, которого нет в образе, — контейнер навсегда unhealthy.
  • Ожидать, что Docker сам перезапустит unhealthy-контейнер (это делают Swarm, Kubernetes или внешний мониторинг).

Что важно помнить

  • Healthcheck выполняется внутри контейнера — localhost там правильный адрес.
  • Статус healthy — основа для порядка запуска в Compose.
  • Healthcheck не заменяет повторные попытки подключения в коде приложения.

Мини-шпаргалка

  • 0 — healthy, не 0 — неудача.
  • interval, timeout, start_period, retries.
  • Postgres — pg_isready, Redis — redis-cli ping.
  • CMD-SHELL — когда нужна оболочка.
  • Liveness лёгкий, readiness — про зависимости.

Документация

Docker: Dockerfile reference — HEALTHCHECK, Docker Compose: healthcheck.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам