Giters

yubb-ai / unofficial-gpt4

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Spring Boot Native Image Microservice

This demo shows how to build, package, and run a simple Spring Boot 3 microservice from a JAR file with the GraalVM JDK, and from a native executable with GraalVM Native Image. The benefits of using a native executable are faster start-up times and reduced memory consumption. It also demonstrates how to run the application and build the native executable within a Docker container.

There are two ways to generate a native executable from a Spring Boot application:

Sample Application

The example is a minimal REST-based API application, built on top of Spring Boot 3. It consists of:

  • com.example.jibber.JibberApplication: the main Spring Boot class. It is also a REST controller which serves as an entry-point for HTTP requests.
  • com.example.jibber.Jabberwocky: a utility class that implements the logic of the application.

If you call the HTTP endpoint, /jibber, it will return some nonsense verse generated in the style of the Jabberwocky poem, by Lewis Carroll. The program achieves this by using a Markov Chain to model the original poem (this is essentially a statistical model). This model generates a new text. The example application provides the text of the poem, then generates a model of the text, which the application then uses to generate a new text that is similar to the original text. The application uses the RiTa library as an external dependency to build and use Markov Chains.

By default, the demo uses the Native Build Tools Maven plugin to perform the tasks. If you would like to run this demo using BuildPacks, the build configuration is provided for you too.

Prerequisites

  1. Download and install the latest GraalVM JDK using SDKMAN!.

    sdk install java 21.0.2-graal

  2. (Optional) Install and run a Docker-API compatible container runtime such as Rancher Desktop, Docker, or Podman. If you are using Docker, configure it to allow non-root user access if you are on Linux.

  3. Download the demos repository or clone it as follows:

    git clone https://github.com/graalvm/graalvm-demos

  4. Change directory to the demo subdirectory:

    cd spring-native-image

Application JAR

Build and Run as a JAR

This demo is built using Maven.

  1. Build the application on top of a JVM:

    ./mvnw clean package

    It generates a runnable JAR file that contains all of the application’s dependencies and also a correctly configured MANIFEST file.

  2. Run the application JAR and put it into the background by appending &:

    java -jar ./target/benchmark-jibber-0.0.1-SNAPSHOT.jar &

  3. Open the application http://localhost:8080/jibber in a browser, or call the endpoint using curl:

    curl http://localhost:8080/jibber

    It should generate a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.

  4. Bring the application to the foreground using fg, and then enter <CTRL-c> to terminate the application.

(Optional) Containerize the JAR

The following steps (5-8) show how you can easily containerize the JAR built in the previous step using the Oracle GraalVM JDK container image container-registry.oracle.com/graalvm/jdk:17-ol8.

  1. Run this command to package the JAR as a Docker container:

    docker build -f Dockerfiles/Dockerfile.jvm --build-arg APP_FILE=benchmark-jibber-0.0.1-SNAPSHOT.jar -t jibber-benchmark:jvm.0.0.1-SNAPSHOT .

  2. Run the container:

    docker run --rm --name graal -p 8080:8080 jibber-benchmark:jvm.0.0.1-SNAPSHOT

  3. Open the application http://localhost:8080/jibber in a browser, or from a new terminal window, call the endpoint using curl:

    curl http://localhost:8080/jibber

    You should get a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.

  4. To stop the application, first get the container id using docker ps, and then run:

    docker rm -f <container_id>

Native Executable

Recap what you have so far: built a Spring Boot application with an HTTP endpoint, and successfully containerised it. Now you will look at how you can create a native executable from your application.

Spring Boot 3's built-in support for GraalVM Native Image makes it easy to compile a Spring Boot 3 application into a native executable.

This native executable not only starts faster but also uses far fewer resources than running the application as a JAR file.

You can use the native-image tool from the GraalVM installation to build a native executable. In this example, you'll use the GraalVM Native Build Tools for Maven to build a native executable.

Default Native Build Configuration

Make sure you’re using spring-boot-starter-parent in order to inherit the out-of-the-box native profile, and the org.graalvm.buildtools:native-maven-plugin plugin.

You should see the following in the Maven pom.xml file:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
<build>
    <plugins>
        <plugin>
            <groupId>org.graalvm.buildtools</groupId>
            <artifactId>native-maven-plugin</artifactId>
        </plugin>
        ...
    </plugins>
</build>

The out-of-the-box native profile has GraalVM Reachability Metadata enabled by default.

Build and Run as a Native Executable

