Quarkus アプリケーションのネイティブ実行可能ファイルへのコンパイル
概要
はじめに
アプリケーション開発者は、Red Hat ビルドの Quarkus を使用して、OpenShift 環境およびサーバーレス環境で実行される Java で書かれたマイクロサービスを作成できます。ネイティブ実行可能ファイルにコンパイルされたアプリケーションは、メモリーのフットプリントが小さく、起動時間は高速です。
このガイドでは、Quarkus Getting Started プロジェクトをネイティブ実行可能ファイルにコンパイルする方法と、ネイティブ実行可能ファイルを設定してテストする方法を説明します。Quarkus スタートガイド で作成したアプリケーションが必要です。
Red Hat ビルドの Quarkus を使用したネイティブ実行可能ファイルのビルドでは、以下について説明します。
- Podman または Docker などのコンテナーランタイムを使用した単一コマンドでのネイティブ実行可能ファイルのビルド
- 作成されたネイティブ実行可能ファイルを使用したカスタムコンテナーイメージの作成
- OpenShift Docker ビルドストラテジーを使用したコンテナーイメージの作成
- Quarkus ネイティブアプリケーションの OpenShift へのデプロイ
- ネイティブ実行可能ファイルの設定
- ネイティブ実行可能ファイルのテスト
前提条件
OpenJDK (JDK) 11 がインストールされ、
JAVA_HOME環境変数が Java SDK の場所を指定するように設定されている。- Red Hat ビルドの Open JDK は、Red Hat カスタマーポータルの Software Downloads ページからダウンロードできます (ログインが必要です)。
- OCI (Open Container Initiative) と互換性のあるコンテナーランタイム (Podman または Docker など)。
Quarkus Getting Started プロジェクトを完了している。
- Quarkus Getting Started プロジェクトのビルド方法は、Quarkus スタートガイド を参照してください。
-
あるいは、Quarkus quickstart archive をダウンロードするか、
Quarkus QuickstartsGit リポジトリーをクローンしてください。プロジェクトのサンプルはgetting-startedディレクトリーにあります。
Red Hat ドキュメントへのフィードバック (英語のみ)
弊社の技術的な内容についてのフィードバックに感謝します。ご意見をお聞かせください。コメントの追加、Insights の提供、誤字の修正、および質問を行う必要がある場合は、ドキュメントで直接行うこともできます。
Red Hat アカウントがあり、カスタマーポータルにログインしている必要があります。
カスタマーポータルからドキュメントのフィードバックを送信するには、以下の手順を実施します。
- Multi-page HTML 形式を選択します。
- ドキュメントの右上にある Feedback ボタンをクリックします。
- フィードバックを提供するテキストのセクションを強調表示します。
- ハイライトされたテキストの横にある Add Feedback ダイアログをクリックします。
- ページの右側のテキストボックスにフィードバックを入力し、Submit をクリックします。
フィードバックを送信すると、自動的に問題の追跡が作成されます。Submit をクリックすると表示されるリンクを開き、問題の監視を開始するか、さらにコメントを追加します。
貴重なフィードバックにご協力いただきありがとうございます。
多様性を受け入れるオープンソースの強化
Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。
第1章 ネイティブ実行可能ファイルの作成
Podman または Docker などのコンテナーランタイムを使用して、Quarkus アプリケーションからネイティブ実行可能ファイルを作成することができます。Quarkus は、ビルダーイメージを使用してバイナリー実行可能ファイルを作成します。これは、Red Hat Universal Base Images RHEL8-UBI および RHEL8-UBI minimal と共に使用することができます。Red Hat ビルドの Quarkus 1.11 は、quarkus.native.builder-image プロパティーのデフォルトとして registry.access.redhat.com/quarkus/mandrel-20-rhel8:20.3 を使用します。
お使いのアプリケーションのネイティブ実行可能ファイルには、アプリケーションコード、必須ライブラリー、Java API、および仮想マシン (VM) の縮小版が含まれます。縮小された仮想マシンベースは、アプリケーションの起動時間を高速化し、ディスクのフットプリントを小さくします。
手順
Getting Started プロジェクトの
pom.xmlファイルを開き、nativeプロファイルが含まれていることを確認します。<profiles> <profile> <id>native</id> <properties> <quarkus.package.type>native</quarkus.package.type> </properties> </profile> </profiles>注記Quarkus
nativeプロファイルを使用すると、ネイティブ実行可能ファイルおよびネイティブイメージテストの両方を実行することができます。以下のいずれかの方法を使用して、ネイティブ実行可能ファイルをビルドします。
Docker を使用してネイティブ実行可能ファイルをビルドします。
./mvnw package -Pnative -Dquarkus.native.container-build=true
Podman を使用してネイティブ実行可能ファイルをビルドします。
./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
これらのコマンドにより、
targetディレクトリーにgetting-started-*-runnerバイナリーが作成されます。重要Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルすると、分析および最適化の際にメモリーを大量に消費します。
quarkus.native.native-image-xmx設定プロパティーを設定することで、ネイティブコンパイル時に使用されるメモリーの量を制限することができます。メモリー制限を低く設定すると、ビルド時間が長くなる可能性があります。詳細は、ネイティブ実行可能ファイルの設定プロパティー を参照してください。
ネイティブ実行可能ファイルを実行します。
./target/getting-started-*-runner
ネイティブ実行可能ファイルをビルドする場合は
prodプロファイルが有効化され、Quarkus ネイティブテストは、prodプロファイルを使用して実行されます。これは、quarkus.test.native-image-profileプロパティーを使用して変更できます。
第2章 カスタムコンテナーイメージの作成
以下のいずれかの方法を使用して、Quarkus アプリケーションからコンテナーイメージを作成できます。
- 手動でのコンテナーの作成
- OpenShift Docker ビルドを使用したコンテナーの作成
Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルすると、分析および最適化の際にメモリーを大量に消費します。quarkus.native.native-image-xmx 設定プロパティーを設定することで、ネイティブコンパイル時に使用されるメモリーの量を制限することができます。メモリー制限を低く設定すると、ビルド時間が長くなる可能性があります。
2.1. 手動でのコンテナーの作成
このセクションでは、Linux X86_64 向けにアプリケーションを使用してコンテナーイメージを手動で作成する方法を説明します。Quarkus Native コンテナーを使用してネイティブイメージを作成する場合は、Linux X86_64 オペレーティングシステムをターゲットとする実行可能ファイルを作成します。お使いのホストオペレーティングシステムが別のものである場合は、バイナリーを直接実行することはできず、コンテナーを手動で作成する必要があります。
Quarkus Getting Started プロジェクトには、以下の内容と共に src/main/docker ディレクトリーに Dockerfile.native が含まれます。
FROM registry.access.redhat.com/ubi8/ubi-minimal:8.3
WORKDIR /work/
RUN chown 1001 /work \
&& chmod "g+rwX" /work \
&& chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/application
EXPOSE 8080
USER 1001
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]
Dockerfiles は、ベースイメージとして UBI を使用します。このベースイメージは、コンテナーで機能するように設計されています。Dockerfiles は、ベースイメージの minimal バージョン を使用して、作成されたイメージのサイズを縮小します。
手順
以下のいずれかの方法を使用して、ネイティブ Linux 実行可能ファイルをビルドします。
Docker を使用してネイティブ実行可能ファイルをビルドします。
./mvnw package -Pnative -Dquarkus.native.container-build=true
Podman を使用してネイティブ実行可能ファイルをビルドします。
./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman
以下のいずれかの方法を使用して、コンテナーイメージをビルドします。
Docker を使用してコンテナーイメージをビルドします。
docker build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .
Podman を使用してコンテナーイメージをビルドします。
podman build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .
コンテナーを実行します。
Docker を使用してコンテナーを実行します。
docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started
Podman を使用してコンテナーを実行します。
podman run -i --rm -p 8080:8080 quarkus-quickstart/getting-started
2.2. OpenShift Docker ビルドを使用したコンテナーの作成
OpenShift Docker ビルドストラテジーを使用して、Quarkus アプリケーションのコンテナーイメージを作成できます。このストラテジーは、クラスターでビルド設定を使用してコンテナーを作成します。
前提条件
- Red Hat OpenShift Container Platform クラスターにアクセスでき、最新バージョンの OpenShift CLI (oc) がインストールされている。oc のインストールに関する詳細は、OpenShift Container Platform クラスターのインストールおよび設定 ガイドの CLI のインストールのセクションを参照してください。
- OpenShift API エンドポイントの URL。
手順
OpenShift CLI にログインします。
oc login -u <username_url>
OpenShift に新規プロジェクトを作成します。
oc new-project <project_name>
src/main/docker/Dockerfile.nativeファイルに基づいてビルド設定を作成します。cat src/main/docker/Dockerfile.native | oc new-build --name <build_name> --strategy=docker --dockerfile -
プロジェクトをビルドします。
oc start-build <build_name> --from-dir .
プロジェクトを OpenShift にデプロイします。
oc new-app <build_name>
サービスを公開するには、以下を実行します。
oc expose svc/<build_name>
第3章 ネイティブ実行可能ファイルの設定プロパティー
設定プロパティーは、ネイティブ実行可能ファイルの生成方法を定義します。application.properties ファイルを使用して、Quarkus アプリケーションを設定できます。
設定プロパティー
以下の表は、ネイティブ実行可能ファイルの生成方法を定義するよう設定できる設定プロパティーの一覧です。
| プロパティー | 説明 | 型 | デフォルト |
|---|---|---|---|
|
| ビルドプロセスにパスする追加の引数。 | 文字列の一覧 | |
|
| HTTP URL ハンドラーを有効にします。これにより、HTTP URL に URL.openConnection() が可能となります。 | ブール値 |
|
|
| HTTPS URL ハンドラーを有効にします。これにより、HTTPS URL に URL.openConnection() が可能となります。 | ブール値 |
|
|
| ネイティブイメージにすべてのセキュリティーサービスを追加します。 | ブール値 |
|
|
| ネイティブイメージにすべてのキャラクターセットを追加します。これにより、イメージサイズが大きくなります。 | ブール値 |
|
|
| Graal ディストリビューションのパスが含まれます。 | 文字列 |
|
|
| JDK のパスが含まれます。 |
| |
|
| ネイティブイメージを生成するために使用する Java の最大ヒープサイズ。 | 文字列 | |
|
| ネイティブイメージのビルドを実行する前に、デバッガーがビルドプロセスにアタッチするまで待機します。GraalVM インターナルの知識のあるユーザーにとって、これは高度なオプションになります。 | ブール値 |
|
|
| Docker でビルドし、debug-build-process が true の場合は、デバッグポートを公開します。 | ブール値 |
|
|
| ネイティブイメージサーバーを再起動します。 | ブール値 |
|
|
| メモリー管理を向上させるために分離を有効化します。 | ブール値 |
|
|
| ネイティブイメージが失敗した場合は、JVM ベースのフォールバックイメージを作成します。 | ブール値 |
|
|
| ネイティブイメージサーバーを使用します。これにより、コンパイルを高速化することは可能ですが、キャッシュの無効化問題により、ドロップが変更される可能性があります。 | ブール値 |
|
|
| すべての META-INF/services エントリーを自動的に登録します。 | ブール値 |
|
|
| 検査用にすべてのプロキシーのバイトコードをダンプします。 | ブール値 |
|
|
| コンテナーランタイムを使用してビルドします。デフォルトで Docker が使用されます。 | ブール値 |
|
|
| イメージをビルドするための Docker イメージ。 | 文字列 |
|
|
| イメージをビルドするために使用されるコンテナーランタイム。たとえば、Docker などがあります。 | 文字列 | |
|
| コンテナーランタイムにパスするオプション。 | 文字列の一覧 | |
|
| イメージの VM イントロスペクションを有効化します。 | ブール値 |
|
|
| イメージのフルスタックトレースを有効化します。 | ブール値 |
|
|
| コールパスおよび含まれるパッケージ/クラス/メソッドのレポートを生成します。 | ブール値 |
|
|
| フルスタックトレースを使用して例外を報告します。 | ブール値 |
|
|
| ランタイム時にエラーを報告します。サポート対象外の機能を使用している場合は、お使いのアプリケーションがランタイム時に失敗する可能性があります。 | ブール値 |
|
|
|
ネイティブイメージに追加する必要のあるリソースパスに一致する glob のコンマ区切りリスト。すべてのプラットフォームで、スラッシュ ( | 文字列の一覧 | |
|
|
デバッグを有効にし、別の .debug ファイルにデバッグシンボルを生成します。 | ブール値 |
|
サポートされる glob 機能とその説明
以下の表は、サポートされる glob 機能とその説明を一覧表示しています。
| 文字 | 機能の説明 |
|
|
スラッシュ ( |
|
|
スラッシュ ( |
|
| 1 つの文字と一致しますが、スラッシュとは一致しません。 |
|
| ブラケットで指定した範囲の文字の 1 つと一致しますが、スラッシュとは一致しません。 |
|
| ブラケットで指定した範囲の文字の 1 つと一致しますが、スラッシュとは一致しません。 |
|
| ブラケットで指定していない文字の 1 つと一致しますが、スラッシュとは一致しません。 |
|
| ブラケットで指定した範囲外の文字の 1 つと一致しますが、スラッシュとは一致しません。 |
|
| コンマ区切り文字とトークンが交互に連続する文字列で、あらゆるトークンと一致します。トークンには、ワイルドカード、ネストされたオルタネーション、および範囲が含まれます。 |
|
|
エスケープ文字。エスケープには、 |
関連情報
3.1. Quarkus ネイティブコンパイルのメモリー消費の設定
Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルすると、分析および最適化の際にメモリーを大量に消費します。quarkus.native.native-image-xmx 設定プロパティーを設定することで、ネイティブコンパイル時に使用されるメモリーの量を制限することができます。メモリー制限を低く設定すると、ビルド時間が長くなる可能性があります。
手順
以下のいずれかの方法を使用して
quarkus.native.native-image-xmxプロパティーに値を設定し、ネイティブイメージのビルドタイム中のメモリー消費を制限します。application.propertiesファイルを使用します。quarkus.native.native-image-xmx=<maximum_memory>
システムプロパティーの設定
mvn -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.native-image-xmx=<maximum_memory>
このコマンドは、Docker を使用してネイティブ実行可能ファイルをビルドします。Podman を使用するように
-Dquarkus.native.container-runtime=podman引数を追加します。
たとえば、メモリー制限を 6 GB に設定するには、quarkus.native.native-image-xmx=6g を入力します。値は、2MB より大きい 1024 の倍数にする必要があります。メガバイトを示す m または M の文字を追加するか、ギガバイトを示す g または G の文字を追加します。
第4章 ネイティブ実行可能ファイルのテスト
ネイティブ実行可能ファイルの機能をテストするために、ネイティブモードで実行するアプリケーションをテストします。@NativeImageTest アノテーションを使用して、ネイティブ実行可能ファイルをビルドし、http エンドポイントに対してテストを実行します。
手順
pom.xmlファイルを開き、nativeプロファイルに以下の要素が含まれていることを確認します。<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-failsafe-plugin</artifactId> <version>${surefire-plugin.version}</version> <executions> <execution> <goals> <goal>integration-test</goal> <goal>verify</goal> </goals> <configuration> <systemPropertyVariables> <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path> <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager> <maven.home>${maven.home}</maven.home> </systemPropertyVariables> </configuration> </execution> </executions> </plugin>failsafe-maven-pluginはインテグレーションテストを実行し、作成されたネイティブ実行可能ファイルの場所を示します。src/test/java/org/acme/quickstart/NativeGreetingResourceIT.javaファイルを開き、次のコンテンツが含まれていることを確認します。package org.acme.quickstart; import io.quarkus.test.junit.NativeImageTest; @NativeImageTest 1 public class NativeGreetingResourceIT extends GreetingResourceTest { 2 // Run the same tests }
テストを実行します。
./mvnw verify -Pnative
以下の例は、このコマンドの出力を示しています。
./mvnw verify -Pnative ... [getting-started-1.0-SNAPSHOT-runner:18820] universe: 587.26 ms [getting-started-1.0-SNAPSHOT-runner:18820] (parse): 2,247.59 ms [getting-started-1.0-SNAPSHOT-runner:18820] (inline): 1,985.70 ms [getting-started-1.0-SNAPSHOT-runner:18820] (compile): 14,922.77 ms [getting-started-1.0-SNAPSHOT-runner:18820] compile: 20,361.28 ms [getting-started-1.0-SNAPSHOT-runner:18820] image: 2,228.30 ms [getting-started-1.0-SNAPSHOT-runner:18820] write: 364.35 ms [getting-started-1.0-SNAPSHOT-runner:18820] [total]: 52,777.76 ms [INFO] [INFO] --- maven-failsafe-plugin:2.22.1:integration-test (default) @ getting-started --- [INFO] [INFO] ------------------------------------------------------- [INFO] T E S T S [INFO] ------------------------------------------------------- [INFO] Running org.acme.quickstart.NativeGreetingResourceIT Executing [/data/home/gsmet/git/quarkus-quickstarts/getting-started/target/getting-started-1.0-SNAPSHOT-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=build/quarkus.log] 2019-04-15 11:33:20,348 INFO [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 0.002s. Listening on: http://[::]:8081 2019-04-15 11:33:20,348 INFO [io.quarkus] (main) Installed features: [cdi, resteasy] [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.387 s - in org.acme.quickstart.NativeGreetingResourceIT ...
注記Quarkus は、ネイティブイメージの開始まで 60 秒間待機し、その後ネイティブテストに自動的に失敗します。この期間は、
quarkus.test.native-image-wait-timeシステムプロパティーを使用して変更できます。以下のコマンドを使用して、待機時間を延長することができます。
<duration>は、秒単位の待機時間になります。./mvnw verify -Pnative -Dquarkus.test.native-image-wait-time=
<duration>
4.1. ネイティブ実行可能ファイルとして実行する場合のテストを除外する
ネイティブアプリケーションに対してテストを実行する場合は、HTTP エンドポイントと対話することしかできません。テストはネイティブでは実行されないため、お使いのアプリケーションのコードに対して、JVM での実行でリンクできる場合と同じようにリンクすることはできません。
JVM とネイティブ実行可能ファイルとの間でテストクラスを共有することができ、@DisabledOnNativeImage アノテーションを使用して特定のテストを除外して JVM でのみ実行することができます。
4.2. 既存のネイティブ実行可能ファイルのテスト
既存の実行可能ファイルのビルドに対してテストすることができます。これにより、バイナリーのビルド後にバイナリーで複数のテストのセットを段階的に実行することができます。
手順
すでにビルドされたネイティブ実行可能ファイルに対してテストを実行します。
./mvnw test-compile failsafe:integration-test
このコマンドは、Failsafe Maven Plugin を使用して、既存のネイティブイメージに対してテストを実行します。
あるいは、以下のコマンドを使用してネイティブ実行可能ファイルへのパスを指定することもできます。
<path>は、ネイティブイメージパスになります。./mvnw test-compile failsafe:integration-test -Dnative.image.path=<path>
第5章 関連情報
改訂日時: 2023-05-16
