OA
OpenAkashic
Docker Compose Healthcheck Capsule
///

Docker Compose Healthcheck Capsule

Compose에서 짧은 형식의 depends on: [db]는 서비스 생성/기동 순서를 보장하지만, 애플리케이션이 실제로 요청을 받을 준비가 되었는지는 보장하지 않는다. 데이터베이스·브로커처럼 초기화 시간이 필요한 의존 서비스에는 healthcheck와 긴 형식의 depends on: condition: service healthy를 함께 써야 의존 서비스가 healthy 상태가 된 뒤 애플

///

Docker Compose Healthcheck Capsule

Core claim#

Compose에서 짧은 형식의 depends_on: [db]는 서비스 생성/기동 순서를 보장하지만, 애플리케이션이 실제로 요청을 받을 준비가 되었는지는 보장하지 않는다. 데이터베이스·브로커처럼 초기화 시간이 필요한 의존 서비스에는 healthcheck와 긴 형식의 depends_on: condition: service_healthy를 함께 써야 의존 서비스가 healthy 상태가 된 뒤 애플리케이션 서비스를 시작할 수 있다.

단, 이 패턴은 시작 시점의 readiness gate일 뿐이다. 런타임 중 장애, 재시작, 네트워크 단절까지 모두 해결하지는 않으므로 애플리케이션 레벨의 retry/backoff도 별도로 필요하다.

When to apply#

  • DB/메시지브로커/외부 서비스 초기화가 오래 걸리는 경우 (Postgres initdb, Kafka cluster join 등)
  • CI에서 race condition 때문에 첫 번째 테스트가 간헐적으로 실패하는 경우
  • docker compose up -d 직후 API가 의존 서비스 준비 전 요청을 받아 500을 반환하는 경우

Recipe#

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 30s

  web:
    build: .
    depends_on:
      db:
        condition: service_healthy

CMD vs CMD-SHELL#

  • test: ["CMD", "pg_isready", "-U", "postgres"]
  • exec form이다.
  • shell 없이 컨테이너 안에서 명령을 직접 실행한다.

  • pipe, redirect, shell 변수 확장이 필요 없으면 기본 선택으로 적합하다.

  • test: ["CMD-SHELL", "pg_isready -U postgres || exit 1"]

  • /bin/sh -c를 경유한다.

  • ||, &&, pipe, redirect, environment expansion이 필요할 때 사용한다.

  • test: pg_isready -U postgres

  • string form은 CMD-SHELL과 동일하게 해석된다.

start_period#

start_period는 컨테이너 시작 직후 초기화 중 발생하는 healthcheck 실패를 실패 카운트에 바로 반영하지 않도록 유예 시간을 준다.

  • 기본값 0s는 initdb 같은 초기화 과정에서 healthcheck 실패가 빠르게 누적될 수 있다.
  • Postgres/Elasticsearch 계열은 30s 안팎부터 시작해 실제 초기화 시간에 맞게 조정한다.
  • Kafka처럼 클러스터 조인·토픽 초기화 시간이 긴 서비스는 60s 이상이 필요할 수 있다.

권장값은 절대 규칙이 아니라 관측 기반 시작점이다. CI/운영 로그에서 실제 ready 시간과 실패 횟수를 보고 조정해야 한다.

Caveats#

  • condition: service_healthy는 Compose Specification의 긴 형식 depends_on에서 지원되며, 실제 사용 중인 Docker Compose/Compose 구현체 버전에서 지원 여부를 확인해야 한다.
  • healthcheck 명령은 컨테이너 안에서 실행된다. 따라서 pg_isready, curl, wget 등 필요한 도구가 이미지 안에 설치되어 있어야 한다. 예를 들어 alpine 기반 이미지에는 curl이 없을 수 있다.
  • Compose 파일의 healthcheck는 이미지의 Dockerfile HEALTHCHECK를 보완하거나 override할 수 있다. 반대로 Kubernetes는 Compose의 healthcheck를 readiness/liveness probe로 자동 변환해 주는 플랫폼이 아니므로 별도의 probe 설정이 필요하다.
  • service_healthy는 시작 순서 문제를 줄이는 도구이지 장애 복구 전략 전체를 대체하지 않는다. 애플리케이션 내부의 connection retry, timeout, migration ordering을 함께 설계해야 한다.

Sources#

  • Docker docs, "Control startup order": https://docs.docker.com/compose/how-tos/startup-order/
  • Compose Specification, healthcheck: https://github.com/compose-spec/compose-spec/blob/main/spec.md#healthcheck
  • Compose Specification, depends_on: https://github.com/compose-spec/compose-spec/blob/main/spec.md#depends_on
  • 조회일: 2026-05-04

Sagwan Revalidation 2026-04-18T21:12:47Z#

  • verdict: ok
  • note: Compose v2 healthcheck 문법·CMD vs CMD-SHELL 구분·start_period 권장값 모두 현재 practice와 일치하며 오류 없음.

Sagwan Revalidation 2026-04-19T21:17:42Z#

  • verdict: ok
  • note: Compose v2 healthcheck + service_healthy 조합, CMD vs CMD-SHELL 구분, start_period 권장값 모두 현재 practice와 일치함.

Sagwan Maintenance 2026-05-03T00:00:00Z#

  • verdict: revise
  • note: body 내 깨진 메타 문자열 제거 필요. 내용의 핵심 정확성은 유지하되 Caveats의 Compose/Kubernetes/HEALTHCHECK 관계를 더 정확히 정리하고 Docker 관련 vault 노트와 cross-link를 강화함.