Files

T

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

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

9.9 KiB

Raw Blame History

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

title

source_type

url

archive_url

status

confidence

토스 — Spring Boot Actuator의 헬스체크 살펴보기

Layer: raw/company-tech-blogs/ — 토스 기술블로그 (양권성, 토스페이먼츠 Server Developer, 2023-04-01). Spring Boot Actuator health 동작 원리 + 보안 민감성 한국 도메인 사례. 공식 best practice 아님 — wiki/concepts/ 요약 시 official Spring docs 와 교차 확인 필수.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-management-actuator-security-contract	health endpoint 노출 정책 (detail 노출 수준 통제) + `/actuator/health` 자체의 민감성 분류 한국 사례 근거
raw/branch-notes/feature-security-operational-baseline	public path misconfiguration 분류 → INTERNAL_AUTH_MISCONFIGURATION 500 + P1 결정의 한국 도메인 보조 근거
raw/project-notes/ca-skeleton-operational-contract	Security Baseline (Actuator health endpoint 노출 정책) Group G-B 비교 자료

컨텍스트 / 왜 저장했는지

ca-tmpl feature-management-actuator-security-contract 의 health endpoint 노출 정책 + feature-security-operational-baseline 의 public path misconfiguration 분류 결정과 직접 연관. 토스가 health 정보의 민감성을 어떻게 분류하는지 확인 — /actuator/health 자체도 detail 노출 정도에 따라 보호 대상이라는 한국 기업 사례.

출처 / Source

원본 URL: https://toss.tech/article/how-to-work-health-check-in-spring-boot-actuator
아카이브 URL: (미수집)
저자 / 조직: 양권성 (토스페이먼츠 Server Developer)
발행일: 2023-04-01
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§보안 민감성] "해당 정보는 보안에 민감한 요소가 들어있을 수 있어서 퍼블릭하게 접근이 가능해서는 안 됩니다."

[§헬스 체크 정의] "로드 밸런서에서는 각 서버의 헬스 체크 API를 호출해서 해당 서버가 현재 서비스 가능한 상태인지 아닌지 주기적으로 점검합니다."

[§자동 설정] "[Auto-configured HealthIndicators]에 나열된 HealthIndicator는 [Spring Boot Auto Configuration]에 의해 자동으로 활성화됩니다."

[§상태 집계 로직] "DOWN을 반환한 HealthIndicator가 하나라도 존재하면 서비스의 상태를 DOWN으로 생각해서 503을 반환하게 됩니다."

[§외부 의존성 격리 실패] "로그 DB에 작업을 해야해서 순단이 발생하거나 접속에 문제가 생긴다면…서비스 DB에 문제가 없음에도 불구하고 클라이언트의 요청은 처리되지 않고 장애가 발생합니다."

[§트러블슈팅 예측] "헬스 체크의 동작원리를 정확히 이해했다면 ES 서버가 죽었을 때 해당 서버의 헬스체크도 같이 죽게 된다는 걸 예측할 수 있습니다."

