Docker - Healthcheck, Liveness, Readiness

세 가지를 명확히 구분하자.

• 컨테이너가 살아있는 상태
• 컨테이너가 트래픽을 받을 수 있는 상태
• Docker와 Kubernetes가 이걸 어떻게 다르게 다루는지

---

한 줄 요약

Docker의 healthy는 readiness가 아니다.
의미상으로는 liveness에 가깝다.

---

Docker healthcheck 실습에서 무슨 일이 있었나

다음과 같은 Docker healthcheck를 설정했다.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 5s
  timeout: 2s
  retries: 3

처음에는 /health 경로가 없어서 컨테이너 상태가 unhealthy였다.

이후 컨테이너 안에서 다음 작업을 했다.

echo "ok" > /usr/share/nginx/html/health

그러자 상태가 healthy로 바뀌었다.

---

왜 healthy로 바뀌었을까?

nginx의 기본 설정에서

• 웹 루트(web root)는 /usr/share/nginx/html
• /health 요청은 이 디렉터리 안의 health 파일을 찾는다

즉,

• /health 파일이 없을 때 → 404 → curl -f 실패
• /health 파일이 생기면 → 200 → curl -f 성공

Docker는 HTTP 응답 내용은 보지 않고,
헬스체크 명령의 exit code만 판단한다.

그래서:

• curl -f 성공(exit code 0)
  → Docker는 컨테이너를 healthy로 표시한다.

---

그럼 이 healthy는 liveness일까, readiness일까?

결론부터 말하면

Docker의 healthcheck는 liveness/readiness를 구분하지 않는다.

Docker에는 개념이 하나뿐이다.

Docker
 └─ healthcheck

반면 Kubernetes에는 명확히 나뉜다.

Kubernetes
 ├─ livenessProbe   (살아있나?)
 └─ readinessProbe  (트래픽 받아도 되나?)

---

방금 실습을 실무 개념으로 해석하면

• /health는 항상 200을 반환
• DB, 외부 API, 네트워크 상태는 보지 않음
• 실패하면 컨테이너를 재시작해도 문제 없음

따라서 이 헬스체크는 의미상으로:

“컨테이너(프로세스)가 살아있다”를 확인하는 liveness 성격

이라고 보는 게 맞다.

---

Docker에는 readiness가 없다

이게 오늘 가장 크게 정리된 포인트다.

Docker 단독 환경

• Docker는 컨테이너 생존만 관리
• 트래픽 제어(readiness)는 관여하지 않음

그래서 실무에서는

• Docker healthcheck → liveness 용
• readiness는:
  • Reverse Proxy (nginx, ALB, Traefik 등)
  • Kubernetes Service / readinessProbe
    가 담당한다.

---

실무에서의 기준 정리

Liveness (살아있나?)

• 가장 얕은 경로
• 의존성(DB, 외부 API) ❌
• 실패하면 재시작해도 되는 조건

예:

• /healthz
• /actuator/health/liveness

Readiness (받아도 되나?)

• DB 연결 상태
• 초기화 완료 여부
• 캐시 워밍 상태 등

실패해도:

• 컨테이너는 유지
• 트래픽만 제외

---

오늘의 결론

Docker의 healthy는
“트래픽을 받을 수 있음”이 아니라
“프로세스가 살아 있음”에 대한 신호다.

그리고 readiness는
Docker가 아니라 트래픽을 제어하는 쪽에서 판단한다.

---

마무리 한 줄

Docker/Kubernetes 헬스체크는
상태를 나누는 개념부터 정확히 이해해야 헷갈리지 않는다.