ネイティブ実行可能ファイルの生成

ネイティブな実行可能ファイルをビルドするには、GraalVM のディストリビューションを使用する必要があります。ディストリビューションは3つあります。Oracle GraalVM Community Edition (CE)、Oracle GraalVM Enterprise Edition (EE)、そして Mandrel です。Oracle ディストリビューションと Mandrel ディストリビューションの違いは以下の通りです。

GraalVM for JDK 21 is required.

On Linux it’s possible to package a native executable that doesn’t depend on any system shared library. There are some system requirements to be fulfilled and additional build arguments to be used along with the native-image invocation, a minimum is -Dquarkus.native.additional-build-args="--static","--libc=musl".

完全な静的バイナリのコンパイルは、 glibc の代わりに musl を静的にリンクすることで行われます。厳密なテストなしに実運用で使用するべきではありません。

デフォルトでは、インテグレーションテストは prod プロファイルを使用して、ネイティブの実行可能ファイルに対して build と run の両方を行います。

You can override the profile the executable runs with during the test using the quarkus.test.native-image-profile property. Either by adding it to application.properties or by appending it to the command line: ./mvnw verify -Dnative -Dquarkus.test.native-image-profile=test. Your %test. prefixed properties will be used at the test runtime.

You can override the profile the executable is built with and runs with using the quarkus.profile=test property, e.g. ./mvnw clean verify -Dnative -Dquarkus.profile=test. This might come handy if there are test specific resources to be processed, such as importing test data into the database.

上記の例を application.properties に記述すると、Hibernate ORM が管理するデータベースには、JVM モードのテスト実行中とネイティブモードのテスト実行中の両方でテストデータが入力されることになります。本番用の実行ファイルには version.txt リソースのみが含まれ、余分なテストデータは含まれません。

この方法でテストを実行する場合、実際にネイティブで実行されるのはアプリケーションのエンドポイントのみで、HTTP 呼び出しでしかテストできません。テストコードは実際にはネイティブには実行されないので、HTTP エンドポイントを呼び出さないコードをテストしている場合は、それらをネイティブテストの一部として実行するのは良い考えではないでしょう。

上記のようにJVMとネイティブ実行でテストクラスを共有している場合、特定のテストをネイティブイメージに対してテストをするときに、@DisabledOnNativeImage アノテーションを付けてそれらをスキップできます。

It is also possible to re-run the tests against a native executable that has already been built. To do this run ./mvnw test-compile failsafe:integration-test -Dnative. This will discover the existing native image and run the tests against it using failsafe.

何らかの理由でプロセスがネイティブイメージを見つけられない場合や、ターゲットディレクトリーにないネイティブイメージをテストしたい場合は、 -Dnative.image.path= システムプロパティーで実行ファイルを指定することができます。

Quarkusアプリケーションからコンテナイメージを作成する最も簡単な方法は、コンテナイメージ エクステンションの1つを利用することです。

これらのエクステンションのいずれかが存在する場合、ネイティブ実行可能ファイル用のコンテナイメージを作成することは、基本的には単一のコマンドを実行することになります:

詳細については、 コンテナイメージガイド を参照してください。

Quarkus Mavenプラグインで生成されたJARを使用して、コンテナー内でアプリケーションを実行することができます。ただし、このセクションでは、生成されたネイティブ実行可能ファイルを使用してコンテナーイメージを作成することに焦点を当てます。

ローカルのGraalVMインストール環境を使用する場合、ネイティブ実行可能ファイルは、ローカルのオペレーティングシステム(Linux、macOS、Windowsなど)をターゲットにしています。しかし、コンテナーはオペレーティングシステムによって生成されたものと同じ 実行 形式を使用しない場合があるため、コンテナーランタイムを活用して実行形式を生成するようにMavenビルドに指示します(この セクション で説明されているように)。

生成される実行ファイルは 64 ビットの Linux 実行ファイルになるので、お使いの OS によっては実行できなくなる可能性があります。しかし、コンテナにコピーするので問題ありません。プロジェクト生成では、 src/main/docker ディレクトリに Dockerfile.native-micro を用意し、以下のような内容にしています:

