このコンテンツは選択した言語では利用できません。
Chapter 1. Compiling your Quarkus applications to native executables
As an application developer, you can use Red Hat build of Quarkus to create microservices written in Java that run on OpenShift and serverless environments. Applications compiled to native executables have small memory footprints and fast startup times.
This guide shows you how to compile the Quarkus Getting Started project into a native executable and how to configure and test the native executable. You will need the application created in Getting started with Quarkus.
Building a native executable with Red Hat build of Quarkus covers:
- Building a native executable with a single command using a container runtime such as Podman or Docker
- Creating a custom container image using the produced native executable
- Creating a container image using the OpenShift Docker build strategy
- Deploying the Quarkus native application to OpenShift
- Configuring the native executable
- Testing the native executable
Prerequisites
Have OpenJDK 11 or 17 installed and the
JAVA_HOMEenvironment variable set to specify the location of the Java SDK.- In Quarkus 2.7, building native executables by using Java 17 is provided as a Technology Preview feature. To build native executables for production deployments, use Java 11.
- Log in to the Red Hat Customer Portal to download Red Hat build of OpenJDK from the Software Downloads page.
- An Open Container Initiative (OCI) compatible container runtime, such as Podman or Docker.
A completed Quarkus Getting Started project.
- To learn how to build the Quarkus Getting Started project, see Getting started with Quarkus.
-
Alternatively, you can download the Quarkus quickstart archive or clone the
Quarkus QuickstartsGit repository. The sample project is in thegetting-starteddirectory.
1.1. Producing a native executable リンクのコピーリンクがクリップボードにコピーされました!
A native binary is an executable that is created to run on a specific operating system (OS) or CPU architecture.
The following list outlines some examples of a native executable:
- A universal binary for Mac
- An ELF binary for Linux
- An EXE binary for Windows
When you build a native executable, one advantage is that your application and dependencies, including the JVM, are packaged into a single file. The native executable for your application contains the following items:
- The compiled application code
- The Java APIs
- The required libraries
- A reduced version of the Java virtual machine (JVM) for improved application startup times and minimal disk and memory footprint
To produce a native executable from your Quarkus application, you can select either an in-container build or a local-host build. The following table explains the different building options that you can use:
| Building option | Requires | Uses | Results in | Benefits |
|---|---|---|---|---|
| In-container build - Supported | A container runtime, for example, Podman or Docker |
The default | A Linux 64-bit executable | GraalVM does not need to be set up locally, which makes your CI pipelines run more efficiently |
| Local-host build - Only supported upstream | A local installation of GraalVM or Mandrel |
Its local installation as a default for the | An executable that has the same OS and CPU architecture as the machine on which the build is executed | An alternative for developers that are not allowed or don’t want to use tools such as Docker or Podman. Overall is faster than containers. |
Red Hat build of Quarkus supports the building of native Linux executables by using the Red Hat build of Quarkus Native builder, which is a productized distribution of Mandrel. Building native executables by using Oracle GraalVM Community Edition (CE), Mandrel community edition, or any other distributions of GraalVM is not supported for Red Hat build of Quarkus.
1.1.1. Producing a native executable by using an in-container build リンクのコピーリンクがクリップボードにコピーされました!
To create a native executable and run the native image tests, use the native profile that is provided by Red Hat build of Quarkus for an in-container build.
Prerequisites
- Podman or Docker is installed.
- The container has access to at least 8GB of memory.
Procedure
Open the Getting Started project
pom.xmlfile, and verify that the project includes thenativeprofile:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Build a native executable by using one of the following ways:
Using Maven:
For Docker:
./mvnw package -Pnative -Dquarkus.native.container-build=true
./mvnw package -Pnative -Dquarkus.native.container-build=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Podman:
./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podmanCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Using the Quarkus CLI:
For Docker:
quarkus build --native -Dquarkus.native.container-build=true
quarkus build --native -Dquarkus.native.container-build=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Podman:
quarkus build --native -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
quarkus build --native -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podmanCopy to Clipboard Copied! Toggle word wrap Toggle overflow Step results
These commands create a
*-runnerbinary in thetargetdirectory, where the following is true:-
The
*-runnerfile is the built native binary produced by Quarkus. The
targetdirectory is a directory that Maven creates when you build a Maven application.ImportantCompiling a Quarkus application to a native executable consumes a large amount of memory during analysis and optimization. You can limit the amount of memory used during native compilation by setting the
quarkus.native.native-image-xmxconfiguration property. Setting low memory limits might increase the build time.
To run the native executable, enter the following command:
./target/*-runner
./target/*-runnerCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Additional resources
For more information, see 'Native executable configuration properties' in Compiling your Quarkus applications to native executables.
1.1.2. Producing a native executable by using a local-host build リンクのコピーリンクがクリップボードにコピーされました!
If you are not using Docker or Podman, use the Quarkus local-host build option to create and run a native executable.
Using the local-host build approach is faster than using containers and is suitable for machines that use a Linux operating system.
Using the following procedure in production is not supported by Quarkus. Use this method only when testing or as a backup approach when Docker or Podman is not available.
Prerequisites
A local installation of Mandrel or GraalVm, correctly configured according to the Building a native executable guide.
-
Additionally, for a GraalVM installation,
native-imagemust also be installed.
-
Additionally, for a GraalVM installation,
Procedure
For GraalVM or Mandrel, build a native executable by using one of the following ways:
Using Maven:
./mvnw package -Pnative
./mvnw package -PnativeCopy to Clipboard Copied! Toggle word wrap Toggle overflow Using the Quarkus CLI:
quarkus build --native
quarkus build --nativeCopy to Clipboard Copied! Toggle word wrap Toggle overflow Step results
These commands create a
*-runnerbinary in thetargetdirectory, where the following is true:-
The
*-runnerfile is the built native binary produced by Quarkus. The
targetdirectory is a directory that Maven creates when you build a Maven application.NoteWhen you build the native executable, the
prodprofile is enabled unless modified in thequarkus.profileproperty.
-
The
Run the native executable:
./target/*-runner
./target/*-runnerCopy to Clipboard Copied! Toggle word wrap Toggle overflow Note-
Native tests run using the
prodprofile by default unless modified in thequarkus.test.native-image-profileproperty.
-
Native tests run using the
Additional resources
For more information, see Producing a native executable.
1.2. Creating a custom container image リンクのコピーリンクがクリップボードにコピーされました!
You can create a container image from your Quarkus application using one of the following methods:
- Creating a container manually
- Creating a container using the OpenShift Docker build
Compiling a Quarkus application to a native executable consumes a large amount of memory during analysis and optimization. You can limit the amount of memory used during native compilation by setting the quarkus.native.native-image-xmx configuration property. Setting low memory limits might increase the build time.
1.2.1. Creating a container manually リンクのコピーリンクがクリップボードにコピーされました!
This section shows you how to manually create a container image with your application for Linux AMD64. When you produce a native image by using the Quarkus Native container, the native image creates an executable that targets Linux AMD64. If your host operating system is different from Linux AMD64, you cannot run the binary directly and you need to create a container manually.
Your Quarkus Getting Started project includes a Dockerfile.native in the src/main/docker directory with the following content:
Universal Base Image (UBI)
The following list displays the suitable images for use with Dockerfiles.
Red Hat Universal Base Image 8 (UBI8). This base image is designed and engineered to be the base layer for all of your containerized applications, middleware, and utilities.
registry.access.redhat.com/ubi8/ubi:8.5
registry.access.redhat.com/ubi8/ubi:8.5Copy to Clipboard Copied! Toggle word wrap Toggle overflow Red Hat Universal Base Image 8 Minimal (UBI8-minimal). A stripped-down UBI8 image that uses microdnf as a package manager.
registry.access.redhat.com/ubi8/ubi-minimal:8.5
registry.access.redhat.com/ubi8/ubi-minimal:8.5Copy to Clipboard Copied! Toggle word wrap Toggle overflow - All Red Hat Base images are available on the Container images catalog site.
Procedure
Build a native Linux executable by using one of the following methods:
Docker:
./mvnw package -Pnative -Dquarkus.native.container-build=true
./mvnw package -Pnative -Dquarkus.native.container-build=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Podman:
./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podmanCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Build the container image by using one of the following methods:
Docker:
docker build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .
docker build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .Copy to Clipboard Copied! Toggle word wrap Toggle overflow Podman
podman build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .
podman build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Run the container by using one of the following methods:
Docker:
docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started
docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-startedCopy to Clipboard Copied! Toggle word wrap Toggle overflow Podman:
podman run -i --rm -p 8080:8080 quarkus-quickstart/getting-started
podman run -i --rm -p 8080:8080 quarkus-quickstart/getting-startedCopy to Clipboard Copied! Toggle word wrap Toggle overflow
1.2.2. Creating a container using the OpenShift Docker build リンクのコピーリンクがクリップボードにコピーされました!
You can create a container image for your Quarkus application using the OpenShift Docker build strategy. This strategy creates a container image by using a build configuration in the cluster.
Prerequisites
-
You have access to a Red Hat OpenShift Container Platform cluster and the latest version of the OpenShift CLI (
oc) is installed. For information about installingoc, see the Installing the CLI section of the Installing and configuring OpenShift Container Platform clusters guide. - A URL for the OpenShift API endpoint.
Procedure
Log in to the OpenShift CLI:
oc login -u <username_url>
oc login -u <username_url>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a new project in OpenShift:
oc new-project <project_name>
oc new-project <project_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a build config based on the
src/main/docker/Dockerfile.nativefile:cat src/main/docker/Dockerfile.native | oc new-build --name <build_name> --strategy=docker --dockerfile -
cat src/main/docker/Dockerfile.native | oc new-build --name <build_name> --strategy=docker --dockerfile -Copy to Clipboard Copied! Toggle word wrap Toggle overflow Build the project:
oc start-build <build_name> --from-dir .
oc start-build <build_name> --from-dir .Copy to Clipboard Copied! Toggle word wrap Toggle overflow Deploy the project to OpenShift:
oc new-app <build_name>
oc new-app <build_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expose the services:
oc expose svc/<build_name>
oc expose svc/<build_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.3. Native executable configuration properties リンクのコピーリンクがクリップボードにコピーされました!
Configuration properties define how the native executable is generated. You can configure your Quarkus application using the application.properties file.
Configuration properties
The following table lists the configuration properties that you can set to define how the native executable is generated:
| Property | Description | Type | Default |
|
|
Allows passing extra arguments to the UPX command line (like --brute). The arguments are comma-separated. The exhaustive list of parameters can be found in | list of strings | |
|
| The compression level in [1, 10]. 10 means best. Higher compression level requires more time to compress the executable. | int | |
|
|
If debug is enabled and debug symbols are generated. The symbols will be generated in a separate | boolean | false |
|
| A comma separated list of globs to match resource paths that should not be added to the native image. | list of strings | |
|
| Additional arguments to pass to the build process. | list of strings | |
|
|
Enables HTTP URL handler. This allows you to do | boolean |
|
|
|
Enables HTTPS URL handler. This allows you to do | boolean |
|
|
| Adds all security services to the native image. | boolean |
|
|
| Adds all character sets to the native image. This increases the image size. | boolean |
|
|
| Contains the path of the GraalVM distribution. | string |
|
|
| Contains the path of the JDK. |
| |
|
| The maximum Java heap used to generate the native image. | string | |
|
| Waits for a debugger to attach to the build process before running the native image build. This is an advanced option for those familiar with GraalVM internals. | boolean |
|
|
|
Publishes the debug port when building with docker if | boolean |
|
|
| Restarts the native image server. | boolean |
|
|
| Enables isolates to improve memory management. | boolean |
|
|
| Creates a JVM-based fallback image if the native image fails. | boolean |
|
|
| Uses the native image server. This can speed up compilation but can result in lost changes due to cache invalidation issues. | boolean |
|
|
|
Automatically registers all | boolean |
|
|
| Dumps the bytecode of all proxies for inspection. | boolean |
|
|
| Builds using a container runtime. Docker is used by default. | boolean |
|
|
| The docker image to build the image. | string |
|
|
| The container runtime used build the image. For example, Docker. | string | |
|
| Options to pass to the container runtime. | list of strings | |
|
| Enables VM introspection in the image. | boolean |
|
|
| Enables full stack traces in the image. | boolean |
|
|
| Generates reports on call paths and included packages/classes/methods. | boolean |
|
|
| Reports exceptions with a full stack trace. | boolean |
|
|
| Reports errors at runtime. This may cause your application to fail at runtime if you use unsupported features. | boolean |
|
|
|
A comma-separated list of globs to match resource paths that should be added to the native image. Use a slash ( | list of strings | |
|
|
Enables debug and generates debug symbols in a separate | boolean |
|
Supported glob features
The following table lists the supported glob features and descriptions:
| Character | Feature description |
|
|
Matches a possibly-empty sequence of characters that does not contain slash ( |
|
|
Matches a possibly-empty sequence of characters that might contain slash ( |
|
| Matches one character, but not slash. |
|
| Matches one character specified in the bracket, but not slash. |
|
| Matches one character from the range specified in the bracket, but not slash. |
|
| Matches one character not specified in the bracket; does not match slash. |
|
| Matches one character outside the range specified in the bracket; does not match slash. |
|
| Matches any of the alternating tokens separated by commas; the tokens may contain wildcards, nested alternations, and ranges. |
|
|
The escape character. There are three levels of escaping: |
1.3.1. Configuring memory consumption for Quarkus native compilation リンクのコピーリンクがクリップボードにコピーされました!
Compiling a Quarkus application to a native executable consumes a large amount of memory during analysis and optimization. You can limit the amount of memory used during native compilation by setting the quarkus.native.native-image-xmx configuration property. Setting low memory limits might increase the build time.
Procedure
Use one of the following methods to set a value for the
quarkus.native.native-image-xmxproperty to limit the memory consumption during the native image build time:Using the
application.propertiesfile:quarkus.native.native-image-xmx=<maximum_memory>
quarkus.native.native-image-xmx=<maximum_memory>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Setting system properties:
mvn -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.native-image-xmx=<maximum_memory>
mvn -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.native-image-xmx=<maximum_memory>Copy to Clipboard Copied! Toggle word wrap Toggle overflow This command builds the native executable with Docker. To use Podman, add the
-Dquarkus.native.container-runtime=podmanargument.
For example, to set the memory limit to 6 GB, enter quarkus.native.native-image-xmx=6g. The value must be a multiple of 1024 and greater than 2MB. Append the letter m or M to indicate megabytes, or g or G to indicate gigabytes.
1.4. Testing the native executable リンクのコピーリンクがクリップボードにコピーされました!
Test the application in native mode to test the functionality of the native executable. Use the @NativeImageTest annotation to build the native executable and run tests against the HTTP endpoints.
Procedure
Open the
pom.xmlfile and verify that thenativeprofile has the following elements:Copy to Clipboard Copied! Toggle word wrap Toggle overflow The Maven Failsafe plug-in (
maven-failsafe-plugin) runs the integration test and also indicates the location of the native executable that is generated.Open the
src/test/java/org/acme/quickstart/NativeGreetingResourceIT.javafile and verify that it includes the following content:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run the test:
./mvnw verify -Pnative
./mvnw verify -PnativeCopy to Clipboard Copied! Toggle word wrap Toggle overflow The following example shows the output of this command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteQuarkus waits for 60 seconds for the native image to start before automatically failing the native tests. You can change this duration by configuring the
quarkus.test.wait-timesystem property.You can extend the wait time by using the following command where
<duration>is the wait time in seconds:./mvnw verify -Pnative -Dquarkus.test.wait-time=<duration>
./mvnw verify -Pnative -Dquarkus.test.wait-time=<duration>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.4.1. Excluding tests when running as a native executable リンクのコピーリンクがクリップボードにコピーされました!
When you run tests against your native application, you can only interact with its HTTP endpoints. Because tests do not run natively, you cannot link against your application’s code like you do when running tests on the JVM.
You can share your test class between your JVM and native executions and exclude certain tests using the @DisabledOnNativeImage annotation to run tests only on the JVM.
1.4.2. Testing an existing native executable リンクのコピーリンクがクリップボードにコピーされました!
By using the Failsafe Maven plug-in, you can test against the existing executable build. You can run multiple sets of tests in stages on the binary after it is built.
To test the native executable that you produced with Quarkus, use the available Maven commands. There are no equivalent Quarkus CLI commands to complete this task by using the command line.
Procedure
Run a test against a native executable that is already built:
./mvnw test-compile failsafe:integration-test
./mvnw test-compile failsafe:integration-testCopy to Clipboard Copied! Toggle word wrap Toggle overflow This command runs the test against the existing native image by using the
FailsafeMaven plug-in.Alternatively, you can specify the path to the native executable with the following command where
<path>is the native image path:./mvnw test-compile failsafe:integration-test -Dnative.image.path=<path>
./mvnw test-compile failsafe:integration-test -Dnative.image.path=<path>Copy to Clipboard Copied! Toggle word wrap Toggle overflow