TIL

Container Lifecycle Hooks

• 공식 문서 - Container Lifecycle Hooks
• kubelet이 관리하는 컨테이너가 lifecycle 이벤트에 맞춰 핸들러 코드를 실행할 수 있게 해주는 framework
• Pod 정의에서 spec.containers[].lifecycle 아래 선언

Hook 종류

• 컨테이너에 노출되는 hook은 postStart와 preStop 두 가지. StopSignal은 같은 lifecycle 블록에서 함께 설정되는 부가 항목

Hook	시점	동작 특성
postStart	컨테이너 생성 직후	ENTRYPOINT와 동시(concurrent) 실행 — hook이 메인 프로세스 시작 전·중·후 어디서든 돌 수 있음
preStop	API 요청·probe 실패·preemption 등으로 종료 직전	컨테이너가 이미 종료된 상태면 호출되지 않음. hook 완료 후에야 TERM 전송

postStart

• 핸들러가 완료될 때까지 컨테이너의 Running 전환을 지연시킬 수 있음 — 너무 오래 걸리거나 hang하면 컨테이너가 영영 Running으로 못 감
• ENTRYPOINT와 동시 시작이므로 컨테이너 프로세스가 아직 listen하기 전일 수 있음 → httpGet 핸들러는 부적합한 경우 많음
• 핸들러에는 파라미터가 전달되지 않음

preStop

• terminationGracePeriodSeconds 카운트다운이 hook 실행 전에 이미 시작됨 → hook 시간 + 컨테이너 종료 시간이 grace period 안에 들어가야 함
• 예시 — terminationGracePeriodSeconds: 60, hook 55초 소요, 컨테이너 종료 10초 소요라면 총 65초가 필요하지만 60초에 강제 kill → 컨테이너가 정상 종료 못함
• hook이 hang하면 — Pod phase가 Terminating 상태로 머무르다 grace period 만료 후 kill됨
• 핸들러에는 파라미터가 전달되지 않음

StopSignal

• 컨테이너 종료 시 보낼 시그널을 명시적으로 지정 — 이미지의 STOPSIGNAL 지시어를 override
• 자세한 동작은 Pod Lifecycle - Stop Signals 참고

Hook handler 종류

핸들러	실행 위치	용도
exec	컨테이너 안	컨테이너의 cgroup·namespace 안에서 명령 실행. 사용 리소스가 컨테이너에 카운트됨
httpGet	kubelet	컨테이너의 지정 엔드포인트에 HTTP 요청. 컨테이너 프로세스가 아직 listen 중이 아닐 수 있어 postStart엔 비권장
sleep	kubelet	지정 시간 동안 컨테이너 일시 정지. preStop에서 drain 대기에 유용

• tcpSocket은 deprecated
• exec을 제외한 나머지는 kubelet 프로세스가 직접 실행 — 핸들러 자체가 죽어도 컨테이너 리소스에 영향 없음

lifecycle:
  postStart:
    exec:
      command: ["/bin/sh", "-c", "echo started > /tmp/ready"]
  preStop:
    httpGet:                  # 또는 sleep: { seconds: 10 }
      path: /shutdown
      port: 8080

실행 동작

• postStart 실패 — 컨테이너 kill → restartPolicy에 따라 재시작. 이때 FailedPostStartHook event 발생
• preStop 실패 — 마찬가지로 컨테이너 kill (FailedPreStopHook event)
• 핸들러는 가능한 짧고 가볍게 — 단, 상태 저장처럼 긴 작업이 필요한 경우는 예외

전달 보장

• at least once — 같은 이벤트에 대해 hook이 여러 번 호출될 수 있음. 핸들러는 멱등(idempotent)하게 구현 필요
• 일반적으로는 한 번만 전달. 드물게 kubelet 재시작 중간에 끊기면 재시도 시 중복 전달 가능
• HTTP 수신 측이 down이라면 별도 재시도는 없음

디버깅

• 핸들러의 stdout/stderr 로그는 Pod event에 노출되지 않음
• 실패하면 Pod에 event broadcast — FailedPostStartHook 또는 FailedPreStopHook
• kubectl describe pod <name>의 Events 섹션에서 확인