Migrating a Spring Boot app to a native image – how is it done?
Get to know GraalVM native image support and migrate a complex Spring Boot app – the RealWorld application, which goes well beyond a basic 'Hello World' example.
This time we’re looking at GraalVM Native Image Support. Plenty of articles have been written about this feature. Sadly, many of them are out of date, because native images for spring boot apps used to be generated with the spring-native module, which has since been deprecated. On top of that, most materials demonstrate native image generation on very basic apps, which may conceal certain details. Here, we’ll show how to perform this migration for something larger than hello world.
What is the plan?
As mentioned, our goal is to show how to migrate a spring boot app to a native application. You might be wondering, “Why would I want my app to run as a native image?”. Well… the two main motivations are quicker application startup (who wouldn’t want a production application that starts in a few milliseconds) and a smaller memory footprint. This approach has its downsides too, and as we work through the migration, you’ll see for yourself where the biggest pain points are. But let’s get back to the plan.
To begin with, we need an application to migrate, and it must be a real one rather than a trivial hello world. An overly simple application can conceal some crucial details. Instead of writing it from scratch, we’ll take one of the RealWorld applications, which relies on many spring boot modules. This lets us concentrate solely on the changes required to compile the application to a native one. There’s a perfect candidate for the migration: a community implementation running on java 17 and spring boot 3.0. We’ll adapt this application so that a native image of it can be built. The application relies on many modules that are common in our projects, such as spring-boot-starter-jpa, spring-boot-starter-security, spring-boot-starter-web, hibernate, the h2 database and smaller tools like Lombok, so it should be enough to show which problems may come up during the migration.
After that, we’ll walk through the migration together, presenting best practices and ways to solve some of the migration problems you might encounter in your own applications.
Before migration
If you intend to build your spring boot application as a native image, begin by going through this document on known limitations to check whether your application relies on anything listed there. If something in your application isn’t supported yet, you can either wait for official support or replace that particular thing with something else. For instance, since log4j2 doesn’t work in native images, you should switch to logback before you even attempt to build the native image.
Migration steps
The following sections walk you through the migration process step by step.
Structure of our application
First, let’s get a bit familiar with how the application is structured:
├── api
├── build
├── build.gradle.kts
├── database
├── gradle
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src
- api - holds the open api definition, requests to our api as a postman collection, and a small script that tests the api using newman; we’ll use it to test the application
- build - the directory containing all the build artifacts
- build.gradle.kts, settings.gradle.kts - the gradle project configuration written in kotlin dsl (by the way, were you aware that kotlin dsl is now the default for new gradle builds?)
- gradle, gradlew, gradlew.bat - the gradle wrapper
- database - the directory holding the database schema
- src - the application’s source code
Prerequisites
To build native images with the Native Build Tools, we need a GraalVM distribution. Please, please manage your distributions with sdkman rather than downloading them by hand. We’ll be using the GraalVM-based Liberica distribution, version 22.3.2.r17
$ sdk install java 22.3.2.r17-nik
$ sdk use java 22.3.2.r17-nik
Run your application with AOT enabled
Rather than going straight to native-image compilation, we should first check that the application runs correctly on a JVM using the AOT-generated initialization code. This way, potential errors surface much sooner than they would if we ran the entire native image compilation process.
To start, we have to turn on generation of the initialization code. Why? As you probably know, spring does a lot of work at application startup, and none of that work can happen at runtime if you want a native image. That’s the reason for the initialization code generation phase: everything a regular spring application does at runtime gets translated into code generated at build time.
Ok, to generate this code with gradle, all we have to do is add the org.graalvm.buildtools.native plugin to the plugins section:
plugins {
java
id("com.diffplug.spotless") version "6.18.0"
id("org.springframework.boot") version "3.0.5"
id("io.spring.dependency-management") version "1.1.0"
id("org.graalvm.buildtools.native") version "0.9.20"
}
Next, we build the application:
$ ./gradlew build
Aaaand here comes our first minor error:
Execution failed for task ':spotlessJavaCheck'.
> The following files had format violations:
build/generated/aotSources/com/github/gavlyukovskiy/boot/jdbc/decorator/DataSourceDecoratorAutoConfiguration__BeanDefinitions.java
Apparently, spotless checks my generated classes in the build directory too… A small tweak to the spotless configuration turns that off:
spotless {
java {
target("src/main/java/**/*.java")
palantirJavaFormat()
indentWithSpaces()
Now we can run ./gradlew build once more. The application is now built with the AOT-generated code included. Let’s try running it using the AOT-generated initialization code, which is done by enabling the spring.aot.enabled property.
$ java -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar
Right at the start of the logs, we should see that the AOT-processed application is starting:
Starting AOT-processed RealworldApplication using Java 17.0.7 with PID....
To make sure everything is fine, we can run the api tests:
$ ./api/run-api-tests.sh
Everything seems to work. So far, so good.
Let’s go native
First try
Once your application runs smoothly with AOT-generated code, we can attempt to build it in native mode. Buuuut that’s probably not what you should do first. Here’s why. To kick off native compilation, all we need to run is:
$ ./gradlew nativeCompile
Time for a coffee… The process takes a few minutes.
source
BUILD SUCCESSFUL in 4m 24s
At last, our native image is ready!!!! Let’s launch it!
$ ./build/native/nativeCompile/realworld
And it crashed…
Caused by: java.lang.ExceptionInInitializerError: null
at com.github.gavlyukovskiy.boot.jdbc.decorator.p6spy.P6SpyConfiguration.init(P6SpyConfiguration.java:112) ~[realworld:na]
So somewhere among our dependencies, there’s code that failed to initialize some variables. That leaves a null object, which gets accessed further on in the code – hence the NullPointerException. Why didn’t initialization happen? Let’s go back to square one…
The main reason we want a native application is that it gives us two great features: quick application startup and a small memory footprint. To deliver them, GraalVM operates under a closed-world assumption, where all code must be known at build time. Because of that, the final application contains only the classes our application actually uses (small memory footprint). In addition, during compilation the native-image compiler also knows which objects get created when the application starts, and it prepopulates a heap with them – which is where the fast startup comes from.
Back to the problem. At build time, the native-image compiler couldn’t detect that we were loading some classes dynamically, so it left them out of the final application. The code responsible for loading those classes set the variable to null, and at runtime we ended up with a NullPointerException.
How do we fix it? Since the class is accessed via reflection, we have to tell the compiler to load it at build time and make it available to our application at runtime. To do that, we must define our reachability metadata as JSON files. Yeah… that’s doable, but what are we supposed to put in these files? Do we have to analyze every library to figure out what it does?!
It took 5 minutes of building to get the first error. We could try writing this reachability metadata ourselves, which would certainly take longer than 5 minutes, and then we’d have to recompile the application, run it, fix errors, recompile, run it, fix errors… Who has time for that? Now you see why this isn’t the way to go. For applications this complex, defining all the reachability metadata manually is close to impossible. There’s a better approach.
Run tracing agent to collect reachability metadata
Rather than writing the reachability metadata by hand, we can run the application with a tracing agent attached, which gathers all of it for us. However, since the metadata is collected at runtime, we have to make sure every code path in the application gets executed, so the agent collects everything that’s needed and the native image holds no surprises when we run it.
Once more, we build the application as a jar file.
$ ./gradlew build
Then we run the application with native-image-agent attached:
$ java -agentlib:native-image-agent=config-output-dir=./src/main/resources/META-INF/native-image/ -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar
Note that we passed the configuration option config-output-dir=./src/main/resources/META-INF/native-image/ to the agent: once the reachability metadata lands in this directory, the native image compiler picks it up automatically when we run ./gradlew nativeCompile.
Next, we need to exercise the application so the agent can gather all the reachability metadata. For this, we can use the api tests located in the ./api directory.
$ ./api/run-api-tests.sh
After shutting the application down, we can see plenty of configuration in the JSON files in the src/main/resources/META-INF/native-image directory. Just imagine writing all of that manually…
Build a native image
We’re now set to build the native image. Here we go!
./gradlew nativeCompile
source
BUILD SUCCESSFUL in 4m 46s
Now let’s launch it!
$ ./build/native/nativeCompile/realworld
It’s alive!!! At last, it’s running. Look how quickly it started! Half a second for a spring boot application? Amazing!
Started RealworldApplication in 0.453 seconds (process running for 0.463)
Hold on, though – let’s run the API tests to make sure everything is OK.
$ ./api/run-api-tests.sh
Sadly, there are some errors…
| | executed | failed |
|--------------------|----------|--------|
| iterations | 1 | 0 |
| requests | 32 | 0 |
| test-scripts | 48 | 2 |
| prerequest-scripts | 18 | 0 |
| assertions | 194 | 69 |
Hibernate seems to be causing trouble:
Caused by: org.hibernate.HibernateException: Generation of HibernateProxy instances at runtime is not allowed when the configured BytecodeProvider is 'none'; your model requires a more advanced BytecodeProvider to be enabled.
Ok, so hibernate attempted to generate proxies – for dirty checking or lazy initialization, for example – but that isn’t possible in a native image, because the entire hibernate bytecode provider has to be turned off. Bytecode manipulation at runtime is off the table.
A code snippet from org.springframework.orm.jpa.vendor.SpringHibernateJpaPersistenceProvider
static {
if (NativeDetector.inNativeImage()) {
System.setProperty(Environment.BYTECODE_PROVIDER, Environment.BYTECODE_PROVIDER_NAME_NONE);
}
}
That leaves us with just one option: turn off hibernate proxy generation at runtime as well, and generate all the proxies at build time instead. There’s a dedicated gradle plugin for that: Hibernate Enhance Plugin. Its options are explained in an excellent article by Vlad Mihalcea. Generating this code at build time requires two changes in build.gradle.kts. First, add this to the plugins:
id("org.hibernate.orm") version ("6.2.2.Final")
then configure the code enhancements:
hibernate {
enhancement {
enableDirtyTracking.set(true)
enableLazyInitialization.set(true)
enableExtendedEnhancement.set(false)
}
}
We can now go through the full cycle again to verify that everything works: build a standard application, run it with native-image-agent, run the tests to gather reachability metadata, and at the end build the native image.
Before that, however, one more step is needed to sort out all the hibernate issues. The bytecode provider (used by hibernate) also has to be disabled when running the regular application. There are two reasons: we want the application running with the agent to behave exactly as it will in a native environment, and we want the regular application to work the same way as the native one, so that errors that might happen in a native environment show up much sooner while testing the regular application.
For this, we can place hibernate.properties in src/main/resources with the configuration below:
hibernate.bytecode.provider=none
hibernate.bytecode.use_reflection_optimizer=false
The second line turns off the ReflectionOptimizer, since without disabling it our tests fail with this exception:
org.hibernate.HibernateException: Using the ReflectionOptimizer is not possible when the configured BytecodeProvider is 'none'. Disable hibernate.bytecode.use_reflection_optimizer or use a different BytecodeProvider
Ok, time to go through the full cycle (build a standard application, run it with native-image-agent, run tests to gather reachability metadata, and build a native image) one more time…
source
We launch the application aaaand there’s yet another error… This is exhausting…
Caused by: com.oracle.svm.core.jdk.UnsupportedFeatureError: No classes have been predefined during the image build to load from bytecodes at runtime.
at org.graalvm.nativeimage.builder/com.oracle.svm.core.util.VMError.unsupportedFeature(VMError.java:89) ~[na:na]
at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.PredefinedClassesSupport.throwNoBytecodeClasses(PredefinedClassesSupport.java:76) ~[na:na]
at org.graalvm.nativeimage.builder/com.oracle.svm.core.hub.PredefinedClassesSupport.loadClass(PredefinedClassesSupport.java:130) ~[na:na]
at java.base@17.0.7/java.lang.ClassLoader.defineClass(ClassLoader.java:294) ~[realworld:na]
at net.bytebuddy.utility.dispatcher.JavaDispatcher$DynamicClassLoader.invoker(JavaDispatcher.java:1383) ~[na:na]
This error says that the enhancer plugin manipulates bytecode at runtime. But runtime bytecode manipulation isn’t allowed – bytebuddy is turned off. So how do we deal with this?
The way around it is one of GraalVM’s experimental features: Support for Predefined Classes. We’ll therefore adjust the command that runs the application with native-image-agent.
Here’s the updated version:
$ java -agentlib:native-image-agent=config-output-dir=./src/main/resources/META-INF/native-image/,**experimental-class-define-support** -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar
With this, the native-image-agent stores some bytecode as reachability metadata in the src/main/resources/META-INF/native-image directory, and we can attempt to build the application.
If we do, though, JaCoCo causes trouble this time. JaCoCo is a test coverage analyzer that works by instrumenting bytecode. Since we now generate bytecode inside ./src/main/resources, it starts analyzing that code as well and throws an error saying classes with the same name have already been analyzed (one class came from the regular sources, the other from the reachability metadata). The simplest workaround is to place the generated code elsewhere, but then native-image has to be reconfigured to read the reachability metadata from a different directory.
Let’s create an aot directory in the project root and set it as the native-image-agent output directory
$ java -agentlib:native-image-agent=config-output-dir=**./aot/META-INF/native-image/**,experimental-class-define-support -Dspring.aot.enabled=true -jar ./build/libs/realworld.jar
Next, the aot directory has to be added to the classpath of the native-image tool. We do that in build.gradle.kts
graalvmNative {
binaries {
names.forEach { binaryName ->
named(binaryName){
classpath("./aot/")
}
}
}
}
This adds the aot directory to the classpath of every binary – in our case main and test.
We’re ready to build the application now. Keep in mind that the full cycle has to be repeated. Fancy a second coffee?
After yet another build cycle (I’ve lost count of how many times I went through it), we can run the application with the api tests, and everything appears to work! The application starts in half a second – a great success.
Started RealworldApplication in 0.448 seconds (process running for 0.456)
We’re not done yet, though. To truly confirm that the application works correctly as a native image, the unit tests have to run in the native environment. All it takes is this simple command.
./gradlew nativeTest
The tests appear to fail because we use mockito – remember the known limitations?
Once mockito and a few hamcrest matchers are removed, we can rerun the native tests, and this time everything passes. I promise!
What a long journey that was…
Final thoughts
As you’ve seen, real world spring boot applications can run as native images, but it’s not easy, and getting something that works takes a lot of time. This entire flow should also be integrated into the CI pipeline, which may prove challenging as well.
Here’s a quick comparison of our application running as a native image versus as a regular Java application.
| | startup time | occupied memory (rss) |
|---------------------|--------------|-----------------------|
| regular application | ~3 seconds | 500 Mb |
| native application | ~0.5 second | 200 Mb |
For larger applications, the gap in startup time and memory usage will be even wider.
The numbers look fantastic, so what’s the catch? Switching to native image has these main drawbacks:
- Building a native image is far slower than a regular build – a regular application builds in just ~20 seconds with the temurin distribution of Java 17, so 5 minutes versus 20 seconds is an enormous gap,
- not every library works in a native environment yet (known limitations),
- there’s no support for JVMTI, Java Agents, JMX or JFR. Only kernel features remain for inspecting what’s going on inside the application. This also means jvm heap metrics gathered via MXBeans (by micrometer, for instance) aren’t available. In general, no metrics collected from MXBeans are available,
- in the community edition of GraalVM, serialGC is the only garbage collector on offer. G1 GC can be used, but only in the enterprise edition of GraalVM, which comes with the Oracle Java SE Subscription,
- there’s no JIT, so your application’s throughput will be lower.
That’s all, folks. I hope this article helps you migrate to native image – just remember to “pick your fighter wisely”
Time to close all my open tabs… Feels great, doesn’t it?