13.4.1 Microservices as GraalVM native images

Getting Started with Micronaut and Graal

To get started creating a Microservice that can be compiled into a native image, use the graalvm feature when creating the application with the CLI:

Creating a Graal Native Microservice

$ mn create-app hello-world --features graalvm

The graalvm feature adds three important items:

1. The svm and graal dependencies to your build.gradle (or pom.xml if --build maven is used).

2. A Dockerfile which can be used to construct the native image using Docker and a script docker-build.sh to run it.

3. A native-image.properties configuration file src/main/resources/META-INF/native-image to simplify building the image.

The native-image.properties file that is generated looks something like:

Args = -H:Name=example \ (1)
       -H:Class=example.Application (2)

Building a Native Image Using Docker

To build your native image using Docker simply run:

$ ./gradlew assemble # or ./mvnw package if using Maven
$ docker build . -t hello-world
$ docker run -p 8080:8080 hello-world

Or use the provided script:

$ ./gradlew assemble # or ./mvnw package if using Maven
$ ./docker-build.sh

The provided Dockerfile is a multi-stage dockerfile which builds the project in two steps:

1. A GraalVM official image will build the native image.

2. A typical dockerfile structure will build the final image which is smaller due to layering.

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 20.2.0 with SDKman

$ sdk install java 20.2.0.r8-grl # or 20.2.0.r11-grl if you want to use JDK 11
$ sdk use java 20.2.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

Creating native image with Gradle

$ ./gradlew assemble
$ native-image -cp build/libs/hello-world-0.1-all.jar

Creating native image with Maven

$ ./mvnw package
$ native-image -cp target/hello-world-0.1-all.jar

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).