Introduction to Spring Boot Admin

In this post, we will discuss various features of the Spring Boot admin web application.

 

Spring Boot Admin

Spring Boot admin is a community project use to manage and monitor your Spring Boot applications. The client application gets register themselves with the admin server (via Http) or is discovered using Spring Cloud discover server like Eureka, Consul.

Each client application needs to have Spring Actuator jars in it. The endpoints provided by the Actuator jar is polled by the Spring Boot Admin server to get the metrics of that particular application.

Actuators endpoints let you monitor and interact with your application. Spring Boot includes a number of built-in endpoints and lets you add your own. To know more details about these endpoints read Spring Boot Actuator.

In this article, we will first set up a Spring Boot Admin server and then create a simple rest service and register it with the admin server.

 

1. Admin Server Setup

The best way to create a spring boot application is Spring Initializr.  Select your Spring Boot version (2+ recommended) and add the ‘Spring Boot Admin Server’ dependency. Generate it as a Maven project and you are all set.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.example</groupId>
   <artifactId>spring-admin-server</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <packaging>jar</packaging>
   <name>spring-admin-server</name>
   <description>Demo project for Spring Boot</description>
   <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>2.0.5.RELEASE</version>
      <relativePath />
      <!-- lookup parent from repository -->
   </parent>
   <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
      <java.version>1.8</java.version>
      <spring-boot-admin.version>2.0.3</spring-boot-admin.version>
   </properties>
   <dependencies>
      <dependency>
         <groupId>de.codecentric</groupId>
         <artifactId>spring-boot-admin-starter-server</artifactId>
      </dependency>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-test</artifactId>
         <scope>test</scope>
      </dependency>
   </dependencies>
   <dependencyManagement>
      <dependencies>
         <dependency>
            <groupId>de.codecentric</groupId>
            <artifactId>spring-boot-admin-dependencies</artifactId>
            <version>${spring-boot-admin.version}</version>
            <type>pom</type>
            <scope>import</scope>
         </dependency>
      </dependencies>
   </dependencyManagement>
   <build>
      <plugins>
         <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
         </plugin>
      </plugins>
   </build>
</project>

Enable the admin server by adding @EnableAdminServer at your main class.

@SpringBootApplication
@EnableAdminServer
public class SpringAdminServerApplication {
 public static void main(String[] args) {
  SpringApplication.run(SpringAdminServerApplication.class, args);
 }
}

This is all needed to enable the Spring Boot admin server. Let’s run the application and open http://localhost:8080.

 

 

2. Setting Up an Admin Client

We need to create a simple Spring Boot web application and add the following maven dependencies

<dependency>
   <groupId>de.codecentric</groupId>
   <artifactId>spring-boot-admin-starter-client</artifactId>
</dependency>

Spring Boot Admin (client) automatically bring in the Actuator jar. The application includes a simple REST controller with a single GET mapping that just returns a greeting message.

@RestController
public class GreetController {

 @GetMapping("/greet")
 public String greet() {
  return "Hi!! there...";
 }
}

As the last step, let’s update
application.properties file with the following properties.

server.port=8060
spring.application.name=greet-service
spring.boot.admin.client.url=http://localhost:8080
management.endpoints.web.exposure.include=*

spring.boot.admin.client.url is a mandatory property which is the URL of the Spring Boot Admin Server to register at.management.endpoints.web.exposure.include is used to expose all the actuators endpoints.

For production, you should carefully choose which endpoints to expose. NOTE- If you care using .yml as your properties, * has a special meaning in YAML, so be sure to add quotes if you want to include (or exclude) all endpoints, as shown in the following example:

management:
  endpoints:
  web:
   exposure:
   include: "*"

Now boot the application up and visit the Admin server.

Let’s go into details.

 

As you can see, you can get much info about your application using the UI.

 

3. Client Using Spring Cloud Discovery

If you have a Spring Cloud Discovery (like Eureka) for your application, you don’t need to have Spring Boot Admin Client jar in each of your client application (Although each one of them must have actuator jar in their classpath).

3.1 Maven Dependencies

Add the following dependency in the pom.xml

<dependency>
   <groupId>org.springframework.cloud</groupId>
   <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency&g

Enable discovery by adding code class=”literal”>@EnableDiscoveryClient in your main class

@SpringBootApplication
@EnableAdminServer
@EnableDiscoveryClient
public class SpringAdminServerApplication {

