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]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# 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 전이)

## 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]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)