Docker healthcheck: настройка и мониторинг

Коротко. Инструкция HEALTHCHECK в Dockerfile говорит Docker, как проверять, что приложение внутри контейнера действительно живо, а не просто «процесс запущен». Docker периодически выполняет команду (обычно curl к health-эндпоинту) и выставляет контейнеру статус healthy или unhealthy. Оркестраторы используют этот статус для перезапуска и балансировки. Но healthcheck живёт внутри хоста — снаружи за доступностью следит synthetic-мониторинг сайтов.

Зачем нужен HEALTHCHECK

Без healthcheck Docker считает контейнер «работающим», пока жив главный процесс. Но процесс может висеть в дедлоке, не отвечать на запросы или зависнуть на бесконечном GC — для Docker он всё ещё «running». HEALTHCHECK добавляет проверку на уровне приложения.

• healthy — команда вернула 0, приложение отвечает;
• unhealthy — команда падала retries раз подряд;
• starting — контейнер в пределах start-period, ещё прогревается;
• none — healthcheck не задан.

HEALTHCHECK в Dockerfile

Базовый пример для веб-приложения с health-эндпоинтом. Curl с флагом -f вернёт ненулевой код на 4xx/5xx, что Docker засчитает как провал.

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD curl -fsS http://localhost:8080/healthz || exit 1

CMD ["node", "server.js"]

Параметры healthcheck

Healthcheck в docker-compose

В compose тот же healthcheck описывается декларативно, а другие сервисы могут ждать статус healthy через depends_on с условием.

services:
  web:
    build: .
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 5s
      start_period: 20s
      retries: 3
  worker:
    build: ./worker
    depends_on:
      web:
        condition: service_healthy

Команда healthcheck должна быть лёгкой и проверять именно приложение, а не зависимости. Тяжёлая проверка БД внутри healthcheck превратит контейнер в unhealthy при первом же сетевом лаге.

Чего healthcheck не видит

HEALTHCHECK работает изнутри хоста: Docker дёргает localhost внутри контейнера. Он не проверяет, доступен ли сервис снаружи — через reverse-proxy, балансировщик, DNS и публичный TLS. Контейнер может быть healthy, а сайт — недоступен из-за просроченного сертификата на nginx или поломанного DNS.

Внешний слой поверх контейнеров

enterno.io проверяет полный путь снаружи, как пользователь: HTTP-ответ, валидность SSL, DNS-резолв и Ping из регионов RU / EU / US. Это дополняет Docker healthcheck: healthcheck лечит контейнер, внешний монитор ловит проблемы на периметре. Бесплатно 10 мониторов с интервалом 5 минут (платно — 1 минута / 30 секунд).

Для контейнеризированных cron-задач и батч-воркеров используйте heartbeat-мониторинг: контейнер пингует уникальный URL в конце задачи; пропущенный пинг = алерт о том, что задача не отработала. Это надёжнее healthcheck для разовых джоб, которые завершаются.

FAQ

Чем HEALTHCHECK отличается от readinessProbe в Kubernetes?

HEALTHCHECK — фича самого Docker. В Kubernetes пробы управляются kubelet и игнорируют Docker HEALTHCHECK. В k8s используйте liveness/readiness probes напрямую.

Почему контейнер unhealthy, хотя приложение работает?

Чаще всего команда healthcheck неверна: нет curl в образе, неправильный порт или путь, слишком короткий timeout. Проверьте docker inspect → секцию Health.

Нужен ли curl в образе для healthcheck?

Не обязательно: можно использовать wget, встроенный healthcheck приложения (node healthcheck.js) или TCP-проверку. В alpine curl ставится отдельно.

Как мониторить контейнерный cron-джоб?

Через heartbeat: задача делает пинг на enterno.io/heartbeat в конце; отсутствие пинга в окне = алерт о незапустившейся или зависшей джобе.

Добавьте проверку снаружи: создайте монитор на enterno.io/heartbeat для cron-джоб или на /monitors для сайта. Полезное: мониторинг контейнеров, health-check эндпоинты, мониторинг для разработчиков.