Skip to content

01-spring-boot-admin-4.md

Latest commit

 

History

History
310 lines (221 loc) · 8.32 KB

01-spring-boot-admin-4.md

File metadata and controls

310 lines (221 loc) · 8.32 KB
sidebar_custom_props
icon
arrow-up

To Spring Boot Admin 4

This guide covers the breaking changes, deprecated features, and migration steps required to upgrade from Spring Boot Admin 3.x to 4.x.

Prerequisites

Before upgrading to Spring Boot Admin 4, ensure your application meets these requirements:

  • Spring Boot 4.0+ - Spring Boot Admin 4 requires Spring Boot 4.0 or higher
  • Java 17+ - Minimum Java version is 17
  • Review dependencies - Check that all third-party dependencies are compatible with Spring Boot 4

:::tip Java Version Compatibility Spring Boot Admin strives to support the same Java baseline version as the corresponding Spring Boot version. This means:

  • Spring Boot Admin 4.x supports the same minimum Java version as Spring Boot 4.x (Java 17+)
  • Future Spring Boot Admin releases will align with Spring Boot's Java requirements

Always check the Spring Boot documentation for the supported Java versions of your Spring Boot version. :::

Breaking Changes

1. Nullable Annotations Change

What Changed:

Spring Boot Admin 4 replaces Spring's nullable annotations with JSpecify annotations for better null-safety across the Java ecosystem.

Migration:

// Before (Spring Boot Admin 3.x)
import org.springframework.lang.Nullable;

public class MyService {
    public void process(@Nullable String value) {
        // ...
    }
}
// After (Spring Boot Admin 4.x)
import org.jspecify.annotations.Nullable;

public class MyService {
    public void process(@Nullable String value) {
        // ...
    }
}

Action Required:

If you extend Spring Boot Admin classes or implement interfaces using @Nullable annotations:

  1. Add JSpecify dependency to your pom.xml:
<dependency>
    <groupId>org.jspecify</groupId>
    <artifactId>jspecify</artifactId>
    <version>1.0.0</version>
</dependency>
  1. Update your imports from org.springframework.lang.Nullable to org.jspecify.annotations.Nullable

2. HTTP Client Configuration Changes

What Changed:

Spring Boot Admin 4 modernizes HTTP client usage:

  • Client: Now uses RestClient exclusively (replaces WebClient autoconfiguration)
  • Server: Uses WebClient for instance communication and RestTemplate for notifiers

Migration:

For Admin Client

The client autoconfiguration now provides RestClient instead of WebClient:

// Before (Spring Boot Admin 3.x)
@Bean
public WebClient.Builder webClientBuilder() {
    return WebClient.builder()
        .defaultHeader("X-Custom-Header", "value");
}
// After (Spring Boot Admin 4.x)
@Bean
public RestClient.Builder restClientBuilder() {
    return RestClient.builder()
        .defaultHeader("X-Custom-Header", "value");
}

For Admin Server

No changes required - the server continues using WebClient for instance communication:

// Server-side customization (unchanged)
@Bean
public InstanceWebClient instanceWebClient(WebClient.Builder builder) {
    return InstanceWebClient.builder(builder)
        .connectTimeout(Duration.ofSeconds(5))
        .build();
}

Action Required:

  • If you customize the client's HTTP configuration, migrate from WebClient.Builder to RestClient.Builder
  • Update any custom beans that depend on WebClient in client applications

3. Property Rename: prefer-ip Removed

What Changed:

The property spring.boot.admin.client.instance.prefer-ip has been removed in favor of the more flexible spring.boot.admin.client.instance.service-host-type.

Migration:

# Before (Spring Boot Admin 3.x)
spring:
  boot:
    admin:
      client:
        instance:
          prefer-ip: true
# After (Spring Boot Admin 4.x)
spring:
  boot:
    admin:
      client:
        instance:
          service-host-type: IP  # Options: IP, HOST_NAME, CANONICAL_HOST_NAME

Available Options:

Value Description
IP Use IP address (equivalent to old prefer-ip: true)
HOST_NAME Use hostname (equivalent to old prefer-ip: false)
CANONICAL_HOST_NAME Use canonical hostname

Action Required:

  • Search your configuration files for prefer-ip
  • Replace with service-host-type: IP (if prefer-ip: true) or service-host-type: HOST_NAME (if prefer-ip: false)

4. Jolokia Compatibility

What Changed:

Spring Boot Admin 4 manages the Jolokia Spring Boot integration org.jolokia:jolokia-support-springboot 2.5.x, which supports Spring Boot 4.

Action Required:

  • Jolokia 2.5.x is compatible with Spring Boot 4 and Spring Boot Admin 4.
  • If you use JMX-Bean Management, you must add the appropriate Jolokia Spring Boot support dependency to each client application, matching the client's Spring Boot major version (for example, jolokia-support-springboot for Spring Boot 4+ clients and jolokia-support-springboot3 for Spring Boot 3.x clients). For Spring Boot 2.x applications managed by Spring Boot Admin 2 or 3, use jolokia-core as described in the corresponding SBA version documentation. See the JMX-Bean Management section for the exact dependency coordinates per Spring Boot version.

Migration Checklist

Follow these steps to ensure a smooth upgrade:

Step 1: Update Dependencies

Update your pom.xml:

<properties>
    <spring-boot.version>4.0.0</spring-boot.version>
    <spring-boot-admin.version>4.0.0</spring-boot-admin.version>
</properties>

<dependencies>
    <!-- Admin Server -->
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-starter-server</artifactId>
        <version>${spring-boot-admin.version}</version>
    </dependency>

    <!-- Admin Client -->
    <dependency>
        <groupId>de.codecentric</groupId>
        <artifactId>spring-boot-admin-starter-client</artifactId>
        <version>${spring-boot-admin.version}</version>
    </dependency>
</dependencies>

Step 2: Update Configuration

  1. Replace prefer-ip property:
# Find and replace in all configuration files
grep -r "prefer-ip" src/main/resources/
# Replace with service-host-type
  1. Review HTTP client customizations:
# Check for WebClient customizations in client apps
grep -r "WebClient.Builder" src/main/java/

Step 3: Update Code

  1. Update nullable annotations:
# Find all Spring nullable imports
find src -name "*.java" -exec grep -l "org.springframework.lang.Nullable" {} \;

# Replace with JSpecify
sed -i 's/org.springframework.lang.Nullable/org.jspecify.annotations.Nullable/g' <files>
  1. Migrate client HTTP configuration:

Review and update any beans creating WebClient.Builder for the Admin Client.

Step 4: Test

  1. Start the Admin Server:
mvn spring-boot:run
  1. Register a client application
  2. Verify functionality:
    • Instance registration works
    • Health checks update correctly
    • Actuator endpoints are accessible
    • Notifications fire properly
    • JMX operations work via Jolokia

Step 5: Monitor Logs

Watch for deprecation warnings or errors:

tail -f logs/spring-boot-admin.log | grep -i "deprecat\|error\|warn"

Getting Help

If you encounter issues during the upgrade:

  1. Check the changelog: Review detailed changes in the release notes
  2. Search existing issues: GitHub Issues
  3. Ask the community: Stack Overflow with tag spring-boot-admin
  4. Report bugs: Create an issue on GitHub

Summary

Key Changes:

  • ✅ Update to Spring Boot 4.0+
  • ✅ Replace org.springframework.lang.Nullable with org.jspecify.annotations.Nullable
  • ✅ Migrate client from WebClient to RestClient
  • ✅ Change prefer-ip to service-host-type

Most applications can upgrade with minimal code changes, primarily focused on configuration updates and dependency management.