TIL

Pod

• 공식 문서 - Pod Lifecycle
• Pod은 정의된 lifecycle을 따르는 일회성 객체 — Pending → Running → Succeeded 또는 Failed
• 한 번 스케줄되면 종료될 때까지 같은 노드에 머무름 — 재스케줄링 없음
• 일부 자원(volume, IP)은 Pod의 UID와 lifetime을 공유 — Pod이 사라지면 함께 사라짐
• 노드 장애 시 Pod은 재배치 대신 삭제 후 controller가 새 Pod 생성

Pod phase

• status.phase 필드 — Pod lifecycle의 상위 수준 요약 (5개 값)
• 컨테이너 상태의 정밀한 집합이 아닌 단순 요약 — 상세는 container state·conditions 참조

Phase	의미
Pending	클러스터에 받아들여졌으나 컨테이너 준비 미완료 (스케줄 대기·이미지 pull 중)
Running	노드에 바인딩되고 모든 컨테이너 생성됨, 최소 하나가 실행/시작/재시작 중
Succeeded	모든 컨테이너가 성공 종료(0), 재시작되지 않음
Failed	모든 컨테이너 종료, 최소 하나가 실패로 종료 (non-zero exit 또는 시스템 종료)
Unknown	노드와 통신 실패로 상태를 알 수 없음

• STATUS 컬럼과 혼동 주의
  • kubectl get pod의 STATUS는 사용자 직관용 표시 값 — CrashLoopBackOff, Terminating 등 phase에 없는 값도 등장
  • phase는 API 데이터 모델의 명시적 필드, STATUS는 보조 표시일 뿐
• 1.27부터 — 삭제된 Pod은 API 서버에서 사라지기 전에 kubelet이 컨테이너 exit code에 따라 Failed 또는 Succeeded 단말 phase로 전환 (static Pod·force delete 제외)
• 노드가 죽으면 그 노드의 모든 Pod은 Failed phase로 설정됨

Container state

• Pod 전체 phase와 별개로 kubelet이 각 컨테이너의 상태를 추적 (3종)
• kubectl describe pod <name>으로 컨테이너별 상태·Reason 확인 가능

State	의미
Waiting	시작에 필요한 작업 진행 중 (이미지 pull, Secret 적용 등). Reason 필드 포함
Running	정상 실행 중. postStart hook이 정의돼 있다면 이미 완료된 시점
Terminated	실행 후 완료 또는 실패. exit code, 시작·종료 시각 포함. preStop hook이 있다면 종료 전 실행됨

restartPolicy

• 컨테이너 종료 시 kubelet의 재시작 정책 — Pod.spec.restartPolicy 필드 (기본값 Always)

정책	종료 후 동작
Always	exit code와 무관하게 항상 재시작
OnFailure	non-zero exit일 때만 재시작
Never	어떤 경우에도 재시작 안 함

• 적용 범위
  • 일반 app container와 일반 init container에 적용
  • Sidecar container는 예외 — initContainers 항목 중 자체 restartPolicy: Always를 가진 컨테이너. Pod-level 정책 무시
• 워크로드별 일반적 선택
  • Deployment — Always (유일하게 허용되는 값)
  • Job — OnFailure 또는 Never

Restart backoff

• 컨테이너가 종료될 때마다 kubelet이 같은 Pod·같은 노드에서 재생성
• 재시작 간격은 지수 backoff — 10s, 20s, 40s, … 최대 300s(5분)에서 캡
• 컨테이너가 10분간 정상 실행되면 backoff 타이머 리셋 — 새 crash는 처음으로 취급
• CrashLoopBackOff — 컨테이너가 반복 실패해 backoff 대기 중인 상태
  • kubectl 표시 값일 뿐 phase는 아님
  • 흔한 원인 — 앱 에러, 환경 변수 누락, 리소스 부족, liveness/startup probe 실패
  • 진단 — kubectl logs <pod>로 로그, kubectl describe pod <pod>로 이벤트·리소스 확인

Pod conditions

• status.conditions 배열 — Pod이 거쳐온(또는 거치지 못한) 단계들. kubelet이 관리
• 각 condition은 type / status(True·False·Unknown) / reason / message / lastTransitionTime 필드를 가짐

Condition	의미
PodScheduled	Pod이 노드에 스케줄됨
PodReadyToStartContainers	샌드박스 생성·네트워크 구성·볼륨 마운트 완료 — 컨테이너 실행 직전 단계
Initialized	모든 init container가 성공 종료
ContainersReady	Pod 안의 모든 컨테이너가 ready 상태
Ready	Pod이 요청을 받을 수 있음 — 매칭되는 Service의 EndpointSlice에 포함됨
DisruptionTarget	preemption·eviction·GC 등으로 곧 종료될 예정

• 대략적 진행 순서 — PodScheduled → PodReadyToStartContainers → Initialized → ContainersReady → Ready
• Ready는 ContainersReady + 모든 readiness gate 조건 충족의 결과 (gate 없으면 ContainersReady와 같음)

Readiness gates

• Pod의 readiness 판단에 앱·운영자가 직접 신호를 주입할 수 있는 메커니즘 — spec.readinessGates에 커스텀 condition 정의
• 컨테이너 내부에서 판단 불가능한 외부 조건(외부 의존성 준비, 데이터 warm-up 등)에 활용

  spec:
    readinessGates:
      - conditionType: "www.example.com/feature-1"   # status.conditions에 이 type이 True여야 Ready
  

• gate 값 설정 — kubectl patch로는 status 변경 불가. operator/앱이 PATCH API로 status.conditions에 직접 set
• Ready 판정 — 모든 컨테이너 ready AND 모든 readiness gate가 True

