Spring Boot graceful shutdown 기본 동작과 끄는 법

배포나 재시작할 때 처리 중이던 요청이 중간에 끊기는 걸 막고 싶을 때 보는 설정입니다. 결론부터 말하면 Spring Boot는 graceful shutdown이 기본 활성화라 따로 켤 필요가 없습니다. server.shutdown의 기본값이 graceful이고, 끄고 싶을 때 immediate로 바꾸는 구조입니다.

# 기본값이라 명시 안 해도 동작합니다
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s

# 끄려면
# server.shutdown=immediate

지원 범위는 임베디드 Jetty, Reactor Netty, Tomcat 3종입니다. 유예 시간 동안 이 셋은 네트워크 계층에서 새 요청 수신을 멈추고, 이미 진행 중이던 요청만 끝까지 처리합니다. 유예 시간은 spring.lifecycle.timeout-per-shutdown-phase로 조정하며, 공식 문서 예시는 20s를 씁니다.

graceful shutdown은 애플리케이션 컨텍스트를 닫는 과정에서 동작합니다. 그래서 kill -9(SIGKILL)로 끊으면 적용되지 않고, 유예 시간보다 오래 걸리는 요청도 보장되지 않습니다. 쿠버네티스에 올린다면 파드의 terminationGracePeriodSeconds를 이 timeout보다 길게 잡아줘야 합니다.

🔗 https://docs.spring.io/spring-boot/reference/web/graceful-shutdown.html