필수 readiness와 선택 capability를 분리하기

프로세스가 살아 있다는 사실, 핵심 검색 요청을 처리할 준비가 됐다는 사실, 선택 기능이 모두 정상이라는 사실은 서로 다릅니다. 하나의 ready 값에 전부 넣으면 선택 모델 장애가 전체 재시작으로 이어지고, 핵심 DB 장애를 liveness가 가립니다.

세 가지 상태

• liveness: 프로세스가 요청을 받을 수 있는가
• readiness: 제품의 필수 경로를 안전하게 처리할 수 있는가
• capability: 특정 DB·모델·push·scheduler 기능이 현재 동작하는가

Python 검색 backend의 /health/ready는 검색에 필수인 DB와 임베딩 두 게이트만 판정합니다. /health/capabilities는 도메인별 DB, 텍스트·Vision 모델, push, scheduler를 독립 항목으로 확인합니다. 선택 항목이 내려가도 필수 게이트가 살아 있으면 HTTP 200과 degraded: true를 반환합니다.

응답을 안전하게 만들기

상태 응답에는 ok, reachable, configured, model_loaded, running, job_count처럼 운영 판단에 필요한 최소 필드만 둡니다. DSN, 내부 endpoint, token, provider 오류 본문과 사용자 원문은 health 응답에 넣지 않습니다. 느린 DB·모델 probe는 thread pool과 timeout으로 감싸 이벤트 루프를 막지 않게 합니다.

운영자와 사용자에게 주는 의미

운영자는 not_ready이면 필수 검색 경로를 복구하고, ready + degraded이면 영향을 받는 선택 기능만 확인할 수 있습니다. 사용자 화면은 모든 capability가 정상인지 기다리기보다 실제 요청이 사용하는 기능의 오류·재시도·대체 행동을 보여줘야 합니다. 상태 숫자 하나를 제품 성공으로 해석하지 않고, 기능별 영향 범위와 복구 주체를 함께 기록합니다.

관련 강좌: Compose·Readiness·Reverse Proxy·Rollback 운영하기