llm-wiki/vault/20-evidence/official-docs/kubernetes-pod-lifecycle-termination.md

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

title	source_type	url	archive_url	related_branches	related_projects	tags	created	vendor
Kubernetes Pod Lifecycle — Termination of Pods	official-doc	https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/		feature-background-job-async-contract	ca-skeleton	official-doc ca-skeleton runtime kubernetes graceful-shutdown sigterm	2026-06-11	Kubernetes / CNCF

Kubernetes Pod Lifecycle — Termination of Pods

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-background-job-async-contract	D8 — SIGTERM → terminationGracePeriodSeconds(기본 30s) → SIGKILL 강제종료 메커니즘: executor awaitTermination 은 grace period 내부에 들어가야 한다는 근거.

출처 / Source

• 원본 URL: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/
• 아카이브 URL: (미확보)
• 저자 / 조직: Kubernetes / CNCF (공식 문서)
• 발행일: (지속 갱신 — 특정 날짜 없음)
• 마지막 확인일: 2026-06-11

왜 저장했는지 / Why archived

D8 결정(executor awaitTermination ≤ 19s)의 외부 근거 확보를 위해 저장. Kubernetes 공식 문서가 Pod 종료 시 terminationGracePeriodSeconds(기본 30s) 내에서 SIGTERM → awaitTermination → SIGKILL 순서로 진행됨을 명시하므로, executor awaitTermination 이 그 grace period 안쪽에 맞아야 함을 직접 정당화한다.

핵심 인용 / Key quotes (verbatim)

[§Pod Termination Flow, step 2.i] "If one of the Pod's containers has defined a preStop hook and the terminationGracePeriodSeconds in the Pod spec is not set to 0, the kubelet runs that hook inside of the container. The default terminationGracePeriodSeconds setting is 30 seconds."

[§Pod Termination Flow, step 2.ii] "The kubelet triggers the container runtime to send a TERM signal to process 1 inside each container."

[§Pod Termination Flow, step 4.i] "When the grace period expires, if there is still any container running in the Pod, the kubelet triggers forcible shutdown. The container runtime sends SIGKILL to any processes still running in any container in the Pod. The kubelet also cleans up a hidden pause container if that container runtime uses one."

[§Forced Pod termination] "By default, all deletes are graceful within 30 seconds. The kubectl delete command supports the --grace-period=<seconds> option which allows you to override the default and specify your own value."

