SpringTechnology

Introduction to Spring Boot Admin Server with Example

A guide to Spring Boot Admin Server. Learn to create a centralised Admin Server to monitor and manage your other Spring Boot Services.

What is Spring Boot Admin Server

Firstly, to understand the admin Server, you need to know Actuators in Spring Boot. If you don’t know please visit: Spring Boot Actuator with Spring Boot 2. (For users of Spring Boot 1.x: Spring Boot Actuator with Spring Boot 1.x).

Actuators are used to manage and monitor individual Spring Boot services. However, using actuators for monitoring and managing large number of services is not easy. Because each service has its own actuator endpoint. Which makes it difficult to inspect them individually. Also, the actuator endpoints do not provide a visual representation of the applications health.

In other words, actuators are great at inspecting individual Spring Boot applications, but when you have ‘n’ number of Spring Boot Services, the actuators are not easy.

The Admin Server, exactly solves this problem. it is a server which provides UI based management and monitoring console for various Spring Boot Applications.

Various Spring Boot applications (called as clients) register their actuator endpoints with the Admin Server and admin server uses HTTP interface to monitor these services.

Start Admin Server

The Admin Server is simple Spring Boot Project, with absolutely no code. As stated earlier, it is a central monitoring application for all of your spring boot services.

Firstly, create a new Spring Boot Application (Empty). Then, add below entries to gradle.

gradle dependency

implementation 'de.codecentric:spring-boot-admin-starter-server'
implementation 'de.codecentric:spring-boot-admin-server-ui'

Finally you need enable admin server with @EnableAdminServer annotation.

Application.java

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

Now, open the browser and run the application on default port http://localhost:8080. You should see the Server UI looking for services to monitor.

Spring Boot Admin Server - Empty | amitph
Spring Boot Admin Server – Empty

At this point you, have got your Admin Server up and running.

Admin Server Clients

The Clients are any normal Spring Boot Actuator enabled services which are monitored by Admin Server. For example, we have a Songs Service with actuator already enabled. Now, to the Songs Service need to register itself with the admin server we started above. To do this, Songs Service needs admin server client dependency.

gradle dependency

implementation 'de.codecentric:spring-boot-admin-starter-client:2.1.3'

After this, you need to enable the actuator endpoints and also provide admin server url.

application.yaml

management:
  endpoints:
    web:
      exposure:
        include: '*'
  endpoint:
    health:
      show-details: always
spring:
  boot:
    admin:
      client:
        url: [http://localhost:8080]
  application:
    name: Songs Service

The Songs Service is now ready to launch.
In order to test, we want to run two instances of Songs Service. Hence, we have run gradle clean build to generate the applications JAR file. Once you generate Jars, start the application on two different ports. For example . 8081 and 8082.

java -jar -Dserver.port=8081 songs-service.jar

// and in separate window
java -jar -Dserver.port=8082 songs-service.jar

Monitor on Admin Server

Now, go back to the Admin Server Console and you should see Songs Service with 2 instances.

Admin Server Clients - all up | amitph
Admin Server Clients – all up

Now, click on either of the instances to see details.

Spring Boot Admin Server Detailed | amitph
Spring Boot Admin Server Detailed View

You will have to actually, try and play around to see the depth of details the admin server provides.

Admin Server Notifications

Till now, you have started a Spring Boot Admin UI and also registered other Spring Boot Services as Clients. Finally, it is time to see how Spring Boot Admin is capable of sending notifications with zero code.

Spring Boot Admin has in built support for below services.

  • Email`
  • Pager Duty
  • OpsGenie
  • HipChat
  • Let’s Chat
  • Microsoft Teams
  • Telegram
  • Discord

For example, we will integrate Slack and test if the Admin Server correctly send notification about service is DOWN.

For that, you just need to let admin server know about the slack channel.

spring.boot.admin.notify.slack.webhook-url=https://hooks.slack.com/services/<Channel_WebHook>
spring.boot.admin.notify.slack.channel=test

Now, we restart the admin server and simply shutdown one of our client service. We receive a slack notification correctly.

Slack Notification | amitph
Slack Notification

Spring Boot Admin Server Security

The admin server exposes sensitive information about the clients. Therefore, it is very important to put access restrictions over it. We have already covered Spring Boot Actuator Endpoint Security. However, securing the admin server is also essential. We will cover the admin server security in three steps described below.

Secure Admin Server

First, you need to add a starter dependency of Spring Security and dependency of admin server login module.

implementation 'de.codecentric:spring-boot-admin-server-ui-login'
implementation 'org.springframework.boot:spring-boot-starter-security'

Then, add Spring Security Configuration to secure the application.

@Configuration
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {
    private final String adminContextPath;

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

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        SavedRequestAwareAuthenticationSuccessHandler successHandler = new SavedRequestAwareAuthenticationSuccessHandler();
        successHandler.setTargetUrlParameter("redirectTo");
        successHandler.setDefaultTargetUrl(adminContextPath + "/");

        http
                .authorizeRequests().antMatchers(adminContextPath + "/assets/**").permitAll()
                .antMatchers(adminContextPath + "/login").permitAll()
                .anyRequest().authenticated()
                .and().formLogin().loginPage(adminContextPath + "/login").successHandler(successHandler)
                .and().logout().logoutUrl(adminContextPath + "/logout")
                .and().httpBasic()
                .and().csrf().csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .ignoringAntMatchers(adminContextPath + "/instances", adminContextPath + "/actuator/**");
    }
}

Now, the admin server is secured. However, you need to define a username and password.

spring:
  security:
    user:
      name: "admin"
      password: "admin123"

Now try accessing the Admin Server in browser, and you should be prompted for credentials. Provide the above username/password combination to log in.

Spring Boot Admin Login Screen | amitph
Login Screen

Admin Server Credentials in Client Application

After this, you should notice that the client application is unable to register with the admin server. Because, admin server is now password protected. Therefore, you need to add the admin server credentials in client’s properties configurations.

spring:
  boot:
    admin:
      client:
        url: [http://localhost:8080]
        username: "admin"
        password: "admin123"

After this, your should see the client is able to register with the Admin Server.

Admin Server to access Client’s Secured Endpoints

Consider, the client has Secured actuator endpoints. Because of which, the admin server will only be able to access “/health” and “/info” endpoints from the client. You need to make admin server to pass clients credentials while accessing client’s secured endpoints.

For that, the clients, while registering with admin server, also need to specify username/password to access their own actuator endpoints. This is done as below.

spring:
  boot:
    admin:
      client:
        instance:
          metadata:
            user.name: client
            user.password: clientPassword

Finally, you have got everything secured. The Admin Server is secured and the Client endpoints are secured too. Also, both of them are aware of the credentials to interact with each other.

Summary

Finally, you are at the end of the Spring Boot Admin Server Tutorial. You got an introduction to Admin Server and its importance and also learnt that the admin server is a zero code server. Also you learnt, each spring boot application has to declare itself as a client and provide admin server url in configuration. After this admin server UI displays useful information about each of the client applications.

Then, you learnt the Admin server is capable of notifying many popular channels and tried an example of Slack Channel Notifications.

Finally, you learnt how to secure the admin server and restrict unwanted access.

The source code examples used in this project can be found on Github: admin-server-code and client-code.