Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

13 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

Spring Boot Actuator — Health Endpoint Groups (Liveness / Readiness / Startup)

Layer: raw/official-docs/ — Spring Boot 공식 reference (Actuator Endpoints + Application Availability) 원문 발췌. ca-tmpl feature-runtime-health-lifecycle-contract 의 liveness / readiness group + readiness 외부 dependency 포함 정책 결정 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-runtime-health-lifecycle-contract	actuator `/actuator/health/liveness` + `/actuator/health/readiness` group 채택 + readiness 에 외부 dependency 포함 정책 결정
raw/branch-notes/feature-management-actuator-security-contract	health endpoint 의 prod 노출 + group 별 detail 노출 정책 결정

컨텍스트

ca-tmpl feature-runtime-health-lifecycle-contract 는 actuator 의 liveness / readiness 분리 group 을 그대로 사용하고, startup probe 는 별도 endpoint 로 둠. 본 source 는 Spring Boot 가 제공하는 health group 모델의 공식 정의를 보존.

출처 / Source

원본 URL: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.health
보조 URL: https://docs.spring.io/spring-boot/reference/features/spring-application.html#features.spring-application.application-availability
아카이브 URL: (미수집)
저자 / 조직: Spring Team (VMware / Broadcom)
발행일: Spring Boot 3.x reference (4.0.6 anchors observed)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§actuator.endpoints.kubernetes-probes] "These indicators are shown on the global health endpoint (\"/actuator/health\"). They are also exposed as separate HTTP Probes by using health groups: \"/actuator/health/liveness\" and \"/actuator/health/readiness\"."

[§features.spring-application.application-availability — LivenessState] "The "Liveness" state of an application tells whether its internal state allows it to work correctly, or recover by itself if it is currently failing. A broken "Liveness" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application."

[§features.spring-application.application-availability — ReadinessState] "The "Readiness" state of an application tells whether the application is ready to handle traffic. A failing "Readiness" state tells the platform that it should not route traffic to the application for now. This typically happens during startup, while CommandLineRunner and ApplicationRunner components are being processed, or at any time if the application decides that it is too busy for additional traffic."

[§features.spring-application.application-availability — ApplicationAvailability] "Application components can retrieve the current availability state at any time, by injecting the ApplicationAvailability interface and calling methods on it."

[§features.spring-application.application-availability — Publish state] "We can also update the state of the application, when the application breaks and cannot recover: AvailabilityChangeEvent.publish(this.eventPublisher, ex, LivenessState.BROKEN);"

[§actuator.endpoints.kubernetes-probes.external-state] "If the readiness state of an application instance is unready, Kubernetes does not route traffic to that instance."

[§actuator.endpoints.health.groups] "A health group can also include/exclude a CompositeHealthContributor."

[§features.spring-application.application-availability — link] "Spring Boot provides Kubernetes HTTP probes for "Liveness" and "Readiness" with Actuator Health Endpoints."