[§Termination of Pods — opening paragraph] "Typically, with this graceful termination of the pod, kubelet makes requests to the container runtime to attempt to stop the containers in the pod by first sending a TERM (aka. SIGTERM) signal, with a grace period timeout, to the main process in each container. [...] Once the grace period has expired, the KILL signal is sent to any remaining processes, and the Pod is then deleted from the API Server."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
K8S-POD-LC-C1	Pod 종료 시 기본 grace period 는 30초(terminationGracePeriodSeconds default = 30s)이며, preStop hook 실행 후 SIGTERM 이 main process 에 전달된다	[§Pod Termination Flow, step 2.i] "The default terminationGracePeriodSeconds setting is 30 seconds."	official-vendor-doc	Kubernetes Pod에서 실행되는 모든 container	Spring executor의 awaitTermination 기본값이 30s 이내여야 한다는 것을 직접 증명하지는 않음 — grace period 내부에 들어가야 함을 정당화할 뿐
K8S-POD-LC-C2	grace period 만료 시 container runtime 이 SIGKILL 을 아직 실행 중인 모든 프로세스에 전송한다	[§Pod Termination Flow, step 4.i] "When the grace period expires, if there is still any container running in the Pod, the kubelet triggers forcible shutdown. The container runtime sends SIGKILL to any processes still running in any container in the Pod."	official-vendor-doc	Kubernetes kubelet + 모든 container runtime (containerd, CRI-O 등)	JVM process 내부에서 shutdown hook / awaitTermination 이 완전히 종료되지 않은 경우에 일어나는 정확한 JVM 동작은 이 claim 범위 밖
K8S-POD-LC-C3	kubelet 은 container runtime 에 TERM(SIGTERM) 신호를 container process 1 에 전송하도록 요청한다	[§Pod Termination Flow, step 2.ii] "The kubelet triggers the container runtime to send a TERM signal to process 1 inside each container."	official-vendor-doc	모든 Kubernetes Pod container (process 1 이 JVM 인 경우 포함)	container 내부에서 JVM 이 SIGTERM 을 받았을 때 Spring ApplicationContext 가 어떻게 처리하는지 — 그것은 Spring 공식 doc 영역
K8S-POD-LC-C4	preStop hook 이 grace period 만료 후에도 실행 중이면, kubelet 은 2초의 일회성 grace period 연장을 요청한다	[§Pod Termination Flow, step 2.i] "If the preStop hook is still running after the grace period expires, the kubelet requests a small, one-off grace period extension of 2 seconds."	official-vendor-doc	preStop hook 이 설정된 Pod	preStop hook 없이 SIGTERM 직접 수신하는 컨테이너의 동작에는 적용 안 됨
K8S-POD-LC-C5	기본 삭제는 30초 내 graceful 하게 처리된다 (--force + --grace-period=0 없을 시)	[§Forced Pod termination] "By default, all deletes are graceful within 30 seconds."	official-vendor-doc	kubectl delete pod 기본 호출	클러스터·컨트롤러가 Pod 를 직접 삭제하는 경우(eviction, OOM kill 등)의 grace period 동작에 대해서는 추가 확인 필요

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • K8S-POD-LC-C1: Pod terminationGracePeriodSeconds 기본값 = 30s
  • K8S-POD-LC-C2: grace period 초과 시 SIGKILL 강제 전송
  • K8S-POD-LC-C3: kubelet 이 container process 1 에 SIGTERM 전송
  • K8S-POD-LC-C4: preStop hook 초과 시 +2s 연장 (일회성)
  • K8S-POD-LC-C5: 기본 삭제 = 30s graceful
• 이 자료가 증명하지 않는 것:
  • executor awaitTermination 의 정확한 값(예: 19s)이 얼마여야 하는가 — 이 자료는 grace period 안에 들어가야 함만 정당화하고, 구체적 margin(1s)은 구현자 결정(UNSUPPORTED_IMPL_DECISION)
  • Spring ContextClosedEvent → executor shutdown 의 호출 순서와 타이밍 — Spring 공식 doc 별도 확인 필요
  • container 가 terminationGracePeriodSeconds 를 초과하여 실행되다 SIGKILL 받았을 때 JVM in-flight job 의 정확한 처리 결과
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 실제 terminationGracePeriodSeconds 설정값 확인 (기본값 30s 가 오버라이드 됐는지)
  • Spring executor awaitTerminationSeconds 와 ContextClosedEvent 연동 공식 문서 — D8 의 나머지 절반

메모 / Notes

• D8 결정(executor awaitTermination ≤ 19s = 20s − 1s margin)에서 20s 는 ca-tmpl 의 app shutdown timeout 설정으로부터 온 것이지, k8s terminationGracePeriodSeconds (기본 30s) 로부터 직접 오는 것이 아님. 이 자료는 "k8s grace period 이 존재하며 그 내부에서 app 이 종료해야 한다"는 상위 제약을 증명하고, 20s 라는 값은 별도 app-level shutdown 설정 근거 필요.
• preStop hook 을 사용하면 SIGTERM 보다 먼저 실행되므로 graceful drain(연결 종료, queue flush 등)에 활용 가능 — 단, hook 실행 시간도 terminationGracePeriodSeconds 에 포함됨.
• 추가로 봐야 할 동일 출처 페이지: https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/ (preStop hook 설정 예제)

Related / 관련

• 같은 주제 다른 official-doc / company-tech-blog: (미확보 — Spring executor shutdown 공식 doc 추가 권고)
• 이 자료를 인용한 wiki 요약: [[wiki/concepts/kubernetes-pod-termination]] (생성 시)