docker health check

마이크로서비스 환경에서는 수많은 컨테이너가 돌아갑니다.
그런데… "얘 지금 진짜 정상 작동 중인가?" 확인 안 하고 그냥 running 상태만 믿었다가 낭패 보는 경우, 많지 않나요?

그래서 Docker는 healthcheck라는 멋진 기능을 제공합니다.
이걸 설정해두면 컨테이너 내부 서비스의 진짜 상태를 주기적으로 점검하고, healthy / unhealthy 상태를 자동으로 판별해줍니다.

✅ fastapi 서비스에 헬스체크 추가 예시

• FastAPI에 /health 라우트 구현

@app.get("/health")
async def health_check():
    return {"status": "ok"}

• compose file

  fastapi:
    ...
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8899/health"]
      interval: 10s       # 헬스체크를 몇 초마다 반복할지 (기본: 30s)
      timeout: 5s         # 응답을 기다리는 최대 시간
      retries: 3          # 실패 허용 횟수. 이 횟수 넘으면 'unhealthy'로 간주
      start_period: 5s    # 컨테이너 시작 후 헬스체크 시작까지 대기 시간

✅ curl 안 쓸 때는?

보안이나 이미지 최소화 때문에 curl이 없는 경우

 

wget 사용:

test: ["CMD-SHELL", "wget -q --spider http://localhost:8080 || exit 1"] 

 

Python 사용:

test: ["CMD-SHELL", "python3 -c \"import requests; r = requests.get('http://localhost:8080'); exit(0) if r.ok else exit(1)\""] 

※ 단, requests 모듈이 설치되어 있어야 합니다.

docker ps 보면 상태가 아래처럼 나온다:

STATUS: Up 2 minutes (unhealthy)

restart: always와의 연계

이 옵션은 컨테이너가 죽으면 자동으로 재시작하게 해주는 설정

그냥 restart: always만 쓰면

• 컨테이너가 죽으면 재시작
• 근데 서비스 상태가 unhealthy여도 계속 재시작될 수 있음

🌀 Docker Compose의 restart 옵션 종류

옵션설명특징

no (기본값)	컨테이너가 중단돼도 자동 재시작 ❌	개발용에 적합
always	무조건 재시작함 (호스트 재부팅 이후도 포함)	운영 서버에서 자주 씀
on-failure[:<횟수>]	비정상 종료 시에만 재시작. 정상 종료(exit code 0)이면 ❌	exit 1, exit 137 등에만 반응
unless-stopped	always와 비슷하지만, 사용자가 docker stop 하면 그 이후부터는 다시 안켜짐	유지보수 시 유용

restart: no
# 아무것도 안 함 (기본값)

restart: always
# 죽으면 무조건 살아남

restart: on-failure
# 실패했을 때만 재시작

restart: on-failure:3
# 실패했을 때 최대 3번까지만 재시도

restart: unless-stopped
# 항상 재시작하되, 수동으로 멈추면 다시 안 켜짐