llm-wiki/raw/official-docs/spring-boot-graceful-shutdown-reference.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
Spring Boot Graceful Shutdown — Official Reference	official-doc	https://docs.spring.io/spring-boot/reference/web/graceful-shutdown.html		feature-background-job-async-contract	ca-skeleton	official-doc ca-skeleton runtime spring-boot	2026-06-11

Spring Boot Graceful Shutdown — Official Reference

Layer: raw/official-docs/ — Spring Boot 공식 레퍼런스의 Graceful Shutdown 페이지 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-background-job-async-contract	D8 — server.shutdown=graceful 의 lifecycle 순서(SmartLifecycle earliest phase 에서 신규 요청 차단) + spring.lifecycle.timeout-per-shutdown-phase(기본 30s) — executor await 가 이 phase timeout 이하여야 하는 근거.

출처 / Source

• 원본 URL: https://docs.spring.io/spring-boot/reference/web/graceful-shutdown.html
• 아카이브 URL: (미등록)
• 저자 / 조직: Spring / VMware (Broadcom)
• 발행일: Spring Boot 3.x / 4.x 공식 레퍼런스 (버전 비고정 permalink)
• 마지막 확인일: 2026-06-11

왜 저장했는지 / Why archived

feature-background-job-async-contract 의 D8(graceful shutdown executor await 한계 설정)은 Spring Boot 가 SmartLifecycle earliest phase 에서 신규 요청을 차단하고, spring.lifecycle.timeout-per-shutdown-phase 가 그 phase 의 최대 대기 시간을 결정한다는 공식 근거가 필요하다. executor awaitTermination 이 이 timeout 이하여야 한다는 설계 제약의 공식 출처로 보관한다.

핵심 인용 / Key quotes (verbatim)

[§Graceful Shutdown — 첫 단락] "Graceful shutdown is enabled by default with all three embedded web servers (Jetty, Reactor Netty, and Tomcat) and with both reactive and servlet-based web applications. It occurs as part of closing the application context and is performed in the earliest phase of stopping SmartLifecycle beans. This stop processing uses a timeout which provides a grace period during which existing requests will be allowed to complete but no new requests will be permitted."

[§Graceful Shutdown — 첫 단락 (연속)] "This stop processing uses a timeout which provides a grace period during which existing requests will be allowed to complete but no new requests will be permitted."

[§Configuration] "To configure the timeout period, configure the spring.lifecycle.timeout-per-shutdown-phase property"

[§Rejecting Requests During the Grace Period] "The exact way in which new requests are not permitted varies depending on the web server that is being used. Implementations may stop accepting requests at the network layer, or they may return a response with a specific HTTP status code or HTTP header. The use of persistent connections can also change the way that requests stop being accepted."

[§Rejecting Requests During the Grace Period — 마지막 문장] "Jetty, Reactor Netty, and Tomcat will stop accepting new requests at the network layer."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SB-GS-C1	Graceful shutdown 은 Jetty, Reactor Netty, Tomcat 세 embedded web server 모두에서 기본 활성화되며, reactive / servlet 모두 지원한다	[§첫 단락] "Graceful shutdown is enabled by default with all three embedded web servers (Jetty, Reactor Netty, and Tomcat) and with both reactive and servlet-based web applications."	official-vendor-doc	Spring Boot 3.x 이상, 위 세 web server 사용 시	커스텀 embedded server(Undertow 등) 또는 server.shutdown=immediate 설정 시의 동작
SB-GS-C2	Graceful shutdown 은 ApplicationContext 가 닫히는 과정의 일부로 수행되며, SmartLifecycle bean 을 정지하는 가장 이른 phase(earliest phase)에서 실행된다	[§첫 단락] "It occurs as part of closing the application context and is performed in the earliest phase of stopping SmartLifecycle beans."	official-vendor-doc	Spring Boot 3.x 이상	정확한 phase 번호(Integer.MIN_VALUE 등 내부 상수)는 이 페이지에서 명시하지 않음
SB-GS-C3	grace period 동안 기존 요청은 완료가 허용되고 신규 요청은 허용되지 않는다	[§첫 단락] "existing requests will be allowed to complete but no new requests will be permitted."	official-vendor-doc	SmartLifecycle phase timeout 내 in-flight 요청에 한함	timeout 초과 후 in-flight 요청의 강제 종료 여부는 이 페이지에서 다루지 않음
SB-GS-C4	grace period timeout 은 spring.lifecycle.timeout-per-shutdown-phase 프로퍼티로 설정하며, 예시 값은 20s 이다 (기본값은 이 페이지에서 명시하지 않음)	[§Configuration] "To configure the timeout period, configure the spring.lifecycle.timeout-per-shutdown-phase property" / 예시: spring.lifecycle.timeout-per-shutdown-phase=20s	official-vendor-doc	Spring Boot spring.lifecycle.* 프로퍼티 바인딩 사용 시	기본값이 30s 라는 사실은 이 페이지에서 직접 명시하지 않음(별도 확인 필요)
SB-GS-C5	Jetty, Reactor Netty, Tomcat 은 grace period 중 신규 요청을 네트워크 레이어에서 차단한다	[§Rejecting Requests] "Jetty, Reactor Netty, and Tomcat will stop accepting new requests at the network layer."	official-vendor-doc	위 세 web server 사용 시	다른 구현체 또는 persistent connection 의 처리 방식은 web server 마다 상이하다고 명시

