llm-wiki/raw/official-docs/kubernetes-pod-lifecycle-termination.md

---
title: "Kubernetes Pod Lifecycle — Termination of Pods"
source_type: official-doc
url: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/
archive_url:
related_branches: [feature-background-job-async-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, runtime, kubernetes, graceful-shutdown, sigterm]
created: 2026-06-11
vendor: "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]]` (생성 시)