Як написати добрий healthcheck для сервісу в Compose?

Question

Accepted Answer

Healthcheck - команда, яку Docker періодично виконує всередині контейнера, щоб визначити, чи сервіс справді працює, а не просто запущений процес. Результат - стан starting, healthy чи unhealthy.
services:
  postgres:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s        # як часто перевіряти
      timeout: 3s         # скільки чекати на відповідь
      retries: 10         # скільки невдач поспіль до unhealthy
      start_period: 20s   # пільговий період на старті: невдачі не рахуються
      start_interval: 1s  # частіші перевірки під час start_period

app:
    build: .
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8000/up"]
      interval: 10s
      timeout: 3s
      retries: 3

Що робить healthcheck добрим:

перевіряє здатність обслуговувати запити, а не лише живий процес: pg_isready, redis-cli ping, HTTP-запит до ендпойнта здоров'я (у Laravel 11+ - маршрут /up);
легкий і швидкий - він виконується кожні кілька секунд; важкі запити до бази в healthcheck створюють навантаження;
не залежить від зовнішніх сервісів у перевірці «живучості»: якщо застосунок вважає себе unhealthy через недоступний сторонній API, оркестратор почне його перезапускати, що нічого не виправить;
інструмент є в образі: curl чи wget часто відсутні в мінімальних образах - перевірка падає не через сервіс, а через відсутню програму;
$$ у Compose - щоб змінна підставилася всередині контейнера, а не при розборі файлу.

Як використовується стан:

depends_on з condition: service_healthy - залежний сервіс стартує лише після готовності;
docker compose ps показує стан, а docker inspect - історію останніх перевірок з виводом команди;
docker compose up --wait - дочекатися, поки всі сервіси стануть healthy (зручно в CI);
оркестратори (Swarm) перезапускають unhealthy-контейнери. Звичайний Docker сам по собі не перезапускає unhealthy-контейнер - лише позначає його.

Healthcheck в образі (HEALTHCHECK у Dockerfile) задає перевірку за замовчуванням; у Compose її можна перевизначити чи вимкнути (disable: true).
Докладніше в документації: Сервіси Compose: healthcheck

Як написати добрий healthcheck для сервісу в Compose?

Схожі питання