The Paketo Java Native Image Buildpack allows users to create an image containing a GraalVM native image application.
The Java Native Buildpack is a composite buildpack and each step in a build is handled by one of it’s components. The following docs describe common build configurations. For a full set of configuration options and capabilities see the homepages of the component buildpacks.
All Java Native Image Buildpack examples will use the Paketo sample applications.
Examples assume that the root of this repository is the working directory:
git clone https://github.com/paketo-buildpacks/samples cd samples
Copied!
The pack CLI is used throughout the examples. pack
is just one of several Cloud Native Buildpack platforms than can execute builds with the Java Native Image Buildpacks. For example, Spring Boot developers may want to explore the Spring Boot Maven Plugin or Spring Boot Gradle Plugin.
Examples assume that either the Paketo Tiny or Paketo Base builder is the default builder:
pack set-default-builder paketobuildpacks/builder:tiny
Copied!
All java native image example images should return {"status":"UP"}
from the [actuator health endpoint][spring boot actuator endpoints].
docker run --rm --tty --publish 8080:8080 samples/java-native curl -s http://localhost:8080/actuator/health | jq .
Copied!
The Java Native Image Buildpack currently only supports Spring Boot applications.
For all native image builds, it is required that:
BP_BOOT_NATIVE_IMAGE
is set at build time.The version of Spring Native declared by the application may require a specific version of Spring Boot. See the Spring Native release notes for supported Spring Boot versions.
The Java Native Image Buildpack supports the same build tools and configuration options as the Java Buildpack. The build must produce an executable jar.
After compiling and packaging, the buildpack will replace provided application source code with the exploded JAR and proceed as described in Building from an Executable Jar.
Example: Building a Native image with Maven
The following command creates an image from source with maven
.
pack build samples/java-native \ --env BP_BOOT_NATIVE_IMAGE=true --path java/native-image
Copied!
An application developer may build an image from an exploded executable JAR. Most platforms will automatically extract provided archives.
Example: Building a Native image from an Executable JAR
The following command uses Maven directly to compile an executable JAR and then uses the pack
CLI to build an image from the JAR.
cd samples/java/native-image ./mvnw package pack build samples/java-native \ --env BP_BOOT_NATIVE_IMAGE=true --path java/native-image/target/demo-0.0.1-SNAPSHOT.jar
Copied!
The resulting application image will be identical to that built in the “Building a Native image with Maven” example.
The GraalVM Buildpack will provide the GraalVM JDK, including the native-image
utility (the Native image builder), and the Substrate VM.
The Spring Boot Native Image Buildpack uses native-image
to compile the Java bytecode into a standalone executable. The Spring Boot Native Image Buildpack relies on Spring Native, a GraalVM Feature, to configure the native image build. The application must include Spring Native as a dependency; if it does not the build will fail.
Note: The native-image
build is a memory intensive process and may be slow if insufficient memory is provided. From the prerequisites in the Spring Native reference docs:
“On Mac and Windows, it is recommended to increase the memory allocated to Docker to at least 8G (and potentially to add more CPUs as well) since native-image compiler is a heavy process. See this Stackoverflow answer for more details. On Linux, Docker uses by default the resources available on the host so no configuration is needed.”
The exact substrate VM version that was contributed to a given image can be read from the Bill-of-Materials.
Example Inspecting the JRE Version
Given an image named samples/java-native
built from one of examples above, the following command will print the exact version of the installed substrate VM.
pack inspect-image samples/java-native --bom | jq '.local[] | select(.name=="native-image-svm") | .metadata.version'
Copied!
The following environment variable configures the JVM version at build-time.
BP_JVM_VERSION
BP_JVM_VERSION=8
or BP_JVM_VERSION=8.*
the buildpack will install the latest patch releases of the Java 8 JDK and JRE.The Java Native Image Buildpack contains the Spring Boot Buildpack and provides the same Spring Boot features as the Java Buildpack.
The Java Native Image Buildpack will contribute a default process type that starts the application.
Example: Running the Default Process
Execute the following commands to start the default process type using a samples/java-native
image built from any previous example command.
docker run --rm --publish 8080:8080 samples/java-native curl -s http://localhost:8080/actuator/health
Copied!
Additional arguments can be provided to the application using the container [CMD
][oci config]. In Kubernetes set CMD
using the args
field on the [container][kubernetes container resource] resource.
Example: Setting the Server Port
Execute the following command passes an additional argument to application start command, setting the port to 8081
.
docker run --rm --publish 8081:8081 samples/java-native --server.port=8081 curl -s http://localhost:8081/actuator/health
Copied!
The following component buildpacks compose the Paketo Java Native Image Buildpack.
Buildpack | Required/Optional | Responsibility |
---|---|---|
Paketo GraalVM Buildpack | Required | Provides the GraalVM JDK and Native Image Substrate VM. |
Paketo Gradle Buildpack | Optional | Builds Gradle-based applications from source. |
Paketo Leiningen Buildpack | Optional | Builds Leiningen-based applications from source. |
Paketo Maven Buildpack | Optional | Builds Maven-based applications from source. |
Paketo SBT Buildpack | Optional | Builds SBT-based applications from source. |
Paketo Executable JAR Buildpack | Optional | Contributes a process Type that launches an executable JAR. |
Paketo Spring Boot Buildpack | Optional | Contributes configuration and metadata to Spring Boot applications. |
Paketo Spring Boot Native Image Buildpack | Required | Creates a native image from a Spring Boot application. |
Paketo Procfile Buildpack | Optional | Allows the application to define or redefine process types with a Procfile |
Paketo Environment Variables Buildpack | Optional | Contributes arbitrary user-provided environment variables to the image. |
Paketo Image Labels Buildpack | Optional | Contributes OCI-specific and arbitrary user-provided labels to the image. |
Last modified: February 19, 2021