- Spring Boot Actuator란?
- Spring Boot Actuator를 사용하기 위한 준비
- 추가되는 엔드포인트
- Spring Boot Actuator 사용법
- Spring Boot Actuator 사용 시 주의사항
응용 프로그램이 개발되면 끝이 아니라 다음 단계로 "운영"이 기다리고 있습니다.
그 운용에 도움이 되는 기능을 제공하는 것이 「Spring Boot Actuator」입니다.
본 포스팅에서는, 운용에 있어서의 「Spring Boot Actuator」의 활용에 대해 설명합니다.
1. Spring Boot Actuator란?
Spring Boot Actuator는 Spring Boot에서 개발한 애플리케이션 모니터링 및 관리와 같은 기능을 제공하는 "운영용" Spring 라이브러리입니다. Actuator(액추에이터)는 원래 기계나 전기 등 세계에서 이용되는 기계나 전기 회로를 구동시켜 동작을 제어하는 「구동 장치」를 말합니다.
Spring Boot Actuator는 Spring Boot에서 개발한 애플리케이션을 외부에서 제어하는 것을 목적으로 합니다.
2. Spring Boot Actuator를 사용하기 위한 준비
먼저 Spring Boot Actuator를 이용하기 위한 준비부터 시작해 보겠습니다.
① 전제 조건
전제 조건으로 Spring Boot 프로젝트가 이미 만들어졌다고 가정합니다.
기존 프로젝트가 없는 경우에는 Spring Initializr 등을 이용하여 웹 앱를 만들어 봅시다.
② 의존성 정의
Spring Boot Actuator는 해당 종속성을 추가하기만 하면 쉽게 활성화할 수 있습니다.
Spring Boot의 경우 Maven 또는 Gradle을 사용하고 있으므로 사용중인 프로젝트에 따라 추가하십시오.
종속성을 추가한 후 Spring Boot 앱을 실행하기만 하면 Spring Boot Actuator 엔드포인트를 사용할 수 있습니다.
# Maven의 경우
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>Gradle의 경우
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}
3. 추가되는 엔드포인트
Spring Boot Actuator를 활성화하면 Spring Boot 앱에 '엔드포인트'가 추가됩니다.
애플리케이션 URL과 엔드포인트를 결합하여 엔드포인트에 액세스할 수 있습니다.
예를 들어, "beans"라는 엔드포인트를 사용하려면 다음 URL에 액세스합니다.
http://localhost:8080/actuator/beans
이 섹션에서는 사용 가능한 엔드포인트 중 높은 사용률을 가진 엔드포인트를 소개합니다.
①health
health 엔드포인트를 활용하면 앱이 정상적으로 실행되고 있는지 확인할 수 있습니다.
앱이 제대로 작동하는지 확인하는 간단한 엔드포인트로 기본적으로 사용하도록 설정되어 있습니다.
②beans
beans 엔드포인트를 사용하여 Spring이 DI 컨테이너에서 관리하는 Bean의 정보를 볼 수 있습니다.
자동으로 생성된 Bean을 포함하여 모든 Bean이 목록에서 검색될 수 있으므로 애플리케이션을 디버깅할 때 유용합니다.
③env
env 엔드포인트를 사용하면 Spring Boot가 실행되는 머신이나 가상 환경에 설정된 환경 변수를 얻을 수 있습니다.
프로덕션 환경과 개발 환경에서 다른 데이터베이스를 사용하는 경우에는 환경 변수로 연결 대상을 변경할 수도 있습니다.
이 경우 env 엔드포인트를 사용하여 올바른 환경 변수가 사용되는지 확인할 수 있습니다.
④loggers
로거 엔드포인트를 활용하여 앱 로그를 검색할 수 있습니다.
실제로 콘솔에 출력되는 내용이 그대로 취득되므로, 에러가 발생했을 경우의 스택 트레이스도 간단하게 취득할 수 있습니다.
⑤metrics
metrics 엔드포인트를 활용하여 애플리케이션에 대한 메트릭 정보를 얻을 수 있습니다.
지표에는 JVM의 CPU 및 메모리 사용률, 디스크 사용량 등의 정보가 포함되어 있습니다.
DataDog이나 Elasticsearch 등의 모니터링 시스템과 연계함으로써, 보다 높은 감시의 실현도 가능합니다.
4. Spring Boot Actuator 사용법
Spring Boot Actuator에는 어떤 기능이 존재하는지 확인한 다음 실제 사용법을 살펴 보겠습니다.
① 엔드포인트 활성화/비활성화
Spring Boot Actuator 배포 직후에는 보안 관점에서 일부 엔드포인트만 활성화됩니다.
application.properties에 필요한 엔드포인트 이름을 지정하여 엔드포인트를 사용할 수 있습니다.
예를 들어, 다음 예제는 bean, env 및 health를 활성화합니다.
management.endpoints.web.exposure.include=beans,env,health
또한 와일드카드인 "*"를 지정하면 모든 엔드포인트가 활성화됩니다.
management.endpoints.web.exposure.include=*
자세한 내용은 나중에 설명하지만 모든 엔드포인트를 활성화하는 것은 권장되지 않습니다. 어디까지나, 「어떤 엔드포인트가 존재하는지를 확인한다」라고 하는 목적을 위해서만 이용합시다.
② 로그 레벨 취득·변경
앱의 실행 로그에는 「로그 레벨」이 존재합니다만, 일반적으로는 프로덕션 환경이나 검증 환경에서는 출력하는 로그 레벨을 INFO 이상으로 하는 것이 많습니다.
그러나, 일시적인 조사를 위해서 디버그용의 로그를 출력하고 싶은 경우도 있습니다.
이 경우 loggers 엔드포인트에 로그 레벨을 전송하여 앱을 다시 시작하지 않고 출력하는 로그 레벨을 변경할 수 있습니다.
# 로그 레벨 변경
디버깅을 위해 모든 로그를 얻을 수 있도록 로그 레벨을 "TRACE"로 변경해 봅시다.
로깅 수준을 변경하려면 웹 응용 프로그램의 "loggers" 끝점에 POST에서 데이터를 보냅니다.
Windows의 경우 PowerShell을 사용하여 다음 명령을 실행하여 데이터를 보낼 수 있습니다.
Invoke-RestMethod -Method Post -Uri http://localhost:8080/actuator/loggers/org.springframework -Headers @{"Content-type"="application/json"} -Body '{"configuredLevel": "TRACE"}'
이 때 POST에서 보내는 내용에 "'{“configuredLevel”: “TRACE”}'"를 지정하여 앱이 출력하는 로그 레벨을 TRACE로 변경할 수 있습니다.
# 로그 레벨 얻기
변경이 완료되면 로거 엔드포인트에 액세스하여 구성을 검색합니다.
다음과 같이 GET 요청을 보내 설정 내용을 확인하세요.
Invoke-RestMethod -Method Get -Uri http://localhost:8080/actuator/loggers/org.springframework
그러면 다음과 같이 현재 설정 내용을 얻을 수 있습니다.
configuredLevel effectiveLevel
--------------- --------------
TRACE TRACE
③ 헬스 체크
health 엔드포인트에 액세스할 때 앱이 제대로 작동하는 경우 다음과 같이 'UP'이 검색됩니다.
{"status":"UP"}
앱이 제대로 작동하는지 외부에서 확인하는 것을 "헬스 체크"라고 합니다.
실제 운영에서 이 "헬스 체크"는 매우 중요합니다.
상태 확인을 정기적으로 수행하여 서버 작동이 안정적이거나 중지되었는지 확인합니다.
만약 헬스 체크에 실패했을 경우에는, 「뭔가 문제가 발생하고 있다」는 것을 감지할 수 있으므로, 재빨리 장애 발생을 감지할 수 있습니다.
5. Spring Boot Actuator 사용 시 주의사항
Spring Boot Actuator는 편리한 반면, 외부에서 앱을 제어할 수 있기 때문에 뜻밖의 장애를 낳을 가능성도 있습니다.
예를 들어, 다음과 같은 일이 발생할 수 있습니다.
· 개발자의 오작동으로 인해 앱이 중지되는 경우.
· Actuator의 엔드 포인트에 대해 DDoS 공격을 당한 경우
· 악의적 인 제 3 자에게 앱 로그를 도난한 경우
Spring Boot Actuator는 앱 자체의 동작에 작용하는 기능을 많이 가지고 있습니다.
특히 프로덕션 환경에 대해서는, 잘못된 조작에 의한 오동작이나, 외부로부터의 공격을 최소한으로 억제하도록 주의합시다. Spring Boot Actuator를 도입할 때 주의해야 할 사항을 말씀드리겠습니다.
① 실제로 사용하는 엔드포인트만 공개
게시할 엔드포인트를 최소한으로 사용합시다.
엔드포인트는 집이나 건물에 있어서는 「입구」에 비유할 수 있습니다. 엔드포인트가 많다는 것은, 제3자로부터 하면 「공격하기 쉬운(피킹하기 쉬운) 입구가 많다」라고 동의입니다. 입구가 없으면 공격받을 위험도 낮아져 개발자가 잘못 들어가는 일도 없어집니다.
경우에 따라 프로덕션 환경에서 엔드포인트를 모두 비활성화하는 것도 고려할 수 있습니다.
② 프로덕션 환경에서 사용하는 경우에는 액세스 제어를 한다
프로덕션 환경은 모든 엔드포인트를 무효화하여 위험을 최소화할 수 있지만 모니터링을 위해서는 로그 및 메트릭과 같은 정보가 필요합니다. 그럼에도 불구하고 이러한 정보는 유출되면 보안 사고에 직접 연결될 수 있습니다.
프로덕션 환경에서 엔드포인트를 공개하는 경우에는 반드시 액세스 제어를 마련합시다.
Spring Security와 결합하여 액세스 소스와 사용자에게 적절한 액세스 권한을 부여할 수 있습니다.
③ 취약성이 높은 버전은 이용하지 않는다
Spring Boot Actuator뿐만 아니라 라이브러리에서 취약점이 발견될 수 있습니다.
이 취약성을 방치해 버리는 것, 간단하게 어플리케이션이나 서버가 탈취되어 기밀 정보가 유출하는 가능성도 있습니다.
엔드포인트 제한 및 액세스 제어를 적절히 설정해도 이 취약점을 활용하여 예기치 않은 공격을 받을 수 있습니다.
Spring Boot를 포함한 모든 라이브러리에 취약점이 발견되지 않았는지 확인하고 취약한 버전을 사용하는 경우 즉시 버전을 업그레이드하십시오.
항상 적절한 버전의 라이브러리를 사용하도록 유의하는 것이 중요합니다.