With the out-of-the-box native profile active, you can invoke the native:compile goal to trigger native-image compilation.

  1. Run the following command:

    ./mvnw native:compile -Pnative

    The native profile is used to generate a native executable for your platform. The native executable is called benchmark-jibber and is generated in the target directory.

    Alternatively, to build using BuildPacks, run the ./mvnw spring-boot:build-image -Pnative command to generate a native executable. For more information about using BuildPacks to create a native executable, see Building a Native Image Using Buildpacks.

  2. Run the native executable and put it into the background by appending &:

    ./target/benchmark-jibber &

  3. Open the application http://localhost:8080/jibber in a browser, or call the endpoint using curl:

    curl http://localhost:8080/jibber

    You should get a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.

  4. Bring the application to the foreground using fg, and then enter <CTRL-c> to terminate the application.

From the log output, notice how much quicker the native executable version of this Spring Boot application starts compared to the JAR. The native executable also uses fewer resources than running from a JAR file.

Additional Native Build Configuration

Notice that you can pass additional configuration arguments to the underlying native-image build tool using the <buildArgs> section. In individual buildArg tags, you can pass parameters exactly the same way as you do from a command line. This lets you use all of the parameters that work with the native-image tool from Maven.

Add the following snippet to the pom.xml to pass additional arguments to enable verbose output, quick build mode, etc. over and above the out-of-the-box native profile.

<profiles>
   <profile>
      <id>native</id>
      <build>
         <plugins>
            <plugin>
               <groupId>org.graalvm.buildtools</groupId>
               <artifactId>native-maven-plugin</artifactId>
               <!--<version>0.9.28</version>-->
               <configuration>
                  <verbose>true</verbose>
                  <quickBuild>true</quickBuild>
                  <buildArgs combine.children="append">
                     <arg>-H:+ReportExceptionStackTraces</arg>
                  </buildArgs>
               </configuration>
            </plugin>
         </plugins>
      </build>
   </profile>
</profiles>

Build and Run as a Native Executable

Let's rebuild the native executable with the additional configuration arguments.

  1. Run the following command:

    ./mvnw native:compile -Pnative

    With the quick build mode enabled, it takes less time to build the native executable. This mode should be used in development for faster builds.

  2. Run the native executable and put it into the background by appending &:

    ./target/benchmark-jibber &

  3. Open the application http://localhost:8080/jibber in a browser, or call the endpoint using curl:

    curl http://localhost:8080/jibber

    You should get a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.

  4. Bring the application to the foreground using fg, and then enter <CTRL-c> to terminate the application.

From the log output, notice how much quicker the native executable version of this Spring Boot application starts compared to the JAR. The native executable also uses fewer resources than running from a JAR file.

(Optional) Containerize the Native Executable on Linux

The following steps (5-8) are for Linux only.

  1. On Linux, you can easily containerise the native executable using the following command:

    docker build -f Dockerfiles/Dockerfile.native --build-arg APP_FILE=benchmark-jibber -t jibber-benchmark:native.0.0.1-SNAPSHOT .

  2. Run the application:

    docker run --rm --name native -p 8080:8080 jibber-benchmark:native.0.0.1-SNAPSHOT

  3. Open the application http://localhost:8080/jibber in a browser, or from a new terminal window, call the endpoint using curl:

    curl http://localhost:8080/jibber

    It should generate a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.

  4. To stop the application, first get the container id using docker ps, and then run:

    docker rm -f <container_id>

(Optional) Use Multistage Docker Builds to Build a Native Image and Package it in a Lightweight Container

The following steps (9-12) are for all platforms - MacOS, Windows, and Linux.

For MacOS and Windows, to build a Docker image containing your native executable, you need to build the native executable inside a Docker container. To do this, we've provided a multistage Docker build file.

  1. Run this command to build the native executable within a Docker container:

    docker build -f Dockerfiles/Dockerfile -t jibber-benchmark:native.0.0.1-SNAPSHOT .

  2. Run the application:

    docker run --rm --name native -p 8080:8080 jibber-benchmark:native.0.0.1-SNAPSHOT

  3. Open the application http://localhost:8080/jibber in a browser, or from a new terminal window, call the endpoint using curl:

    curl http://localhost:8080/jibber

    It should generate a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.

  4. To stop the application, first get the container id using docker ps, and then run:

    docker rm -f <container_id>

Measure the Performance of the Application and Metrics

The Spring Actuator dependency has been added to the project, along with support for Prometheus. If you want to test the performance of either the JVM version, or the native executable version of the application, you can make use of the Prometheus support. If you are hosting the application locally, it is available on port 8080:

http://localhost:8080/actuator/prometheus

Related Documentation

About

License:MIT License

Languages

Language:Java 94.0%Language:Batchfile 6.0%