Что такое 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.