needs-confirmation: 이전 raw 본문에서 인용된 "Custom HealthIndicator beans can be assigned to groups using management.endpoint.health.group.<name>.include. By default, the readiness group includes the readinessState indicator only — application liveness and readiness must NOT depend on external systems by Spring Boot's default model." 문장은 2026-05-27 WebFetch 결과에서 단일 문장 verbatim 으로 확인 불가. management.endpoint.health.group.<name>.include property 자체는 reference 의 다른 위치에 존재하나, "must NOT depend on external systems" 라는 정책 문장의 verbatim 출처는 별도 fetch 필요. 따라서 본 raw 의 직접 증명 범위에서 제외.

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SB-HEALTH-C1	Spring Boot 의 health indicator 들은 global `/actuator/health` 외에 health group 으로 `/actuator/health/liveness` 와 `/actuator/health/readiness` HTTP Probe 로도 노출됨	[§actuator.endpoints.kubernetes-probes] "They are also exposed as separate HTTP Probes by using health groups: `\"/actuator/health/liveness\"` and `\"/actuator/health/readiness\"`."	`official-vendor-doc`	Spring Boot Actuator 가 Kubernetes 환경에서 auto-configure 되는 경우	startup probe 용 dedicated endpoint 가 default 로 노출된다는 뜻은 아님 — 본 인용에 startup endpoint 언급 없음
SB-HEALTH-C2	Liveness state 의 정의: 애플리케이션의 internal state 가 정상 동작 가능하거나 자력 복구 가능한지를 표현. broken Liveness = 자력 복구 불가, infrastructure 가 restart 해야 함	[§features.spring-application.application-availability] "The "Liveness" state of an application tells whether its internal state allows it to work correctly, or recover by itself if it is currently failing. A broken "Liveness" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application."	`official-vendor-doc`	Spring Boot 2.3+ AvailabilityState 모델	어떤 조건이 BROKEN 으로 전이시키는지의 구체 trigger 는 본 인용 범위 밖 — 애플리케이션 코드 결정
SB-HEALTH-C3	Readiness state 의 정의: 트래픽 처리 준비 여부. failing readiness 는 플랫폼에 traffic routing 중단을 알림 (startup 중 또는 busy 시)	[§features.spring-application.application-availability] "The "Readiness" state of an application tells whether the application is ready to handle traffic. A failing "Readiness" state tells the platform that it should not route traffic to the application for now."	`official-vendor-doc`	Spring Boot 2.3+ AvailabilityState 모델	readiness 가 자동으로 외부 의존성 (DB / Kafka 등) 실패에 반응한다는 뜻은 아님 — application code 가 publish 해야 함
SB-HEALTH-C4	`ApplicationAvailability` 인터페이스를 주입하여 현재 availability state 를 조회 가능	[§features.spring-application.application-availability] "Application components can retrieve the current availability state at any time, by injecting the `ApplicationAvailability` interface and calling methods on it."	`official-vendor-doc`	Spring Boot 2.3+ DI 환경	상태 전이 책임은 application code — auto-detection 보장 안 됨
SB-HEALTH-C5	`AvailabilityChangeEvent.publish(eventPublisher, ex, LivenessState.BROKEN)` 패턴으로 application code 가 명시적으로 state 전이 publish 가능	[§features.spring-application.application-availability] "We can also update the state of the application, when the application breaks and cannot recover: `AvailabilityChangeEvent.publish(this.eventPublisher, ex, LivenessState.BROKEN);`"	`official-vendor-doc`	LivenessState / ReadinessState 전이 시점 명시 제어	exception handler 외 다른 위치 (예: scheduled task) 에서의 published pattern 은 본 인용 범위 밖
SB-HEALTH-C6	애플리케이션 instance 의 readiness 가 unready 이면 Kubernetes 는 해당 instance 로 traffic routing 안 함	[§actuator.endpoints.kubernetes-probes.external-state] "If the readiness state of an application instance is unready, Kubernetes does not route traffic to that instance."	`official-vendor-doc`	Kubernetes 환경의 Spring Boot Actuator readiness group	"ready → unready 전이" 의 정확한 propagation 지연 (kubelet probe period × failureThreshold) 은 K8s probe 측 변수 — 별도
SB-HEALTH-C7	health group 은 `CompositeHealthContributor` 를 include / exclude 가능	[§actuator.endpoints.health.groups] "A health group can also include/exclude a `CompositeHealthContributor`."	`official-vendor-doc`	health group 구성 시	외부 dependency 를 readiness 에 포함시키는 권장 / 비권장 정책은 본 인용 범위 밖 (needs-confirmation 참조)
SB-HEALTH-C8	"default readiness group 은 외부 의존성을 포함하지 않는다 / 포함해서는 안 된다" 라는 단일 문장 verbatim 은 본 capture 에서 확보 못 함	(부재 자체가 claim)	`needs-confirmation`	readiness group default 멤버 정책	외부 의존성을 readiness 에 추가해도 안전하다는 뜻도 아님 — Spring Boot reference 의 별도 섹션 fetch 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SB-HEALTH-C1: /actuator/health/liveness + /actuator/health/readiness group 의 HTTP Probe 노출
- SB-HEALTH-C2 ~ C5: LivenessState / ReadinessState 의 정의와 ApplicationAvailability + AvailabilityChangeEvent.publish 모델
- SB-HEALTH-C6: Kubernetes 가 unready 인스턴스로 traffic routing 안 함
- SB-HEALTH-C7: health group 의 include / exclude 메커니즘 존재
이 자료가 증명하지 않는 것:
- SB-HEALTH-C8: default readiness group 멤버 (readinessState 만 포함 vs 외부 의존성 포함 정책) verbatim
- startup probe 를 Spring Boot 가 dedicated group 으로 제공하는지 (현재 인용 범위: liveness + readiness 만 명시)
- HealthIndicator 의 per-indicator timeout 제어 메커니즘 (endpoint-level vs indicator-level)
- graceful shutdown 시 readiness 가 자동 DOWN 으로 전환되는 mechanism 의 verbatim 출처 (Application Availability 페이지 본문에는 명시 부재 — 2026-05-27 fetch 결과)
내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 readiness group 에 DB / outbox broker 를 포함시키려면 management.endpoint.health.group.readiness.include=readinessState,db,... 명시 설정 필요 — 이 property 의 verbatim 출처 별도 fetch
- ca-tmpl 의 startup endpoint (/actuator/health/startup) 가 manually 구성된 health group 인지, 아니면 별도 endpoint 인지 (Spring Boot 가 dedicated group 제공 여부 미확정)
- graceful shutdown ↔ readiness DOWN 자동 전환의 공식 메커니즘 (Application Availability 또는 별도 graceful-shutdown reference 페이지)