Strength 허용값 (참고)

• official-vendor-doc — Spring, Keycloak, AWS, Google 등 공식 벤더 문서

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • SB-GS-C2: SmartLifecycle earliest phase 에서 graceful shutdown 이 수행됨 → executor SmartLifecycle 이 이보다 늦은 phase 에 등록되어야 web layer shutdown 이후 완료 대기가 의미 있음
  • SB-GS-C4: spring.lifecycle.timeout-per-shutdown-phase 프로퍼티가 각 phase 의 최대 대기 시간을 결정함 → executor awaitTermination 값은 이 timeout 이하여야 함
  • SB-GS-C5: Tomcat/Netty/Jetty 는 네트워크 레이어 차단 → HTTP level reject 와 구분
• 이 자료가 증명하지 않는 것:
  • spring.lifecycle.timeout-per-shutdown-phase 의 기본값이 30s 라는 사실 — 이 페이지 본문에 없음. Spring Framework DefaultLifecycleProcessor 소스 또는 별도 reference 확인 필요
  • executor awaitTermination 의 구체적 권장값 (19s 등) — 이 자료는 메커니즘만 설명하며 정량 권고 없음
  • k8s terminationGracePeriodSeconds 와의 연동 시간 계산 — 이 페이지 범위 밖
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • spring.lifecycle.timeout-per-shutdown-phase 기본값 30s 의 verbatim 출처 추가 (Spring Framework DefaultLifecycleProcessor Javadoc 또는 Spring Boot 설정 reference)
  • ca-tmpl 의 ThreadPoolTaskExecutor 가 실제로 SmartLifecycle 을 구현하는지 — graceful shutdown phase 에 참여하는지 확인
  • k8s terminationGracePeriodSeconds 공식 doc 인용 추가 — D8 의 "20s container shutdown" 근거를 별도 raw source 로 보강 필요

메모 / Notes

• 이 페이지의 예시(spring.lifecycle.timeout-per-shutdown-phase=20s)는 20s 이지만 기본값은 아님. 기본값 30s 는 DefaultLifecycleProcessor.timeoutPerShutdownPhase 필드에서 유래하며, Spring Boot 공식 reference 의 common-application-properties 페이지에서 별도 확인 권고.
• D8 근거 보강을 위해 k8s terminationGracePeriodSeconds 공식 doc raw source 추가 권고 (현재 D8 = UNSUPPORTED_DECISION 상태).
• server.shutdown=graceful (기본값 확인 필요 — 이 페이지는 "enabled by default" 라고 명시하지 않고 "Disabling Graceful Shutdown" 섹션에서 server.shutdown=immediate 로 비활성화한다고 서술).
  • 주의: 위 인용 SB-GS-C1 은 "enabled by default" 라고 명시함 — 단, server.shutdown property 기본값이 graceful 인지 immediate 인지는 common-application-properties 페이지에서 교차 확인 필요.

Related / 관련

• 같은 주제 다른 official-doc: Spring Framework SmartLifecycle Javadoc, DefaultLifecycleProcessor 소스
• k8s terminationGracePeriodSeconds 공식 doc (별도 raw source 추가 권고)
• 이 자료를 인용한 wiki 요약: [[wiki/concepts/spring-boot-graceful-shutdown]] (생성 시)