TIL

Spring Boot — Kubernetes Probes

• 공식 문서 - Kubernetes Probes (Actuator)
• 공식 문서 - Application Availability
• Spring Boot는 liveness·readiness 가용성 상태를 내부에서 관리하고, K8s 환경이 감지되면 Actuator가 이를 health group으로 노출 → kubelet의 probe가 호출
• 즉 [liveness-readiness-startup-probes]에서 본 K8s probe의 HTTP 엔드포인트를 Spring이 자동으로 채워주는 셈

Application Availability — liveness / readiness 상태 모델

• Spring Boot가 관리하는 두 가용성 상태. Actuator가 있으면 health group으로 노출되고, 없어도 ApplicationAvailability 빈을 주입해 조회 가능

상태	enum 값	의미	실패 시 K8s 반응
Liveness	CORRECT / BROKEN	앱 내부 상태가 정상 동작 가능한가. BROKEN = 스스로 복구 불가	인스턴스 재시작
Readiness	ACCEPTING_TRAFFIC / REFUSING_TRAFFIC	지금 트래픽을 받을 수 있는가	트래픽 라우팅 중단 (재시작 X)

• Liveness 기준 = Spring ApplicationContext — context refresh가 성공하면 live로 간주
• Readiness 기준 = CommandLineRunner·ApplicationRunner까지 모두 끝나야 ready → 기동 초기화 작업은 @PostConstruct가 아니라 runner에 두라는 권장이 여기서 나옴
• liveness는 외부 시스템 체크에 의존하면 안 됨 — DB·외부 API·캐시 장애가 곧 전체 인스턴스 재시작으로 번져 cascading failure 유발
• readiness에 외부 체크 포함은 신중히 — 모든 인스턴스가 공유하는 외부 시스템이면 차라리 빼고 상위 호출 측 circuit breaker로 처리하는 게 보통

Probe 엔드포인트로 노출

• K8s 환경 감지 시(KUBERNETES_SERVICE_HOST 등 환경변수 자동 감지, 또는 spring.main.cloud-platform=kubernetes로 강제) health group 자동 활성화
  • /actuator/health/liveness ← LivenessStateHealthIndicator
  • /actuator/health/readiness ← ReadinessStateHealthIndicator
  • 둘 다 전역 /actuator/health에도 포함됨
• K8s probe 설정 — port는 actuator가 뜬 포트(management.server.port 설정 시 그 포트)

livenessProbe:
  httpGet: { path: /actuator/health/liveness, port: <actuator-port> }
readinessProbe:
  httpGet: { path: /actuator/health/readiness, port: <actuator-port> }

• startupProbe는 대개 불필요 — 기동이 끝날 때까지 readiness가 계속 fail이라 트래픽이 안 감. 단 기동이 매우 느리면 liveness HTTP를 쓰는 startupProbe를 둬서 기동 중 kill을 방지(14번 startup probe와 같은 취지)
• management 포트를 분리하면 주의 — 별도 management context는 메인 앱과 포트·커넥션 풀이 달라, 메인 앱이 죽어도 probe만 성공할 수 있음 → 메인 서버 포트에도 노출

management.endpoint.health.probes.add-additional-paths=true   # liveness=/livez, readiness=/readyz

상태를 코드로 읽기·바꾸기

• 조회 — ApplicationAvailability 빈 주입 후 getLivenessState() / getReadinessState()
• 변경 — AvailabilityChangeEvent.publish(...)로 새 상태 발행
• 수신 — @EventListener로 AvailabilityChangeEvent<...> 구독

// 변경 발행 — 복구 불가 상황 감지 시 liveness를 BROKEN으로 (→ K8s가 재시작)
catch (CacheCompletelyBrokenException ex) {
    // eventPublisher = 주입된 ApplicationEventPublisher
    AvailabilityChangeEvent.publish(eventPublisher, ex, LivenessState.BROKEN);
}

// 변경 수신 — readiness 전이를 파일로 export (K8s exec probe 연동 예시)
@EventListener
void onChange(AvailabilityChangeEvent<ReadinessState> event) {
    switch (event.getState()) {
        case ACCEPTING_TRAFFIC -> { /* /tmp/healthy 생성 */ }
        case REFUSING_TRAFFIC  -> { /* /tmp/healthy 삭제 */ }
    }
}

애플리케이션 lifecycle과 probe 상태

• 내부 상태(AvailabilityState)와 실제 노출되는 probe는 별개 — lifecycle 단계에 따라 probe가 아직 안 떠 있을 수 있음. Spring이 startup·shutdown 이벤트를 발행하고 probe가 이를 반영
• 기동(startup)

단계	Liveness	Readiness	HTTP 서버	비고
Starting	BROKEN	REFUSING_TRAFFIC	미기동	너무 오래 걸리면 K8s가 liveness 보고 재시작
Started	CORRECT	REFUSING_TRAFFIC	요청 거부	context refresh 완료, startup 작업 수행 중
Ready	CORRECT	ACCEPTING_TRAFFIC	요청 수락	runner까지 완료, 트래픽 수신 시작

• 종료(shutdown)

단계	Liveness	Readiness	HTTP 서버	비고
Running	CORRECT	ACCEPTING_TRAFFIC	요청 수락	shutdown 요청 접수
Graceful shutdown	CORRECT	REFUSING_TRAFFIC	새 요청 거부	in-flight 요청만 마저 처리 (graceful shutdown은 이후 별도 정리)

주요 설정 키

설정 키	용도
management.endpoint.health.probes.enabled	liveness·readiness health group on/off (K8s 감지 시 자동 on)
management.health.livenessstate.enabled / ...readinessstate.enabled	개별 health indicator on/off
management.endpoint.health.probes.add-additional-paths	메인 서버 포트에 /livez·/readyz 추가 노출
management.endpoint.health.group.readiness.include	readiness 그룹에 커스텀 indicator 추가 (예: readinessState,customCheck)