20 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Spring Boot Actuator — Health Endpoint Groups (Liveness / Readiness / Startup) | official-doc | https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.health | raw | high |
|
|
|
2026-05-22 | 2026-07-28 |
Spring Boot Actuator — Health Endpoint Groups (Liveness / Readiness / Startup)
Layer:
raw/official-docs/— Spring Boot 공식 reference (Actuator Endpoints + Application Availability) 원문 발췌. ca-tmplfeature-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 노출 정책 결정 |
| raw/branch-notes/feature-capability-provider-selection-contract | 활성화된 provider 만 readiness 에 반영한다 — optional cache 실패는 pod 를 unready 로 만들지 않고, session/idempotency/필수 lock 실패는 unready 로 만든다. 판정 주체는 capability descriptor 이지 bean 존재가 아니다 (StatusAggregator 기반 aggregation + health group include/exclude 메커니즘 근거) |
컨텍스트
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
CommandLineRunnerandApplicationRunnercomponents 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
ApplicationAvailabilityinterface 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
HealthIndicatorbeans can be assigned to groups usingmanagement.endpoint.health.group.<name>.include. By default, the readiness group includes thereadinessStateindicator 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>.includeproperty 자체는 reference 의 다른 위치에 존재하나, "must NOT depend on external systems" 라는 정책 문장의 verbatim 출처는 별도 fetch 필요. 따라서 본 raw 의 직접 증명 범위에서 제외.
2026-07-28 추가 수집 (feature-capability-provider-selection-contract 근거, curl 직접 fetch → self-grep 검증 완료, 위 SB-HEALTH-C8 gap 부분 해소):
[§actuator.endpoints.health.groups] "To create a health indicator group, you can use the
management.endpoint.health.group.<name>property and specify a list of health indicator IDs to include or exclude."
[§actuator.endpoints.health] "By default, the final system health is derived by a
StatusAggregator, which sorts the statuses from eachHealthIndicatorbased on an ordered list of statuses."
[§actuator.endpoints.health.groups] "By default, groups inherit the same
StatusAggregatorandHttpCodeStatusMappersettings as the system health."
[§actuator.endpoints.kubernetes-probes.external-state] "By default, Spring Boot does not add other health indicators to these groups."
[§actuator.endpoints.kubernetes-probes.external-state] "Other external systems might not be essential to the application (the application could have circuit breakers and fallbacks), in which case they definitely should not be included."
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 필요 — 2026-07-28: C11/C12 로 부분 해소 (아래) |
| SB-HEALTH-C9 | health indicator group 은 management.endpoint.health.group.<name> property 로 health indicator ID 목록을 include/exclude 지정해 생성한다 |
[§actuator.endpoints.health.groups] "To create a health indicator group, you can use the management.endpoint.health.group.<name> property and specify a list of health indicator IDs to include or exclude." |
official-vendor-doc |
모든 custom health group (liveness/readiness 포함) 생성 메커니즘 | liveness/readiness 그룹이 startup 시 자동으로 이 매커니즘을 거쳐 구성된다는 순서·시점까지는 본 인용 범위 밖 |
| SB-HEALTH-C10 | 전체 system health(및 각 group)는 기본적으로 StatusAggregator 가 각 HealthIndicator 의 status 를 정렬된 순서 목록 기준으로 정렬하여 도출한다 — 첫 항목이 overall status |
[§actuator.endpoints.health] "By default, the final system health is derived by a StatusAggregator, which sorts the statuses from each HealthIndicator based on an ordered list of statuses." |
official-vendor-doc |
global /actuator/health 및 모든 health group 의 aggregation 규칙 |
개별 capability 의 실패가 어떤 Status(DOWN/OUT_OF_SERVICE 등) 로 매핑되어야 하는지는 본 인용 범위 밖 — application 코드 책임 |
| SB-HEALTH-C11 | health group 은 기본적으로 system 전체와 동일한 StatusAggregator/HttpCodeStatusMapper 설정을 상속한다 — group 마다 별도 override 가능 |
[§actuator.endpoints.health.groups] "By default, groups inherit the same StatusAggregator and HttpCodeStatusMapper settings as the system health." |
official-vendor-doc |
readiness/liveness group 포함 모든 custom group 의 aggregation 상속 규칙 | readiness group 이 실제로 override 설정을 갖는지 여부는 이 인용만으로 알 수 없음 — 프로젝트별 설정 확인 필요 |
| SB-HEALTH-C12 | readiness/liveness health group 은 기본적으로 다른 health indicator 를 추가하지 않으며, 외부 시스템을 readiness 에 포함할지는 "필수(essential)한가"를 기준으로 애플리케이션 개발자가 판단해야 한다 — non-essential(예: fallback 가능한 optional cache)은 포함하지 말아야 함 | [§actuator.endpoints.kubernetes-probes.external-state] "By default, Spring Boot does not add other health indicators to these groups." + "Other external systems might not be essential to the application (the application could have circuit breakers and fallbacks), in which case they definitely should not be included." | official-vendor-doc |
readiness probe 에 캐시·비필수 외부 시스템을 포함할지 판단하는 일반 기준 | "필수/비필수"를 자동으로 구분해주는 Spring Boot 메커니즘은 없음 — capability descriptor 로 판정하는 것은 ca-skeleton 의 설계 결정(본 branch), 공식 문서가 강제하는 구현 방식은 아님 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
SB-HEALTH-C1:/actuator/health/liveness+/actuator/health/readinessgroup 의 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-C9: health group 생성은management.endpoint.health.group.<name>property 로 이뤄짐SB-HEALTH-C10: system health(및 group)의 aggregation 은 기본적으로StatusAggregator가 정렬된 상태 목록 기준으로 도출SB-HEALTH-C11: health group 은 기본적으로 system 과 동일한StatusAggregator/HttpCodeStatusMapper를 상속SB-HEALTH-C12: readiness/liveness group 은 기본적으로 다른 indicator 를 추가하지 않으며, non-essential 외부 시스템은 포함하지 말아야 한다는 판단 기준이 명시됨
- 이 자료가 증명하지 않는 것:
SB-HEALTH-C8: default readiness group 멤버 (readinessState 만 포함 vs 외부 의존성 포함 정책) verbatim — 2026-07-28:SB-HEALTH-C12로 정책 판단 기준("essential 한가")은 확보. 단 "capability descriptor 로 판정한다"는 구현 방식 자체는 여전히 ca-skeleton 의 설계 결정이며 본 자료가 증명하지 않음.- 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 결과)
- "판정 주체는 capability descriptor 이지 bean 존재가 아니다" — 이는 Spring Boot 문서가 아닌 ca-skeleton 자체 설계 결정. 본 자료는 group aggregation·include/exclude 메커니즘과 "essential 여부로 판단하라"는 일반 기준만 증명
- 내 프로젝트 (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 페이지)
feature-capability-provider-selection-contract: capability descriptor 의 readiness 기여 여부를 실제로management.endpoint.health.group.readiness.include/exclude로 배선하는 구체 구현(어떤 capability 를 이 property 목록에 넣을지)은 이 자료가 아니라 branch 의 §구현 가이드에서 결정 — 본 자료는 "그렇게 include/exclude 할 수 있는 메커니즘이 존재한다"까지만 증명
- ca-tmpl 이 readiness group 에 DB / outbox broker 를 포함시키려면
ca-tmpl 함의 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아니라 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시
wiki/projects/ca-skeleton-operational-contractsource-summary 로 이전.
- 장점:
- 별도 코드 없이 K8s probe 규약과 1:1 매핑 (
SB-HEALTH-C1,C6). ApplicationAvailabilityAPI 로 application code 에서 명시적 상태 전이 가능 (SB-HEALTH-C4,C5).
- 별도 코드 없이 K8s probe 규약과 1:1 매핑 (
- 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-C8needs-confirmation 해소 후 재확인 필요.
- ca-tmpl 은 startup endpoint 를 별도 명시 (
메모 / Notes
- 2026-05-27 재검증: Application Availability 페이지 verbatim 확보. Endpoints 페이지의 Kubernetes Probes 섹션 verbatim 확보. 단 "default readiness group 멤버 + 외부 의존성 정책" 단일 문장 verbatim 미확보 →
SB-HEALTH-C8로 분리. - 2026-07-28 재수집 (
feature-capability-provider-selection-contract근거): WebFetch 의 소형 모델 요약이 paraphrase 되어 verbatim 요건을 충족하지 못해,curl로 원문 HTML 을 직접 fetch(HTTP 200, 235KB) 후 Pythonhtml.parser로 텍스트만 추출해 self-grep 대조.management.endpoint.health.group.<name>property,StatusAggregatoraggregation, group 의 aggregator 상속, "essential 하지 않은 외부 시스템은 포함하지 말 것" 판단 기준의 verbatim 4개 신규 확보 (SB-HEALTH-C9~C12).SB-HEALTH-C8의 "포함 여부는 개발자 판단" 부분은 해소되었으나, "capability descriptor 로 그 판단을 자동화한다"는 부분은 여전히 ca-skeleton 자체 설계(본 자료가 증명 안 함). - 다음 fetch 후보:
https://docs.spring.io/spring-boot/reference/features/graceful-shutdown.html(readiness 자동 DOWN 전이)
Related / 관련
- 같은 주제 다른 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:
- 인용하는 project:
- 인용한 wiki 요약: (미작성)