13.4.1 Microservices as GraalVM native images

Getting Started with Micronaut and Graal

Since Micronaut 2.2, any Micronaut application is already ready to be built into a native image using the Micronaut Gradle or Maven plugins, to get started simply create a new application:

Creating a Graal Native Microservice

$ mn create-app hello-world

You can use --build maven for a Maven build.

Building a Native Image Using Docker

To build your native image using Gradle and Docker simply run:

Building a Native Image with Docker and Gradle

$ ./gradlew dockerBuildNative

To build your native image using Maven and Docker simply run:

Building a Native Image with Docker and Maven

$ ./mvnw package -Dpackaging=docker-native

Building a Native Image Without Using Docker

To build your native image without using Docker you need to install GraalVM SDK via the Getting Started instructions or using Sdkman!:

Installing GraalVM 21.0.0 with SDKman

$ sdk install java 21.0.0.r8-grl # or 21.0.0.r11-grl if you want to use JDK 11
$ sdk use java 21.0.0.r8-grl

The native-image tool was extracted from the base GraalVM distribution. Currently, it is available as an early adopter plugin. To install it, run:

Installing native-image tool

$ gu install native-image

Now you can build a native image with Gradle simply by running the nativeImage task:

Creating native image with Gradle

$ ./gradlew nativeImage

The native image will be built to the build/native-image directory.

To create a native image with Maven and the Micronaut Maven plugin use native-image as the packaging format:

Creating native image with Maven

$ ./mvnw package -Dpackaging=native-image

Which will build the native image into the target directory.

You can then run the native image from the directory you built it to.

Run native image

$ ./hello-world

Understanding Micronaut and Graal

Micronaut itself does not rely on reflection or dynamic classloading so works automatically with GraalVM native, however certain third party libraries used by Micronaut may require additional input about uses of reflection.

Micronaut includes an annotation processor that helps to handle generating the reflection-config.json and resource-config.json metadata files that are automatically picked up by the native-image tool:

annotationProcessor("io.micronaut:micronaut-graal")

<annotationProcessorPaths>
    <path>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-graal</artifactId>
    </path>
</annotationProcessorPaths>

This processor will generate: - A reflection-config.json file in the META-INF/native-image directory in your build classes directory (target/classes with Maven and typically build/classes/java/main with Gradle). - A native-image.properties file to read this configuration for all classes annotated with either @Introspected or @TypeHint. - A resource-config.json file also in the META-INF/native-image directory in your build classes directory containing all the files in the src/main/resources file.

For example the following class:

package example;
import io.micronaut.core.annotation.*;
@Introspected
class Test {
    ...
}

The above example will result in the public methods and declared constructors of example.Test being included in reflection-config.json.

If you have more advanced requirements and only wish to include certain fields or methods, you can use @ReflectiveAccess instead which can be present on any constructor, field or method to include only the specific field, constructor or method.

Stating with Micronaut 2.0, as the framework generates automatically the file resource-config.json, if you want to include your own additional resources you can provide them in src/main/graal/resource-config.json and they will automatically added to the generated file.

Adding Additional Classes for Reflective Access

To inform Micronaut of additional classes that should be included in the generated reflect.json file at compilation time you can either annotate a class with @Introspected or @TypeHint.

The former will generate a compile time introspection as well as allowing reflective access and the latter will only allow reflective access and is typically used on a module or Application class to include classes that are needed reflectively. For example, the following is taken from Micronaut’s Jackson module:

@TypeHint(
        value = { (1)
                PropertyNamingStrategy.UpperCamelCaseStrategy.class,
                ArrayList.class,
                LinkedHashMap.class,
                HashSet.class
        },
        accessType = TypeHint.AccessType.ALL_DECLARED_CONSTRUCTORS (2)
)

Generating Native Images

GraalVM’s native-image command is used to generate native images. You can use this command manually to generate your native image. An example can be seen below.

The native-image command

native-image --class-path build/libs/hello-world-0.1-all.jar (1)

Once the image has been built you can run the application using the native image name:

Running the Native Application

$ ./hello-world
15:15:15.153 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 14ms. Server Running: http://localhost:8080

As you can see the advantage of having a native image is startup completes in milliseconds and memory consumption does not include the overhead of the JVM (a native Micronaut application runs with just 20mb of memory).