Docker Compose 환경에서 Container가 실행 중이라는 것은 서비스가 정상이라는 의미가 아닙니다.
많은 운영 장애는 다음과 같은 형태로 발생합니다.
Container 상태
↓
Running
↓
하지만 Application 오류 발생예:
Web Container 실행
↓
Database 연결 실패
↓
서비스 접속 불가Docker는 기본적으로 Container 프로세스가 살아있는지만 확인합니다.
하지만 실제 서버 운영에서는 다음 상태까지 확인해야 합니다.
- Application 정상 응답 여부
- Database 연결 상태
- Port 응답 여부
- 내부 서비스 상태
- 장애 발생 여부
이때 사용하는 기능이 Docker Compose Healthcheck입니다.
기본 구조:
Container 실행
↓
Healthcheck 실행
↓
서비스 상태 확인
↓
healthy / unhealthy 판단이번 글에서는 Docker Compose Healthcheck 기본 개념부터 설정 방법, Service 의존성 관리, 자동 장애 감지, Production 운영 방법까지 알아보겠습니다.
Docker Compose Healthcheck란 무엇인가?
Healthcheck는 Container 내부 서비스가 정상적으로 동작하는지 자동 확인하는 기능입니다.
기본 Container 상태:
running의미:
프로세스 실행 중하지만:
Application 오류
Database 연결 실패
API 응답 불가상황에서도 running 상태일 수 있습니다.
Healthcheck 적용:
Container 실행
↓
테스트 명령 실행
↓
결과 확인
↓
healthy 상태 표시Docker Compose Healthcheck 상태 종류
Healthcheck 결과는 세 가지 상태로 나뉩니다.
starting
초기 실행 상태
Container 시작
↓
Healthcheck 대기healthy
정상 상태
Healthcheck 성공
↓
서비스 정상unhealthy
문제 상태
Healthcheck 실패
↓
장애 감지Docker Compose Healthcheck 기본 설정
기본 구조:
services:
app:
image: my-app
healthcheck:
test:
- CMD
- curl
- http://localhost:3000
interval: 30s
timeout: 10s
retries: 3설정 항목:
test
실행할 검사 명령
예:
curl localhost:3000의미:
웹 응답 확인interval
검사 주기
예:
30s의미:
30초마다 검사
timeout
최대 대기 시간
예:
10sretries
실패 횟수 기준
예:
33번 실패하면:
unhealthyDocker Compose Web Application Healthcheck 예제
Node.js Application:
services:
app:
image: node-app
ports:
- "3000:3000"
healthcheck:
test:
[
"CMD",
"curl",
"-f",
"http://localhost:3000"
]
interval: 30s
timeout: 5s
retries: 3동작:
30초마다 요청
↓
HTTP 200 확인
↓
healthyDocker Compose Healthcheck 상태 확인
확인:
docker compose ps결과:
app
running (healthy)문제 발생:
app
unhealthy상세 확인:
docker inspect container-name확인:
Health
↓
Status
↓
LogDocker Compose Database Healthcheck 설정
Database도 Healthcheck 설정이 중요합니다.
MySQL 예:
services:
mysql:
image: mysql:8
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost"
]
interval: 10s
timeout: 5s
retries: 5확인:
MySQL 응답 가능 여부 확인Docker Compose depends_on과 Healthcheck 연결
많은 사용자가 depends_on만 사용합니다.
예:
services:
app:
depends_on:
- database문제:
Container 시작 순서만 제어합니다.
구조:
Database Container 시작
↓
Application 시작하지만:
Database 준비 완료 X일 수 있습니다.
Healthcheck 연결:
services:
app:
depends_on:
database:
condition: service_healthy구조:
Database 시작
↓
Healthcheck 확인
↓
healthy
↓
Application 시작Docker Compose Production Healthcheck 구조
운영 환경:
Nginx
↓
Application Container
↓
Healthcheck
↓
Database Container
↓
Healthcheck각 서비스 상태를 확인합니다.
Docker Compose Healthcheck와 자동 복구
Healthcheck는 장애 감지 기능입니다.
하지만 자동 재시작은 Restart Policy가 담당합니다.
구조:
Healthcheck 실패
↓
unhealthy
↓
Restart Policy
↓
Container 재시작설정:
restart: unless-stoppedDocker Compose Healthcheck 주의사항
너무 짧은 검사 주기:
1초마다 검사
↓
불필요한 부하 증가너무 긴 검사 주기:
30분마다 검사
↓
장애 발견 지연일반적인 설정:
Application
30초
Database
10~30초Docker Compose Healthcheck 장애 분석
unhealthy 발생
확인:
docker inspect container-name확인:
- Health Log
- Error 메시지
- 실행 명령
Curl 실패
확인:
curl localhost:portDatabase 연결 실패
확인:
docker compose logs databaseDocker Compose Healthcheck Best Practice
운영 추천:
- 모든 중요 Service 설정
- Database Healthcheck 추가
- Application API Healthcheck 추가
- 적절한 Retry 설정
- Restart Policy 함께 사용
권장 구조:
Container
↓
Healthcheck
↓
Status 확인
↓
자동 복구
↓
서비스 유지자주 묻는 질문
Healthcheck가 Container를 자동 삭제하나요?
아닙니다.
상태를 확인하고 unhealthy 표시를 합니다.
running과 healthy 차이는 무엇인가요?
running은 프로세스 실행 상태이고 healthy는 실제 서비스 응답 상태입니다.
모든 Container에 Healthcheck가 필요한가요?
운영 환경에서는 중요한 Service에 설정하는 것이 좋습니다.
depends_on만 사용하면 안 되나요?
depends_on은 시작 순서만 관리하며 서비스 준비 상태는 확인하지 않습니다.
마무리
Docker Compose Healthcheck는 안정적인 서버 운영을 위한 필수 기능입니다.
Container가 실행 중인지뿐 아니라 실제 서비스가 정상적으로 동작하는지 확인할 수 있습니다.
Production 환경에서는 다음 구조를 권장합니다.
Container 실행
↓
Healthcheck
↓
상태 확인
↓
Restart Policy
↓
자동 복구다음 글에서는 장애 발생 시 빠르게 복구하기 위한 Docker Compose 장애 대응 전략을 알아보겠습니다.