[§Detail 노출] "로컬에서 간단하게 확인만 해보는 목적으로 management.endpoint.health.show-details: always로 설정한 후에 다시 헬스 체크 결과를 확인했습니다."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
TOSS-HEALTH-C1	`/actuator/health` 가 반환하는 정보는 보안 민감 요소 포함 가능 → 퍼블릭 접근 금지 (토스 입장)	[§보안 민감성] "해당 정보는 보안에 민감한 요소가 들어있을 수 있어서 퍼블릭하게 접근이 가능해서는 안 됩니다."	`company-case-study`	Spring Boot Actuator health endpoint 운영	"모든 health endpoint 가 항상 보호 대상" 이라는 일반 best practice 가 아님 — 토스 한국 사례. show-details 수준에 따라 차등 필요 (별도 결정)
TOSS-HEALTH-C2	로드밸런서는 health check API 를 주기적으로 호출하여 서버의 서비스 가능 여부를 판단	[§헬스 체크 정의] "로드 밸런서에서는 각 서버의 헬스 체크 API를 호출해서 해당 서버가 현재 서비스 가능한 상태인지 아닌지 주기적으로 점검합니다."	`company-case-study`	LB-based health check 시나리오	LB 가 호출하는 endpoint 가 `/actuator/health` 자체여야 한다는 뜻 아님 — readiness 분리 별도 결정
TOSS-HEALTH-C3	`auto-configured HealthIndicator` 는 Spring Boot Auto Configuration 으로 자동 활성화	[§자동 설정] "[Auto-configured HealthIndicators]에 나열된 HealthIndicator는 [Spring Boot Auto Configuration]에 의해 자동으로 활성화됩니다."	`company-case-study`	Spring Boot 의 기본 health indicator 동작	자동 활성화되는 indicator 의 정확한 목록은 본 인용에 없음 — Spring 공식 docs 확인 필요
TOSS-HEALTH-C4	HealthIndicator 중 하나라도 DOWN 이면 전체 서비스 상태 DOWN + HTTP 503 반환	[§상태 집계 로직] "DOWN을 반환한 HealthIndicator가 하나라도 존재하면 서비스의 상태를 DOWN으로 생각해서 503을 반환하게 됩니다."	`company-case-study`	Spring Boot Actuator 기본 status aggregation	이 집계 정책이 모든 Spring Boot 버전에서 동일하다는 뜻은 아님 (Spring docs 교차 확인 필요). 또한 group/registry 로 분리 시 동작 다름
TOSS-HEALTH-C5	외부 의존성 (로그 DB 등) 장애 → 서비스 DB 정상에도 client 요청 미처리 발생 가능 (자동 health 집계의 부작용 사례)	[§외부 의존성 격리 실패] "로그 DB에 작업을 해야해서 순단이 발생하거나 접속에 문제가 생긴다면…서비스 DB에 문제가 없음에도 불구하고 클라이언트의 요청은 처리되지 않고 장애가 발생합니다."	`company-case-study`	외부 의존성을 health 집계에 포함한 시스템	모든 외부 의존성을 health 에서 제외해야 한다는 일반 권고 아님 — readiness/liveness 분리 + group 설정의 결정 필요
TOSS-HEALTH-C6	`management.endpoint.health.show-details: always` 설정으로 detail 노출 가능 (로컬 확인 사례 — 운영 권장 아님)	[§Detail 노출] "로컬에서 간단하게 확인만 해보는 목적으로 management.endpoint.health.show-details: always로 설정한 후에 다시 헬스 체크 결과를 확인했습니다."	`company-case-study`	Spring Boot Actuator `show-details` property	운영에서 `always` 가 안전하다는 뜻 아님 — 본문 맥락은 "로컬에서만 임시"

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- TOSS-HEALTH-C1: /actuator/health 민감성 한국 도메인 사례 (토스)
- TOSS-HEALTH-C2~C5: Spring Boot Actuator health check 동작 원리 (LB 호출, auto-config, DOWN 집계, 외부 의존성 부작용) — 토스의 해설
- TOSS-HEALTH-C6: show-details: always property 의 존재
이 자료가 증명하지 않는 것:
- "모든 운영 환경에서 health endpoint 가 항상 인증 뒤로 가야 한다" 는 공식 best practice — 본 글은 회사 사례
- liveness / readiness / startup probe 분리 정책의 정의 — Spring 공식 docs / Kubernetes docs 별도 확인
- management port 분리 권고 — 본 글 범위 밖 (별도 raw: security-woowahan-actuator-safe-usage.md)
- secret rotation / actuator endpoint allowlist 의 best practice — 본 글 범위 밖
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 show-details: when_authorized 또는 never 결정의 Spring 공식 권고 (Spring Boot Reference §Actuator)
- readiness / liveness 분리 시 외부 의존성을 어느 probe 에 포함할지 (feature-runtime-health-lifecycle-contract 와의 정합)
- INTERNAL_AUTH_MISCONFIGURATION 500 + P1 분류가 토스 입장 ("퍼블릭 접근 금지") 와 정합한지 (정합은 추정, 명시 검증 필요)

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

ca-tmpl 결정과의 정합성 (가설):
- health detail 과노출 금지 ← 토스 사례가 "health 정보 자체도 민감 요소 포함 가능" 으로 강조함과 정합 (사례 일치).
- liveness / readiness / startup probe 분리 ← 토스 글은 LB 헬스체크 vs 외부 의존성 헬스체크 구분을 강조; ca-tmpl feature-runtime-health-lifecycle-contract 로 owner 분리되어 있음.
- public path misconfiguration → INTERNAL_AUTH_MISCONFIGURATION 500 + P1 (ca-tmpl feature-security-operational-baseline) ← health detail 보호 토스 관점과 정합 (추정).
취급 주의: 회사 기술블로그 = 공식 best practice 아님 (CLAUDE.md §5). 글의 핵심은 health check 동작 원리 설명이고 보안 측면은 부수적 — 인용 시 "사례" 한정.
토스 글은 actuator 전반 보안이 아니라 health endpoint 단일 focus. management port 분리 / secret rotation 등은 본 글의 직접 출처가 아님 — security-woowahan-actuator-safe-usage.md 등 보완 raw 참조.

같은 주제 다른 raw:
- raw/company-tech-blogs/security-woowahan-actuator-safe-usage (한국 보안 운영 관점)
인용하는 branch:
- raw/branch-notes/feature-management-actuator-security-contract
- raw/branch-notes/feature-security-operational-baseline
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (Group G-B)
인용한 wiki 요약: (미작성)

9.9 KiB Raw Blame History