ca-tmpl 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아니라 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 wiki/projects/ca-skeleton-operational-contract source-summary 로 이전.

장점:
- 별도 코드 없이 K8s probe 규약과 1:1 매핑 (SB-HEALTH-C1, C6).
- ApplicationAvailability API 로 application code 에서 명시적 상태 전이 가능 (SB-HEALTH-C4, C5).
ca-tmpl 과의 차이:
- ca-tmpl 은 startup endpoint 를 별도 명시 (/actuator/health/startup) — Spring Boot 가 startup 전용 group 을 default 제공하는지는 본 capture 에서 미확정. 일반적으로 readiness group 을 startup probe 에 재활용하거나 별도 group 수동 정의.
- ca-tmpl 의 "readiness 에 외부 dependency 포함" 정책은 Spring Boot default 모델과 어긋날 가능성 — SB-HEALTH-C8 needs-confirmation 해소 후 재확인 필요.

메모 / Notes

2026-05-27 재검증: Application Availability 페이지 verbatim 확보. Endpoints 페이지의 Kubernetes Probes 섹션 verbatim 확보. 단 "default readiness group 멤버 + 외부 의존성 정책" 단일 문장 verbatim 미확보 → SB-HEALTH-C8 로 분리.
다음 fetch 후보:
- https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.health.groups (group include property verbatim)
- https://docs.spring.io/spring-boot/reference/features/graceful-shutdown.html (readiness 자동 DOWN 전이)

같은 주제 다른 official-doc:
- raw/official-docs/runtime-health-k8s-probes-official — Kubernetes 측 probe 정의
- raw/official-docs/actuator-endpoint-exposure-spring-official — health endpoint 노출 default
- raw/official-docs/actuator-management-port-spring-official — health endpoint 의 노출 포트 결정
인용하는 branch:
- raw/branch-notes/feature-runtime-health-lifecycle-contract
- raw/branch-notes/feature-management-actuator-security-contract
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract
인용한 wiki 요약: (미작성)

13 KiB Raw Blame History Unescape Escape