Порядок старта — не готовность: depends_on, healthcheck и restart-политики

depends_on упорядочивает старт, а не готовность

Обычный depends_on: [db] заставляет Compose стартовать db перед api и останавливать после — это вся гарантия. Он не ждёт, пока процесс внутри db будет готов; в момент, когда контейнер создан и его entrypoint запущен, зависимость считается удовлетворённой, и api стартует. Для всего stateful это гонка, потому что старт контейнера и готовность сервиса — разные события, разделённые реальным временем инициализации: Postgres проигрывает WAL (write-ahead log — журнал упреждающей записи) и открывает сокет, Kafka выбирает контроллер, JVM-приложение прогревается — где-то от пары сотен миллисекунд до многих секунд. Зависимый выстреливает первый запрос в этот зазор и получает connection-refused. Корректная форма делает зависимость условной по здоровью:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
      interval: 5s          # как часто пробить после старта
      timeout: 3s           # проба медленнее этого = провал
      retries: 5            # подряд провалов до "unhealthy"
      start_period: 30s     # окно благодати: провалы тут не идут в retries
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy   # ждать, пока healthcheck db пройдёт

Теперь api держится, пока healthcheck db не сообщит healthy, то есть pg_isready реально успешно отработал против слушающего, принимающего Postgres. Доступные условия: service_started (слабый эквивалент дефолта — контейнер поднят), service_healthy (healthcheck проходит — то, что нужно для stateful-зависимостей) и service_completed_successfully (зависимость отработала до exit 0, для одноразовых init/seed/migration-задач).

Ручки healthcheck — это реальный протокол

Healthcheck — это команда, которую Docker гоняет внутри контейнера по расписанию, и её код возврата — вердикт: 0 healthy, 1 unhealthy. Четыре ручки тайминга — не украшение:

• interval (дефолт 30s) — как часто проба бежит после поднятия контейнера. Более тесные интервалы (5s) быстрее ловят готовность и сбой, но стоят большего числа исполнений пробы.
• timeout (дефолт 30s) — одна проба медленнее этого = провал. Ставь его ниже interval, чтобы зависшая проба не наложилась на следующую.
• retries (дефолт 3) — сколько подряд провалов переключают статус в unhealthy. Один временный провал не помечает сервис как unhealthy.
• start_period (дефолт 0s) — стартовое окно благодати, в течение которого провальные пробы не идут в зачёт retries и не помечают контейнер unhealthy. Это ручка, которую упускают: база, которой нужно 25 секунд на инициализацию, провалит первые несколько проб; без start_period, достаточного покрыть инициализацию, эти провалы прожигают retries, и контейнер объявляется unhealthy и никогда не становится удовлетворённой зависимостью — стек встаёт в дедлок на сервисе, который всего лишь ещё грузится. Задавай start_period под худший холодный старт, щедро.

Все четыре ручки вместе образуют двухфазный протокол: start_period + interval/timeout отвечают на «сколько может занять старт и как часто пробить», а retries — на «сколько подряд провалов после старта означают поломку». Когда встретишь стек, намертво зависший при старте или сервис, который никогда не доходит до healthy, сначала проверь, какая ручка настроена неверно — это быстрее, чем добавлять sleep.

Самый частый сломанный healthcheck — тот, что проверяет не то — test: ["CMD", "true"] или пинг собственного TCP-порта контейнера — который рапортует healthy, пока приложение реально не обслуживает. Реальный healthcheck проходит путь готовности, который используют зависимые: pg_isready для Postgres, HTTP GET /healthz для веб-сервиса, redis-cli ping для Redis.

Restart-политика: лечить или прятать

restart: решает, что происходит при выходе контейнера. Варианты: no (дефолт — никогда не рестартить), on-failure (рестарт только на ненулевом выходе, опционально с лимитом: on-failure:5), unless-stopped (рестарт при любом выходе, если ты явно не остановил) и always (рестарт при любом выходе, даже после ручной остановки, как только демон перезапустится). Senior-ловушка в том, что агрессивная restart-политика прячет крахи: сервис, падающий на реальном баге конфигурации, но с restart: always, входит в тесный crash-restart-цикл, и снаружи стек «выглядит поднятым» — контейнер существует и постоянно пересоздаётся — пока ничего не обслуживает и заливает логи. Docker гасит это экспоненциальным backoff между рестартами (от ~100ms с удвоением), но backoff замедляет цикл, а не вскрывает баг. Взаимодействие с healthcheck тоже важно: контейнер может быть запущен и перезапускаться, но никогда healthy, поэтому зависимый, гейтнутый на service_healthy, корректно отказывается стартовать против циклящего зависимого, а не гонится с ним. Используй on-failure с лимитом в dev, чтобы реально сломанный сервис остановился и показал ошибку, а always/unless-stopped оставь для сервисов, которым доверяешь быть временно нестабильными, а не хронически сломанными.