Docker 헬스 체크가 실패할 때 확인하는 것

Docker 헬스 체크 문제는 혼자서 개발할수록 확인한 값과 바꾼 값을 정확히 기록해야 한다. 나중에 같은 증상이 나타났을 때 이 기록이 최고의 참고 자료가 된다.

먼저 정상 상태를 정해두기

컨테이너가 정상 작동할 때의 환경변수는 무엇인지, 포트 매핑은 어떻게 되어 있는지, 볼륨 마운트는 어디인지를 정확히 기억해두자. 이것들이 하나라도 틀리면 헬스 체크가 실패해도 실제 서비스는 잘 작동하고 있을 수 있다.

로그를 먼저 확인하는 습관

헬스 체크 실패만 보고 바로 코드를 고치려고 하면 안 된다. 먼저 실제로 컨테이너 안에서 뭐가 작동하고 있는지 로그를 봐야 한다.

# 실행 중인 컨테이너 확인
docker ps

# 마지막 100줄 로그 확인
docker logs --tail=100 container-name

# 실시간 로그 스트리밍 (--follow)
docker logs -f container-name

# 상세 정보 확인 (헬스 상태, 포트, 환경변수 등)
docker inspect container-name

환경변수와 포트 매핑 재확인하기

Dockerfile에서 환경변수를 정의했더라도, 실제 docker run 명령어에서 -e 플래그로 오버라이드되었을 수도 있다. 포트도 마찬가지다. -p 3000:3000으로 매핑해뒀다고 생각해도 실제로는 다른 포트에 매핑되어 있을 수 있다. docker inspect로 실제 상태를 확인하는 게 정확하다.

헬스 체크 명령어 직접 실행해보기

헬스 체크가 실패한다면, 그 헬스 체크 명령어를 직접 컨테이너 안에서 실행해보자. 서비스 자체는 작동하는데 헬스 체크 명령어만 잘못된 경우가 많다.

# 컨테이너 내부 셸 진입
docker exec -it container-name /bin/sh

# 헬스 체크 명령어 직접 실행 (예: curl로 상태 체크)
curl http://localhost:3000/health

이미지 크기가 커지는 문제와 별개로 취급하기

헬스 체크 실패와 이미지 크기 문제는 다른 원인일 수 있다. 이미지가 크다는 건 보통 불필요한 레이어나 빌드 아티팩트가 남아 있다는 뜻이고, 헬스 체크가 실패한다는 건 런타임 환경 설정 문제다. 두 문제를 동시에 해결하려고 하면 혼란만 생긴다.