Spring Boot Actuator 기반 Docker Health Check 설정법

Spring Boot Actuator Health Check 설정 방법: Docker 연동 전 필수 점검 사항

Spring Boot Actuator Health Check는 애플리케이션이 정상적인 상태인지 확인할 때 가장 많이 사용되는 기능입니다. 특히 컨테이너 환경에서 Docker HEALTHCHECK와 연결하려면, 먼저 Spring Boot 애플리케이션 내부에서 /actuator/health 엔드포인트가 정상적으로 응답하는지 확인하는 과정이 선행되어야 합니다.

Actuator 설정 없이 무작정 Docker Health Check만 추가하면 컨테이너의 실제 상태를 정확히 판단하기 어렵습니다. 결론부터 말씀드리면, 먼저 Actuator 의존성을 추가하고 health 엔드포인트 노출 범위를 점검한 뒤, 마지막에 Docker와 연결하는 순서로 작업하는 것이 가장 확실합니다.

Spring Boot Actuator Health Check가 필요한 상황

운영 환경이나 배포 자동화 과정에서 다음과 같은 상황을 마주했다면 Actuator 도입이 필수적입니다.

• Docker 컨테이너가 'Up' 상태인 것만으로는 애플리케이션 정상 여부를 확신할 수 없을 때
• 애플리케이션이 완전히 구동된 것을 확인한 후 다음 배포 파이프라인이나 스크립트를 실행해야 할 때
• 애플리케이션뿐만 아니라 연결된 DB의 상태까지 종합적으로 확인하고 싶을 때
• 무의미한 Thread.sleep() 대기 방식에서 벗어나, 상태 기반의 명확한 대기 로직을 만들고 싶을 때

단순히 Java 프로세스가 떠 있다고 해서 애플리케이션이 트래픽을 받을 수 있는 상태인 것은 아닙니다. 바로 이 간극을 메워주는 것이 health 엔드포인트입니다.

왜 이런 설정이 필요할까?

1) 컨테이너 실행과 애플리케이션 준비는 다르다

Docker 컨테이너가 running 상태가 되었다고 해서 Spring Boot 내장 톰캣이 요청을 받을 준비를 마쳤다는 뜻은 아닙니다. 애플리케이션 컨텍스트를 로드하는 중일 수도 있고, 초기 DB 커넥션을 맺는 데 실패했을 수도 있습니다. 이때 /actuator/health를 주기적으로 호출하여 응답을 확인하면 애플리케이션의 진짜 준비 상태를 정확히 판단할 수 있습니다.

2) 자동화 배포 파이프라인의 안정성 확보

CI/CD 배포 직후 다음 명령을 실행해야 하는 구조라면 준비 상태 확인은 필수입니다. 무작정 1분, 3분을 기다리는 것보다, health 상태가 정상으로 돌아올 때까지 반복 확인(Polling)하는 방식이 훨씬 빠르고 안전합니다.

Spring Boot Actuator Health Check 설정 4단계

1단계. Actuator 의존성 추가하기

가장 먼저 Spring Boot 프로젝트의 pom.xml 또는 build.gradle에 Actuator 의존성을 추가해야 합니다. /actuator/health 엔드포인트는 이 모듈이 있어야 활성화됩니다.

Maven (pom.xml)

XML

 

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

2단계. health 엔드포인트 동작 확인하기

의존성을 추가하고 애플리케이션을 구동한 뒤, 브라우저나 터미널에서 아래 명령어로 정상 응답이 오는지 확인합니다.

Bash

 

curl http://localhost:8080/actuator/health

정상적으로 설정되었다면 아래와 같은 JSON 응답을 받게 됩니다.

JSON

 

{"status":"UP"}

이 응답을 확인해야 향후 Docker와 연동했을 때 문제가 생기면 원인이 애플리케이션에 있는지 인프라에 있는지 분리할 수 있습니다. 만약 404 에러가 발생한다면 다음 단계의 노출 설정을 점검해야 합니다.

3단계. 엔드포인트 노출 설정 확인하기

최신 Spring Boot 버전에서는 기본적으로 health 엔드포인트가 노출되지만, 기존 설정에 따라 막혀 있을 수 있습니다. application.properties 또는 application.yml에 노출 설정을 명시적으로 추가합니다.

Properties

 

management.endpoints.web.exposure.include=health

4단계. Docker HEALTHCHECK와 연결하기

Spring Boot 측의 준비가 모두 끝났다면, 이제 Dockerfile에 Health Check 명령을 추가합니다.

Dockerfile

 

HEALTHCHECK --interval=30s --timeout=5s --retries=5 \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

이 설정이 추가된 컨테이너는 지정된 주기(interval)마다 health 엔드포인트를 찔러봅니다. 여기서 성공하면 컨테이너 상태가 healthy로 표시되며, 이는 내부 애플리케이션 구동까지 완벽히 끝났음을 의미합니다.

실전에서 자주 놓치는 주의사항

• Spring Security 설정 충돌: Spring Security를 적용한 프로젝트라면 /actuator/health 경로에 대한 접근 권한이 막혀 인증 에러(401, 403)가 날 수 있습니다. Security 설정에서 해당 경로를 permitAll() 처리해야 Docker가 접근할 수 있습니다.
• DB 연동 상태와 재시작 루프: Actuator의 health는 기본적으로 DB 연결 상태까지 체크합니다. 만약 DB가 일시적인 순단 현상을 겪어 health 상태가 DOWN이 되면, 오케스트레이션 도구(Kubernetes 등)나 Docker가 컨테이너를 강제로 재시작시켜 버릴 수 있습니다. 이 점을 고려해 세부 헬스 인디케이터(Health Indicator) 설정을 조절해야 합니다.
• 보안 노출 범위: management.endpoint.health.show-details=always 설정을 켜면 디스크, DB 상태 등 민감한 인프라 정보가 그대로 노출됩니다. 운영 환경에서는 이 정보를 외부에 노출하지 않도록 방화벽 설정이나 내부 포트 분리 등을 신중히 검토해야 합니다.

마무리

Spring Boot Actuator Health Check는 Docker 환경에서 서비스를 안정적으로 운영하기 위한 필수 기초 공사입니다.

문제가 생겼을 때 바로 Dockerfile을 수정하기보다는, Actuator 의존성을 확인하고 로컬에서 /actuator/health 응답이 오는지 검증하는 것이 우선입니다. 컨테이너가 '실행 중'인지보다 애플리케이션이 '준비 완료'되었는지를 기준으로 삼으면, 배포 파이프라인과 모니터링 시스템을 훨씬 견고하게 구축할 수 있습니다.