あとは、生成されたネイティブ実行可能ファイルを削除していなければ、dockerイメージを使ってビルドします:

そして最後に、以下を実行します:

プロジェクト生成では、以下の内容の src/main/docker docker ディレクトリも提供されます:

UBI の最小イメージは、上記のマイクロイメージよりも大きくなっています。これには、microdnf パッケージマネージャーなどのユーティリティーが含まれています。

前のセクションでは、Maven または Gradle を使用してネイティブ実行可能ファイルをビルドする方法を示しましたが、その場合は最初にネイティブ実行可能ファイルを作成しておく必要があります。さらに、このネイティブ実行可能ファイルは Linux64 ビットの実行可能ファイルである必要があります。

ビルドツールを含む最終的なコンテナを用意せずに、ネイティブ実行可能ファイルをコンテナに直接ビルドする必要がある場合もあるはずです。このアプローチは、マルチステージの Docker ビルドで使用可能です:

このような多段階を用いたビルドは、次のように実現できます:

MavenでビルドするためのサンプルDockerfileです:

このファイルは、Getting started quickstartには含まれていないので、 src/main/docker/Dockerfile.multistage に保存してください。

GradleでビルドするためのサンプルDockerfileです:

プロジェクトでGradleを使用している場合は、このサンプルDockerfileを使用することができます。 src/main/docker/Dockerfile.multistage に保存してください。

最後に、以下を実行します:

小さなコンテナイメージを探している場合は、 distroless アプローチでベースレイヤーのサイズが縮小されます。 distroless の背後には、すべての要件 (場合によってはアプリケーション自体) を含む単一の最小限のベースイメージを使用するという考え方があります。

Quarkus は、Dockerfile で使用できる distroless ベースイメージを提供します。ユーザーは、アプリケーションをコピーするだけです:

Quarkus は、quay.io/quarkus/quarkus-distroless-image:2.0 イメージを提供します。ネイティブ実行可能ファイルを実行するために必要なパッケージが含まれており、サイズはほんの 9Mb です。このイメージの上にアプリケーションを追加するだけで、小さなコンテナイメージを得られます。

Distroless イメージを本番環境で使用する場合は、必ず厳密なテストを実施してください。

完全に静的にリンクされたバイナリをビルドすることで、ビルド結果のネイティブ実行可能ファイルのみを含む スクラッチイメージ を使用することができます。

Scratch からイメージを構築するためのサンプルのマルチステージのDockerfileです:

スクラッチイメージを本番環境で使用する場合は、必ず厳密なテストを実施してください。

Quarkus は、UPX を使用して生成されたネイティブ実行可能ファイルを圧縮できます。詳細については、UPX 圧縮のドキュメント を参照してください。

In certain circumstances, you may want to build the native image in a separate step. For example, in a CI/CD pipeline, you may want to have one step to generate the source that will be used for the native image generation and another step to use these sources to actually build the native executable. For this use case, you can set the additional flag quarkus.native.sources-only=true. This will execute the java compilation as if you had started native compilation (-Dnative), but stops before triggering the actual call to GraalVM’s native-image.

コンパイルが完了すると、ビルドアーティファクトが target/native-sources に表示されます:

From the output above one can see that, in addition to the produced jar file and the associated lib directory, a text file named native-image.args was created. This file holds all parameters (including the name of the JAR to compile) to pass along to GraalVM’s native-image command. A text file named graalvm.version was also created and holds the GraalVM version that should be used. If you have GraalVM installed and it matches this version, you can start the native compilation by executing:

Gradle のプロセスも同様です。

コンテナでビルドプロセスを実行することも可能です:

-Dquarkus.native.container-build=true は、ネイティブイメージのビルドに使用するDockerイメージ名を保持する native-builder.image という名前の追加のテキストファイルを生成します。

CI/CD パイプラインのさまざまなステップがどのように見えるかについて、以下に概要を示しています。

ステップ 1 を実行する環境には、Java と Maven (または Gradle) のみインストールされている必要がありますが、ステップ 3 を実行する環境には GraalVM のインストール (native-image 機能を含む) のみが必要です。

CI/CD パイプラインの最終的な出力に応じて、生成されたバイナリーがコンテナイメージの作成に使用されます。