TIL

Spring Boot — Graceful Shutdown

• 공식 문서 - Graceful Shutdown
• Graceful shutdown = 종료 신호를 받으면 신규 요청은 거부하되 처리 중인(in-flight) 요청은 유예 시간 안에서 마저 끝내고 종료
• Spring Boot 2.3+ 기본 활성. ApplicationContext를 닫을 때 SmartLifecycle 빈 중지의 가장 이른 단계에서 수행
• K8s에서는 [spring-boot-kubernetes-probes]의 shutdown 단계(readiness → REFUSING_TRAFFIC)와 짝을 이루는 실제 트래픽 드레이닝 동작에 해당

동작과 설정

설정 키	기본값	역할
server.shutdown	graceful	graceful = 드레이닝 후 종료 / immediate = 즉시 종료
spring.lifecycle.timeout-per-shutdown-phase	30s	유예 시간 — in-flight 요청을 이 안에서 완료, 초과 시 강제 종료

• 유예 시간 동안 — in-flight 요청은 완료 허용, 신규 요청은 거부
• 임베디드 서버 Tomcat·Jetty·Reactor Netty 지원(servlet·reactive 모두). 신규 요청은 네트워크 레이어에서 수락 중단
• timeout-per-shutdown-phase는 이름대로 phase 단위 타임아웃 — 여러 SmartLifecycle phase 각각에 적용되지만, 웹 앱에서는 사실상 요청 드레이닝 단계의 제한 시간으로 동작
• 주의 — 종료가 SIGTERM으로 전달돼야 graceful이 작동. IDE의 stop 버튼이 SIGTERM을 제대로 안 보내거나 SIGKILL(kill -9)이면 드레이닝 없이 즉시 종료

Kubernetes Pod 종료와 맞물리기

• Pod 삭제 시 동시에 일어나는 일 — (1) Service endpoint에서 제거 시작, (2) preStop 훅 실행, (3) 컨테이너에 SIGTERM 전송 → (4) terminationGracePeriodSeconds 경과 시 SIGKILL
• 즉 K8s가 보낸 SIGTERM이 Spring graceful shutdown을 트리거하는 진입점 (자세한 종료 시퀀스는 [pod])
• 핵심 race — endpoint 제거(라우팅 중단)는 여러 노드로 비동기 전파됨 → SIGTERM 직후에도 잠깐 신규 트래픽이 도착할 수 있고, 이미 드레이닝 모드라 거부당함
• 해법: preStop에 짧은 sleep — endpoint 전파가 끝날 시간을 벌어 준 뒤 SIGTERM이 가도록 지연 ([container-lifecycle-hooks])

# Deployment의 pod spec
terminationGracePeriodSeconds: 45          # SIGKILL까지의 총 예산 (기본 30)
containers:
  - name: app
    lifecycle:
      preStop:
        exec: { command: ["sh", "-c", "sleep 5"] }   # endpoint 제거 전파 대기 (K8s 1.29+는 sleep 액션 네이티브 지원)
# application.yml: server.shutdown=graceful, spring.lifecycle.timeout-per-shutdown-phase=30s

• 시간 예산 부등식 — terminationGracePeriodSeconds ≥ preStop sleep + timeout-per-shutdown-phase (+여유)
  • 어기면 드레이닝 도중 SIGKILL → in-flight 요청 유실. 위 예시는 5 + 30 < 45로 충족
• 노드 [node-pressure-eviction]으로 인한 eviction도 동일한 graceful termination 시퀀스를 거치므로 같은 예산 계산이 적용됨