[Java] Spring Boot Actuator

개요

---

어플리케이션을 개발하는 것도 중요하지만 개발하는것만큼 중요한 것이 어플리케이션을 잘 운영하는 것이다. 서비스를 잘 운영하기 위해서는 여러 요소가 필요하겠지만, 모니터링은 빠질 수 없는 요소이며 이를 위한 도구들이 많이 개발되어 있다.

 

서비스의 운영에 있어서 모니터링은 필수 요소이지만, 모니터링만을 위해 별도의 엔드포인트를 만들거나 기능을 개발하는데 시간이 많이 든다면 배보다 배꼽이 더 커지는 경우일 수 있다. 스프링 부트에서는 spring-boot-actuator 모듈을 통해 이러한 모니터링 기능을 지원할 뿐만 아니라 서비스를 일부 조작할 수 있게 한다.

 

Actuator 사용해보기

---

의존성 추가

Spring boot에서 엑추에이터를 사용하려면 spring-boot-starter-actuator모듈에 대한 의존성만 아래와 같이 추가해주면 된다.

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

// gradle
dependencies {
    compile("org.springframework.boot:spring-boot-starter-actuator")
}

---

End points

Actuator에서는 기본적으로 상당히 많은 종류의 모니터링 요소를 제공하며, 각 엔드포인트 호출을 통해 조회할 수 있다. 전체 리스트를 나열하자면 너무 많기 때문에 유용하게 쓰일 수 있는 요소들만 정리하면 아래와 같다.

경로	설명	디폴트 활성화
/health	application의 현재상태 조회	Yes
/env	환경설정 정보(application.yml) 조회	No
/httptrace	최근 100건의 http request-response 조회	No
/mappings	모든 http 매핑과 그것을 처리하는 핸들러 메서드 조회(Controller)	No
/threaddump	어플리케이션 threaddump 조회	No

앞서 언급했듯이 Actuator를 사용하면 어플리케이션의 일부 정보들을 열람하거나 심지어 조작도 가능하기 때문에 대부분의 default endPoint들은 활성화가 되어 있지 않다. 기본 세팅만을 진행한 후 /actuator 경로로 GET 요청을 보내면 현재 사용가능한 모니터링 리스트를 아래와 같이 확인할 수 있다.

그림 1. 사용가능한 actuator default endpoints

위의 표에서는 default 엔드 포인트가 많다고 언급했지만 실제로 3개의 엔드포인트만 조회되는 이유는, 설정 파일을 통해 활성, 비활성 할 엔드포인트를 선택 할 수 있지만 현재는 아무 것도 설정하지 않았기 때문이다. 현재 활성화되어 있는 health 경로에 요청을 보내면 아래와 같이 현재 서비스의 상태를 확인해 볼 수 있다.

그림 2. /health actuator 호출

참고로 응답으로 넘어오는 status는 다음의 4가지 상태 중 하나가 될 수 있으며 현재는 시스템이 작동중이고 접근 가능함을 뜻한다.

• UP: 시스템이 작동중이며 접근 가능
• DOWN: 시스템이 작동중이지 않거나, 접근 불가능
• UNKNWON: 시스템의 상태가 분명하지 않음
• OUT_OF_SERVICE: 시스템에 접근은 가능하지만 현재 사용은 불가능

 

Actuator를 안전하게 사용하기

---

위의 경우와 같이 서비스의 상태 조회 정도는 외부에서 마음대로 조회가 가능해도 서비스에 치명적인 영향을 미치지 않을 수는 있지만, env, shutdown등의 엑추에이터 엔드포인트가 외부에 노출되고 이를 마음대로 호출할 수 있다면 서비스의 원활한 운영을 위해 도입했던 툴이 오히려 서비스에 악영향을 미칠 수 있다.

 

/env 조회

 

application.yml에서 Actuator 관련 설정 값을 변경해줄 수 있는데, 테스트를 위해 모든 default end-point들을 활성화(management.endpoints.web.exposure.include: “*”) 해주었다. 또한 /env경로 조회 시 default로는 설정값이 마스킹되기 때문에 마스킹을 해제(management.endpoint.env.show-values: ALWAYS)하기 위한 설정도 추가해 주었다. 

management:
  endpoints:
    web:
      exposure:
        include: "*" # 모든 endpoint 활성화
  endpoint:
    env:
      show-values: ALWAYS # /env 경로 값 전부 보이도록 설정 (없을 시 ***로 마스킹)

ppurio:
  open:
    date: "2023-08-01"

그림. /env 호출 결과

 

 

/shutdown 조회

 

shutdown 엔드 포인트는 기본적으로 비활성화 되어 있기 때문에 아래와 같이 설정 파일에서 활성화를 해준다. 이후 해당 경로로 POST 요청을 하면 실제 서비스가 종료되는 것을 확인할 수 있다.

