Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

Docker운영과 디버깅

healthcheck와 container readiness

컨테이너가 단순히 떠 있는 상태와 실제로 요청을 받을 준비가 된 상태가 왜 다른지, healthcheck를 어떤 기준으로 설계하는지 정리합니다.

마지막 수정 2026년 4월 2일

빠른 비교

dockerfile

HEALTHCHECK --interval=30s --timeout=3s --retries=3 --start-period=10s \
  CMD curl -f http://localhost:3000/health || exit 1

bash

# 헬스 상태 확인
docker inspect --format='{{.State.Health.Status}}' my-app

갈리는 기준

어떤 readiness 판단 흐름을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
프로세스가 떴는지와 준비 완료를 구분	`running` vs `healthy`
초기화 시간이 긴 앱	`start-period` 조정
DB나 의존 서비스 준비 후 앱 시작	`depends_on: condition: service_healthy`
단순 포트 열림이 아니라 앱 상태 확인	HTTP/앱 레벨 health endpoint

running 상태와 healthy 상태가 왜 다른가

컨테이너가 running 상태여도 앱이 요청을 받을 준비가 됐다는 보장은 없다. 프로세스는 시작됐지만 DB 연결을 맺는 중이거나, 캐시를 로딩하는 중일 수 있다. HEALTHCHECK는 주기적으로 검사 명령을 실행해 healthy / unhealthy 상태를 별도로 추적한다.

bash

# 상태 전이 흐름
# starting → healthy  (start-period 후 retries 이내 성공)
# starting → unhealthy (retries 초과 실패)
# healthy  → unhealthy (이후 검사에서 retries 초과 실패)
docker inspect --format='{{json .State.Health}}' my-app

interval, timeout, retries, start-period 파라미터가 결정하는 것

각 파라미터는 검사의 타이밍과 내성(tolerance)을 조정한다. interval은 검사 주기, timeout은 검사 명령 최대 허용 시간, retries는 unhealthy로 전환하기까지 실패 허용 횟수, start-period는 컨테이너 시작 직후 실패를 카운트하지 않는 유예 시간이다.

dockerfile

HEALTHCHECK \
  --interval=15s \      # 15초마다 검사
  --timeout=5s \        # 검사가 5초 초과하면 실패로 간주
  --retries=5 \         # 5회 연속 실패해야 unhealthy 전환
  --start-period=30s \  # 시작 후 30초간 실패는 카운트 안 함
  CMD wget -qO- http://localhost:8080/ready || exit 1

Compose의 depends_on: condition: service_healthy와 연동하는 방법

Compose에서 의존 서비스가 healthy 상태가 된 뒤에 다른 서비스를 시작하고 싶을 때 사용한다. depends_on만 쓰면 컨테이너 시작 순서만 보장하고 준비 여부는 무시한다. condition: service_healthy를 추가해야 실제로 준비된 뒤 다음 서비스가 올라온다.

yaml

services:
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy   # db가 healthy 상태가 된 후 시작

포트 열림 검사와 앱 레벨 readiness 검사는 의미가 다르다

TCP 포트가 열려 있다는 것은 프로세스가 리슨 중이라는 뜻일 뿐이고, 실제로 앱이 DB 연결이나 캐시 초기화를 끝냈다는 뜻은 아닙니다. 운영 카드에서는 nc -z localhost 3000 같은 단순 포트 검사보다 /health, pg_isready, redis-cli ping처럼 앱 또는 의존 서비스 의미를 반영하는 검사가 더 신뢰할 만합니다.

체크포인트

상황	적합한 선택
앱 초기화 시간이 긴 서비스	`--start-period`를 충분히 설정
의존 서비스 준비 후 시작 보장	`depends_on: condition: service_healthy`
검사 명령이 무거울 때	`--interval` 늘려 검사 빈도 줄이기
DB readiness 확인	`pg_isready`, `mysqladmin ping` 사용
HTTP 서비스 readiness 확인	`/health` 엔드포인트에 `curl -f`

주의할 점

포트 열림 여부만 검사하는 헬스체크는 앱이 실제로 준비되지 않았는데도 healthy로 보고한다. curl -f http://localhost/health처럼 애플리케이션 레벨에서 응답하는 엔드포인트를 대상으로 해야 DB 연결, 초기화 완료 여부까지 함께 반영할 수 있다.

dockerfile

HEALTHCHECK CMD nc -z localhost 3000 || exit 1

# 포트는 열렸지만 앱이 아직 마이그레이션 중이면
# healthy로 오판할 수 있음

참고 링크

2 sources

Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

Docker운영과 디버깅

healthcheck와 container readiness

컨테이너가 단순히 떠 있는 상태와 실제로 요청을 받을 준비가 된 상태가 왜 다른지, healthcheck를 어떤 기준으로 설계하는지 정리합니다.

마지막 수정 2026년 4월 2일

빠른 비교

dockerfile

HEALTHCHECK --interval=30s --timeout=3s --retries=3 --start-period=10s \
  CMD curl -f http://localhost:3000/health || exit 1

bash

# 헬스 상태 확인
docker inspect --format='{{.State.Health.Status}}' my-app

갈리는 기준

어떤 readiness 판단 흐름을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
프로세스가 떴는지와 준비 완료를 구분	`running` vs `healthy`
초기화 시간이 긴 앱	`start-period` 조정
DB나 의존 서비스 준비 후 앱 시작	`depends_on: condition: service_healthy`
단순 포트 열림이 아니라 앱 상태 확인	HTTP/앱 레벨 health endpoint

running 상태와 healthy 상태가 왜 다른가

bash

# 상태 전이 흐름
# starting → healthy  (start-period 후 retries 이내 성공)
# starting → unhealthy (retries 초과 실패)
# healthy  → unhealthy (이후 검사에서 retries 초과 실패)
docker inspect --format='{{json .State.Health}}' my-app

interval, timeout, retries, start-period 파라미터가 결정하는 것

dockerfile

HEALTHCHECK \
  --interval=15s \      # 15초마다 검사
  --timeout=5s \        # 검사가 5초 초과하면 실패로 간주
  --retries=5 \         # 5회 연속 실패해야 unhealthy 전환
  --start-period=30s \  # 시작 후 30초간 실패는 카운트 안 함
  CMD wget -qO- http://localhost:8080/ready || exit 1

Compose의 depends_on: condition: service_healthy와 연동하는 방법

yaml

services:
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy   # db가 healthy 상태가 된 후 시작

포트 열림 검사와 앱 레벨 readiness 검사는 의미가 다르다

체크포인트

상황	적합한 선택
앱 초기화 시간이 긴 서비스	`--start-period`를 충분히 설정
의존 서비스 준비 후 시작 보장	`depends_on: condition: service_healthy`
검사 명령이 무거울 때	`--interval` 늘려 검사 빈도 줄이기
DB readiness 확인	`pg_isready`, `mysqladmin ping` 사용
HTTP 서비스 readiness 확인	`/health` 엔드포인트에 `curl -f`

주의할 점

dockerfile

HEALTHCHECK CMD nc -z localhost 3000 || exit 1

# 포트는 열렸지만 앱이 아직 마이그레이션 중이면
# healthy로 오판할 수 있음

참고 링크

2 sources