feat: 공식 문서 근거자료, 브랜치 기능 문서 작성
This commit is contained in:
DongHyeonka
@@ -7,9 +7,9 @@ status: raw
|
||||
confidence: high
|
||||
tags: [ca-skeleton, runtime, health, lifecycle, spring-boot, actuator]
|
||||
related_projects: [ca-skeleton-operational-contract]
|
||||
related_branches: [feature-runtime-health-lifecycle-contract, feature-management-actuator-security-contract]
|
||||
related_branches: [feature-runtime-health-lifecycle-contract, feature-management-actuator-security-contract, feature-capability-provider-selection-contract]
|
||||
created: 2026-05-22
|
||||
last_reviewed: 2026-05-27
|
||||
last_reviewed: 2026-07-28
|
||||
---
|
||||
|
||||
# Spring Boot Actuator — Health Endpoint Groups (Liveness / Readiness / Startup)
|
||||
@@ -23,6 +23,7 @@ last_reviewed: 2026-05-27
|
||||
|---|---|
|
||||
| [[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 메커니즘 근거) |
|
||||
|
||||
## 컨텍스트
|
||||
|
||||
@@ -57,6 +58,18 @@ ca-tmpl `feature-runtime-health-lifecycle-contract` 는 actuator 의 **liveness
|
||||
|
||||
> 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 의 직접 증명 범위에서 제외.
|
||||
|
||||
**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 each `HealthIndicator` based on an ordered list of statuses."
|
||||
|
||||
> [§actuator.endpoints.health.groups] "By default, groups inherit the same `StatusAggregator` and `HttpCodeStatusMapper` settings 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 |
|
||||
@@ -68,7 +81,11 @@ ca-tmpl `feature-runtime-health-lifecycle-contract` 는 actuator 의 **liveness
|
||||
| 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 필요 |
|
||||
| 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 / 적용 경계
|
||||
|
||||
@@ -77,15 +94,21 @@ ca-tmpl `feature-runtime-health-lifecycle-contract` 는 actuator 의 **liveness
|
||||
- `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
|
||||
- `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 함의 (내 프로젝트 해석)
|
||||
|
||||
@@ -101,8 +124,8 @@ ca-tmpl `feature-runtime-health-lifecycle-contract` 는 actuator 의 **liveness
|
||||
## 메모 / 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) 후 Python `html.parser` 로 텍스트만 추출해 self-grep 대조. `management.endpoint.health.group.<name>` property, `StatusAggregator` aggregation, group 의 aggregator 상속, "essential 하지 않은 외부 시스템은 포함하지 말 것" 판단 기준의 verbatim 4개 신규 확보 (`SB-HEALTH-C9`~`C12`). `SB-HEALTH-C8` 의 "포함 여부는 개발자 판단" 부분은 해소되었으나, "capability descriptor 로 그 판단을 자동화한다"는 부분은 여전히 ca-skeleton 자체 설계(본 자료가 증명 안 함).
|
||||
- 다음 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 전이)
|
||||
|
||||
## Related / 관련
|
||||
@@ -114,6 +137,7 @@ ca-tmpl `feature-runtime-health-lifecycle-contract` 는 actuator 의 **liveness
|
||||
- 인용하는 branch:
|
||||
- [[raw/branch-notes/feature-runtime-health-lifecycle-contract]]
|
||||
- [[raw/branch-notes/feature-management-actuator-security-contract]]
|
||||
- [[raw/branch-notes/feature-capability-provider-selection-contract]]
|
||||
- 인용하는 project:
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]]
|
||||
- 인용한 wiki 요약: (미작성)
|
||||
|
||||
Reference in New Issue
Block a user