management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    shutdown:
      enabled: true

그림. /shutdown 호출 결과

그림. tomcat 종료 로그

위의 두 예시는 설명을 위해 어느 정도 일반적으로 벌어지지 않을 경우에 대한 예를 들었지만, 이러한 경우 외에도 엑추에이터를 잘못 사용하게 되면 서비스 가용성에 문제를 일으킬 수 있다. 따라서 아래와 같은 방법을 통해 엑추에이터를 안전하게 사용하려고 노력해야 한다.

 

1. 필요한 end point만 include하여 화이트 리스트로 관리하기

Actuator는 shutdown을 제외한 나머지 endpoint들은 default enable 되어 있다. 이러한 설정을 따를 경우 불필요한 endpoint가 활성화되어 잠재적인 위협이 될 수 있으므로 기본 enabel 설정을 아래와 같이 바꾸어 주어야 하며, 필요한 endpoint만 따로 enable 해주는 것이 좋다.

---

2. 꼭 필요한 end point만 노출하기

Actuator endpoint들은 위의 설정을 통해 enable한다고 바로 사용할 수 있는 구조가 아니라, enable된 endpoint를 expose 시켜야 이용할 수 있다. JMX(Java Management Extentions)와 Http 방식의 default 값이 다른데, 이는 아래 그림과 같다.

그림 3. 유형별 default expose endpoints

그림에서 보다시피 http의 경우 기본적으로 /health만 expose 되어 있기 때문에 management.endpoints.web.exposure.include속성에 필요한 endpoint들을 추가해주어야 하며, 이 때도 명시적으로 사용할 endpoint만 추가해주어야 한다.

반대로 JMX의 경우는 너무 많은 endpoint가 노출되므로 JMX 방식을 사용하지 않을 때에는 아래와 같이 모든 endpoint를 노출하지 않도록 설정해두고 쓰는것이 좋다.

---

3. Actuator 경로, 포트 분리하기

손쉽게 서비스에 대한 정보를 얻고 조작할 수 있다는 점에서 해커(공격자)는 Actuator를 통한 공격을 고려할 수 있는데, 이 경우 Actuator 관련 endpoint를 스캔해볼 수 있다.

 

이 때, 서비스 운영 포트와 actuator 포트를 분리한다면 공격자의 스캐닝에 대해 1차적인 보호조치를 할 수 있다(management.server.port).

Actuator는 기본적으로 /actuator/[endpoint]의 기본 형식을 따르므로 이러한 스캐닝 공격에 취약할 수 있으며, 따라서 actuator에 대한 default 경로를 다른 경로로 변경하면 이러한 스캐닝 공격에 어느 정도는 대응을 할 수 있다(management.endpoints.web.base-path).

---

4. 인증, 인가된 사용자만 Actuator에 접근할 수 있도록 제한하기

스프링 부트의 경우 인증, 인가와 관련된 강력한 모듈인 Spring-Security를 제공하고 있는데, 이를 이용해서 인증, 인가된 요청만 actuator에 도달할 수 있도록 설정해줄 수 있다. 다만, /health같은 endpoint는 굳이 인증 과정이 필요하지 않을 수 있는데 이러한 예외 케이스를 고려하여 적절히 적용해야 한다.

// WebSecurityConfig 예시
public void configure(HttpSecurity http) throws Exception {
	http
		.authorizeRequests()
			.antMatchers("/login").permitAll()  //로그인 경로 모든 접근 허용
			.antMatchers("/actuator/**").hasRold("MANAGER")  //actuator 경로 MANAGER만 접근 가능
			.anyRequest().authenticated()  //나머지 경로는 아무 권한만 있으면 접근 가능
		.and()
			.logout()
				.logoutSuccessUrl("/")  //로그아웃 성공 시 리다이렉트 경로
				.invalidateHttpSession(true)  //로그아웃 시 세션 날리기
	;
}

 

정리

---

엑추에이터는 서비스의 정보를 쉽게 조회할 수 있다는 점에서 모니터링 툴이나 기타 테스트 툴에서도 사용하고 있다. 예를 들면 모니터링을 위한 프로메테우스에서도 엑추에이터를 사용하고 있고, 장애상황 테스트를 위한 모듈인 Chaos Monkey 등 테스트를 위한 툴에서도 사용하고 있다.

 

다음 정리에서는 엑추에이터의 기본적인 사용에서 나아가 모니터링을 지원하는 프로메테우스와 그라파나를 공부해서 정리해볼 예정이다.

 

참고

---

https://techblog.woowahan.com/9232/

Security Actuator 안전하게 사용하기 | 우아한형제들 기술블로그

https://docs.spring.io/spring-boot/docs/2.1.8.RELEASE/reference/html/production-ready-endpoints.html#production-ready-endpoints-enabling-endpoints

53. Endpoints