Kamal2에서 점검(maintenance) 모드 활용법

Context

기존 시스템에서 점검 작업 시 메인 애플리케이션 서버에서 점검 페이지를 처리해야 했으므로 별도 서버 관리나 로드밸런서 레이어에서의 처리가 필요했다. Kamal2를 사용하는 환경에서는 이러한 복잡성을 프록시 레이어에서 처리할 수 있는 방법이 필요했다.

Technical Solution

• kamal-proxy 레이어에서 maintenance 모드 활성화: kamal app maintenance 명령으로 프록시가 들어오는 요청을 가로채 503 상태코드 반환
• 커스텀 메시지 추가: --message 플래그로 점검 안내 문구를 지정하여 기본 템플릿에 동적 삽입
• 커스텀 503 페이지 구성: config/deploy.yml의 error_pages_path 설정 후 public/proxy/503.html 배포로 프록시에 파일 사전 복사
• Go 템플릿 변수 활용: 커스텀 HTML에 {{ .Message }} 변수를 포함시켜 명령어 실행 시 메시지 동적 렌더링
• Health Check 경로 분리: proxy 설정에서 healthcheck 경로를 /up과 같은 전용 경로로 설정하여 maintenance 모드에서 루트 경로 충돌 방지
• 점검 종료: kamal app live 명령으로 maintenance 모드 해제하여 정상 트래픽 복귀

Key Takeaway

Kamal을 사용하는 환경에서 점검 작업은 프록시 레이어에서 애플리케이션 재시작 없이 처리할 수 있으며, 점검 모드와 애플리케이션 상태를 명확히 분리하고 health check 경로를 별도로 구성하는 것이 의도한 동작을 보장하는 핵심이다.