Container probes

• kubelet이 컨테이너에 대해 주기적으로 수행하는 진단(diagnostic) — 코드 실행 또는 네트워크 요청
• 앱이 살아있는지, 트래픽을 받을 준비가 됐는지를 외부에서 확인

Probe 메커니즘 (4종)

• 각 probe는 아래 중 정확히 하나만 정의

메커니즘	동작	성공 조건
exec	컨테이너 안에서 명령 실행	exit code 0
grpc	gRPC health check (grpc.health.v1.Health)	응답 status가 SERVING
httpGet	Pod IP의 지정 포트·경로로 HTTP GET	status code 200 ~ 399
tcpSocket	Pod IP의 지정 포트로 TCP 연결 시도	포트가 열려 있음

• exec은 매번 프로세스 fork — Pod 밀집도 높은 노드·짧은 periodSeconds에서 CPU 부하. 다른 방식 우선 고려
• probe 결과는 Success / Failure / Unknown 세 가지 (Unknown은 kubelet이 재시도)

Probe 종류 (3종)

종류	용도	실패 시 동작
livenessProbe	컨테이너가 살아있는지	컨테이너 kill → restartPolicy 따라 재시작
readinessProbe	트래픽을 받을 준비가 됐는지	Pod IP를 모든 매칭 Service의 EndpointSlice에서 제거 (트래픽 차단)
startupProbe	초기 부팅이 완료됐는지	컨테이너 kill → restartPolicy 따라 재시작

• probe 미정의 시 기본 상태는 모두 Success (단 readinessProbe는 초기 delay 전엔 Failure)
• startupProbe가 정의되면 — 성공할 때까지 liveness/readiness probe는 비활성 → 부팅이 긴 앱이 liveness 실패로 죽는 걸 방지

사용 기준

• livenessProbe — 앱이 데드락 등으로 스스로 죽지 못할 때 필요. 앱이 알아서 crash로 종료한다면 restartPolicy만으로 충분
• readinessProbe — 트래픽 받을 준비를 별도 검증할 때. liveness와 다른 endpoint로 분리하면 self-drain(점검 모드) 가능
• startupProbe — 초기 로딩이 긴 앱(큰 데이터, migration 등). liveness의 initialDelaySeconds를 키우는 대신 분리하면 운영 단순화

Pod termination

• Pod 삭제 요청 시 — 클러스터가 graceful shutdown을 시도. 앱 프로세스가 정리할 시간을 줌
• 기본 grace period — 30초. Pod.spec.terminationGracePeriodSeconds로 변경 가능
• 사용 시그널 — 기본 SIGTERM (이미지의 STOPSIGNAL 지시어로 override 가능)

Termination flow

• kubectl delete pod 또는 controller에 의한 교체 시 진행되는 단계
  1. API Server가 Pod에 deletion timestamp 기록 — kubectl get에 Terminating 표시
     • 동시에 control plane이 매칭 Service의 EndpointSlice에서 해당 endpoint를 ready: false 로 변경 → 신규 트래픽 차단
  2. kubelet이 종료 절차 시작 — preStop hook이 정의돼 있으면 컨테이너 안에서 먼저 실행
  3. SIGTERM 전송 — container runtime이 컨테이너 PID 1에 시그널 전달
     • sidecar 없는 경우 컨테이너 간 종료 순서 보장 X
  4. grace period 동안 대기 — 앱이 connection drain·flush 등 정리 수행
  5. 강제 종료 — grace period 만료 시 남은 프로세스에 SIGKILL. 단말 phase(Failed/Succeeded) 전환 후 API에서 Pod 제거
• preStop hook이 grace period보다 길어지면 — 2초 grace extension만 추가됨. 그래도 부족하면 terminationGracePeriodSeconds를 늘려야 함

Forced termination

• kubectl delete pod <name> --grace-period=0 --force — graceful 단계 생략하고 즉시 삭제
• 동작
  • API Server가 즉시 Pod 객체 삭제 — kubelet의 종료 확인을 기다리지 않음
  • 노드 위 컨테이너는 잠시 살아있을 수 있음 → 리소스 leak 가능
• 사용 시점 — 노드가 unreachable이거나 kubelet 응답 없을 때만. 일반 삭제엔 사용 금지

Sidecar container 종료 순서

• Sidecar(initContainers 중 restartPolicy: Always)가 있으면 — 메인 컨테이너가 모두 종료된 후에야 kubelet이 sidecar에 TERM 전송
• sidecar 간 종료 순서 — Pod spec에 정의된 순서의 역순
• 메인 종료가 느리면 sidecar 종료도 함께 늦어짐 → grace period 만료 시 모두 동시에 강제 종료
• 과거 preStop hook으로 종료 순서를 제어하던 패턴은 sidecar로 대체 가능

Pod Garbage Collection

• 종료된 Pod의 API 객체는 자동으로 사라지지 않음 — 사람·controller가 명시적으로 삭제해야 함
• PodGC (kube-controller-manager 내부 controller) — 다음 Pod를 자동 정리
  • 단말 phase(Succeeded/Failed) Pod 수가 임계값(terminated-pod-gc-threshold) 초과 시
  • orphan Pod — 이미 사라진 노드에 바인딩된 Pod
  • unscheduled terminating Pod — 스케줄되지 않은 채 종료 중인 Pod
  • out-of-service 노드의 terminating Pod — node.kubernetes.io/out-of-service taint가 붙은 not-ready 노드의 Pod
• 정리 대상이 단말 phase가 아니면 — PodGC가 Failed로 마킹한 뒤 삭제