목차
헬스체크의 역할과 전제조건
이 글은 Docker와 Docker Compose가 이미 설치되어 있고, 호스트에서 Docker 명령을 실행할 수 있다고 가정합니다. healthcheck는 컨테이너 내부 애플리케이션이 정상 응답하는지 주기적으로 확인하는 기능입니다.
헬스체크가 unhealthy로 판정되어도 Docker Compose가 자동으로 컨테이너를 재시작하지는 않습니다. 상태를 감지한 뒤 별도의 감시 스크립트가 재시작 명령을 실행하도록 구성해야 합니다.
Docker Compose에 healthcheck 추가하기
웹 서비스라면 실제 사용자가 접속하는 주소를 검사하는 것이 좋습니다. 프로세스 실행 여부만 확인하는 것보다 애플리케이션의 응답 상태를 직접 확인할 수 있기 때문입니다.
services:
app:
image: nginx:1.27-alpine
ports:
- "8080:80"
labels:
- "health.autorestart=true"
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 20s
retries 횟수만큼 연속 실패하면 unhealthy로 바뀌므로 일시적인 지연으로 인한 오작동을 줄일 수 있습니다. 예시 이미지 태그는 latest를 사용하지 않았으며, 실행 전에 Docker Hub 등에서 운영에 맞는 안정 태그를 확인하세요.
unhealthy 컨테이너 자동 재시작하기
다음 스크립트는 특정 라벨이 붙은 컨테이너만 감시합니다. Docker 소켓을 직접 사용하므로 감시 스크립트는 컨테이너 내부보다 호스트에서 실행하는 편이 관리와 보안 측면에서 단순합니다.
#!/usr/bin/env bash
set -u
while true; do
for id in $(docker ps -q --filter label=health.autorestart=true); do
status=$(docker inspect --format '{{.State.Health.Status}}' "$id" 2>/dev/null || true)
if [ "$status" = "unhealthy" ]; then
name=$(docker inspect --format '{{.Name}}' "$id" | sed 's#^/##')
echo "$(date '+%F %T') restarting $name"
docker restart "$id"
fi
done
sleep 30
done
파일을 저장한 뒤 실행 권한을 주고 백그라운드에서 실행합니다.
chmod +x health-watch.sh
nohup ./health-watch.sh >> health-watch.log 2>&1 &
docker compose up -d
운영 환경에서는 이 스크립트를 systemd 서비스로 등록해 호스트 재부팅 후에도 자동 실행되도록 구성하는 것이 좋습니다. 재시작만 반복되면 원인 파악이 늦어질 수 있으므로 health-watch.log, 애플리케이션 로그, 재시작 횟수도 함께 확인하세요.
Docker healthcheck는 백업이나 장애 원인 분석 기능이 아니며, 데이터 손상을 막아 주는 장치도 아닙니다. 데이터베이스처럼 재시작에 주의가 필요한 서비스는 먼저 백업과 복구 절차를 준비해야 합니다.
결론
healthcheck는 장애를 감지하고, 감시 스크립트는 재시작을 담당합니다. 두 기능을 분리하면 Docker Compose 환경에서도 장애 대응을 자동화하면서 원인 분석을 위한 로그도 남길 수 있습니다.