llm-wiki/raw/official-docs/runtime-health-spring-actuator-groups.md

---
title: "Spring Boot Actuator — Health Endpoint Groups (Liveness / Readiness / Startup)"
source_type: official-doc
url: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.health
archive_url:
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, feature-capability-provider-selection-contract]
created: 2026-05-22
last_reviewed: 2026-07-28
---

# 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 노출 정책 결정 |
| [[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 `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 의 직접 증명 범위에서 제외.

**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 |
|---|---|---|---|---|---|
| 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/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-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 함의 (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용이 아니라 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` 로 분리.
- 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/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:
  - [[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 요약: (미작성)