 public static void main(String[] args) {
  SpringApplication.run(SpringAdminServerApplication.class, args);
 }
}

As the last point, tell the Eureka client where to find the service registry by adding following properties in the
application.properties file.

eureka.client.serviceUrl.defaultZone=http://localhost:8761/eureka
eureka.client.register-with-eureka=false

Spring Boor Admin Server will get all client application details from Eureka and poll them for metrics.

 

4. Monitoring and Management Features

Let’s take a look at some of the monitoring and management features available by Spring Boot admin.

4.1 Logging

You can reconfigure your log level (root or a particular package) directly from the UI itself without having to change a properties file or without any restart of your application.

 

4.2 JVM Metrics

If you are using tomcat as your container, JMX-beans are exposed via Http. This is because of the Jolokia (auto-included in spring-admin-server-client) jar in your classpath. As Jolokia is servlet based there is no support for reactive applications.

 

4.3 Web Mappings and Traces

These ware views for all the mappings that are present in your application and what all Http traces were made.

 

5. Security

The Spring Boot admin server has access to application sensitive endpoints, so its advisable to have some sort of security enabled to both admin and client application. Since there are several approaches to solving authentication and authorization in distributed web applications Spring Boot Admin doesn’t ship a default one.

You can go with a basic username/password set up on both the admin server and the client application and then configure each other credentials in the properties file. Let’s see the same.

Add the following dependency in your pom.xml file to enable Spring Security for your application.

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

Add the following properties to the application.properties file

spring.security.user.name=admin
spring.security.user.password=admin

[pullquote align=”normal”]Above example only provides basic security and not recommended for the production applications. [/pullquote]

To force the login page, add the following code in your application

@SpringBootApplication
@EnableAdminServer
public class SpringAdminServerApplication {

 private final String adminContextPath;

 public SpringAdminServerApplication(AdminServerProperties adminServerProperties) {
  this.adminContextPath = adminServerProperties.getContextPath();
 }

 public static void main(String[] args) {
  SpringApplication.run(SpringAdminServerApplication.class, args);
 }

 @Bean
 public SecurityWebFilterChain securityWebFilterChainSecure(ServerHttpSecurity http) {

  return http.authorizeExchange()
   .pathMatchers(adminContextPath + "/assets/**").permitAll()
   .pathMatchers(adminContextPath + "/login").permitAll()
   .anyExchange().authenticated()
   .and().formLogin().loginPage(adminContextPath + "/login")
   .and().logout().logoutUrl(adminContextPath + "/logout")
   .and().httpBasic()
   .and().csrf().disable().build();

 }

}

Open the page by visiting http://localhost:8080

 

Once security is active the clients have to know about this authentication in order to register themselves to Spring Boot Admin Server. Also, they have to tell Spring Boot Admin Server how it should connect its actuator endpoints, i.e pass its own credentials (passed via metadata). Add the following properties in greet-service code class=”literal”>application.properties:

#Required for this application to connect to SBA
spring.boot.admin.client.username=admin
spring.boot.admin.client.password=admin

#basic auth creddentials
spring.security.user.name=client
spring.security.user.password=client

#configs to give secured server info to SBA while registering
spring.boot.admin.client.instance.metadata.user.name= ${spring.security.user.name}
spring.boot.admin.client.instance.metadata.user.password=${spring.security.user.password}

This will set up the basic auth in both Spring Boot Admin Server and the Client application. Most of the distributed applications are setup using some sort of token implementation (ID token or using basic client credential grant type) with a common authorization server that grants tokens. You can setup using this if that’s the scenario.

 

6. Notifications

Spring Boot Admin Server can send you notifications if something fails. The following notifiers are available out of the box:

• Email
• PagerDuty
• OpsGenie
• Hipchat
• Slack
• Let’s Chat
• Microsoft Teams
• Telegram

You can, of course, implement your own notification. Let’s just see how you will implement a mail notification. Add spring-boot-starter-mail to your dependencies:

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

Then add the mail configuration in the application.properties.

spring.mail.host=smtp.example.com
[email protected]
spring.mail.username=smtp_user
spring.mail.password=smtp_password

For more information read

 

Summary

In this article, we covered how to set up a Spring Boot Admin Server. Then we created a client application and registered it with the admin server. We then saw some of the monitoring and logging features from the web dashboard.

The sample code for this article can be found on Github