F1 레이스에서 이런 상황을 상상해보자. 레이스카가 트랙을 달리는 동안, 레이스 컨트롤 센터에서는 모든 차량의 상태를 실시간으로 모니터링하고 있다. 엔진 온도, 타이어 압력, 연료량. 이 신호들은 특정 팀의 텐트가 아니라 레이스 전체를 관장하는 컨트롤 타워에서 수집된다. 팀이 피트 전략을 바꾸거나 드라이버가 교체되더라도, 모니터링은 끊기지 않는다.
F1 레이싱 Engineering 사례는 설명을 위해 구성한 가상의 시나리오다.
실제 특정 팀이나 드라이버의 데이터를 기반으로 한 것이 아님을 밝혀 둔다.
Django health 설정에서 path('health/', ...)가 정확히 이 역할을 한다. 처음 deployment.yml에서 /health 경로를 봤을 때 그냥 테스트용 URL인 줄 알았다. 그런데 이 엔드포인트가 왜 존재하는지, 왜 하필 main에 위치해야 하는지 이해하고 나서 생각이 바뀌었다. 단순한 설정이 아니라 서버 운영의 핵심 기반이었다.
Django health 엔드포인트란 무엇인가
/health 엔드포인트는 한 문장으로 정의하면 이렇다.
“서버야, 지금 살아있어?”라는 질문에 자동으로 대답하는 URL
이 URL을 직접 브라우저에서 열어볼 일은 거의 없다. 호출하는 주체는 사람이 아니라 배포 인프라다.
| 호출 주체 | 호출 방식 | 판단 기준 |
|---|---|---|
| Railway, Render, AWS ECS | 30초~1분마다 GET 요청 | 200 OK → 정상 ✅ |
| Kubernetes (k8s) | liveness/readiness probe | 응답 없음 → 컨테이너 재시작 🔄 |
| Nginx / 로드밸런서 | 라우팅 전 체크 | 500 응답 → 해당 인스턴스 제외 ❌ |
deployment.yml에 /health 경로가 명시된 이유가 바로 이것이다. 플랫폼이 주기적으로 이 URL에 요청을 보내고, Django가 200 OK를 반환하면 “정상 운영 중”으로 판단한다. 응답이 없거나 에러가 오면 자동으로 재시작하거나 트래픽을 다른 인스턴스로 돌린다.
Django health 뷰 자체는 단순하다.
from django.http import JsonResponse
def health_check(request):
return JsonResponse({"status": "ok"})
복잡한 로직이 없다. 서버가 요청을 받아서 응답할 수 있는 상태인지만 확인하면 된다.
왜 web 앱이 아닌 main urls.py에 두는가
처음에 가장 의아했던 부분이다. 기능을 담당하는 web 앱 안에 view와 url을 만들어두면 안 되는 걸까?
결론부터 말하면, Django health 엔드포인트는 특정 기능의 일부가 아니라 프로젝트 전체의 인프라 기능이기 때문이다.
| 비교 항목 | web 앱에 배치할 때 | main urls.py에 배치할 때 |
|---|---|---|
| 성격 | “웹 기능 중 하나”처럼 보임 | “프로젝트 공통 인프라” |
| web 앱 리팩토링 시 | 헬스체크가 같이 깨질 수 있음 ❌ | 헬스체크는 독립 유지 ✅ |
| 앱 삭제/분리 시 | 404 발생 가능 ❌ | 영향 없음 ✅ |
| 책임 소재 | 불명확 | 명확 (프로젝트 레벨) |
실제 urls.py 구조로 보면 차이가 더 명확하다.
# ❌ 이전: web/urls.py 안에 헬스체크
# web 앱이 settings에서 제거되거나 구조 변경 시 /health도 404
# ✅ 이후: main/urls.py (프로젝트 루트 URL 설정)
from health.views import health_check
urlpatterns = [
path('health/', health_check), # 인프라 레벨, 최상위에 고정
path('admin/', admin.site.urls),
path('', include('web.urls')), # 기능 앱은 include로 연결
]
web 앱을 나중에 frontend로 이름을 바꾸거나, 앱을 분리하거나, 삭제하더라도 Django health 엔드포인트는 영향을 받지 않는다.
Django health를 main에 두면 생기는 3가지 이점
첫째, 서버 재시작 루프를 막는다.
배포 플랫폼이 /health 응답을 받지 못하면 서버를 무한 재시작할 수 있다. Django health 엔드포인트가 web 앱 안에 있고 그 앱에 문제가 생겼을 때 /health까지 같이 죽으면, 플랫폼은 계속 재시작을 시도한다. main에 독립적으로 두면 이런 연쇄 장애를 줄일 수 있다.
둘째, 앱 구조 변경에 자유롭다.
Django 프로젝트는 성장하면서 앱 구조가 계속 바뀐다. web 앱이 api, frontend, core 등으로 분리될 수 있다. Django health가 특정 앱에 종속되어 있으면 구조 변경 때마다 이 경로도 함께 점검해야 한다. main에 두면 앱 구조와 무관하게 항상 동일 위치에 존재한다.
셋째, 책임 분리 원칙을 지킨다.
소프트웨어 설계의 기본 원칙 중 하나는 관심사 분리(Separation of Concerns)다. Django health는 비즈니스 로직이 아니라 운영 인프라 관심사다. web 앱은 웹 기능에 집중하고, 인프라 관련 설정은 프로젝트 루트(main)에서 관리하는 것이 자연스러운 구조다.
엔지니어 시각으로 보면 더 직관적이다
제조 자동화 라인에서 장비 상태를 모니터링하는 시스템을 떠올려보자.
각 장비 유닛마다 독립된 상태 신호를 외부 모니터링 시스템으로 전송한다. 이 신호는 특정 공정 레시피가 실행 중인지 여부와 관계없이 항상 살아있어야 한다. 공정이 바뀌거나 레시피가 교체되더라도, 장비 자체가 “살아있음”을 알리는 heartbeat 신호는 독립적으로 유지된다.
path('health/', ...)가 정확히 이 heartbeat 신호다. 비즈니스 로직(web 앱)이 어떻게 바뀌든, 서버가 살아있다는 Django health 신호는 끊기지 않아야 한다. 그래서 main에 둔다.
핵심 요약
- Django health 엔드포인트는 배포 인프라가 서버 생존 여부를 주기적으로 확인하는 URL이다
- 호출 주체는 사람이 아닌 Railway·Kubernetes·로드밸런서 등 배포 플랫폼이다
- 특정 기능 앱(web)이 아닌 프로젝트 루트 urls.py(main)에 배치해야 앱 구조 변경에 독립적으로 유지된다
- main에 두는 이유 3가지: 재시작 루프 방지, 앱 구조 변경 자유, 책임 분리 원칙
[링크 제안]
Django health 설정을 이해했다면, 요청이 URL에서 View로 흐르는 전체 Django 구조도 함께 잡아두자.
바이브코딩으로 프로덕션 수준 프로젝트를 진행할 때 헬스체크는 빠질 수 없는 구성 요소다.
토니 스타크의 garage에서 Agentic Engineering을 읽다
