Spring Boot Actuator: /health 커스터마이징

Spring Boot Actuator: /health 커스터마이징

쿠버네티스/ELB는 인스턴스 생사 판단을 /actuator/health에 맡깁니다.

기본 구성만으로 충분할 때도 있지만, 의존 서비스(DB/외부 API/캐시)를 체크하고

배포 중에는 읽기 전용만 허용하는 등 정교한 커스터마이징이 필요합니다.

 

의존성

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

설정

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      probes:
        enabled: true   # liveness/readiness 분리
      show-details: when_authorized

커스텀 HealthIndicator

@Component
public class ExternalApiHealth implements HealthIndicator {
  @Override
  public Health health() {
    boolean ok = pingExternal();
    return ok ? Health.up().withDetail("external","ok").build()
              : Health.down().withDetail("external","fail").build();
  }
}

배포 중 Readiness 제어

@RestController
@RequestMapping("/ops")
public class ReadinessController {
  private final AtomicBoolean ready = new AtomicBoolean(true);

  @PostMapping("/drain") public void drain() { ready.set(false); }
  @GetMapping("/ready") public Map<String, Object> r() {
    return Map.of("ready", ready.get());
  }

  @Bean HealthContributor readiness() {
    return (HealthIndicator) () -> ready.get()? Health.up().build(): Health.outOfService().build();
  }
}

FAQ

Q1. 민감한 상세를 숨기려면?
A. show-details: never 또는 권한 기반 노출을 사용.

Q2. 지표는 어디서 보나요?
A. /actuator/metrics 노출 후 프로메테우스/그래파나 연동을 권장.

 

⏪ 이전 글 보기: application-{profile}.yml 전략 + 비밀키 분리
⏩ 다음 글 보기: @Scheduled 크론 12패턴 + 중복실행 방지

 

👉 1편: Bean Validation(@Valid)로 입력 검증 표준 만들기

👉 2편: @ControllerAdvice 글로벌 예외 응답(에러코드 규격)

👉 3편: application-{profile}.yml 전략 + 비밀키 분리

👉 4편: Spring Boot Actuator: /health 커스터마이징

👉 5편: @Scheduled 크론 12패턴 + 중복실행 방지

👉 6편: 멀티파트 업로드: 제한/보안/임시저장 설계

👉 7편: Spring Cache로 API 3배 빠르게(@Cacheable/무효화)

👉 8편: Pageable 응답 DTO 규격(정렬·페이지 표준화)