Re-augment a Quarkus Application
オーグメンテーションとは？
Quarkusのアプリケーション設定には、2種類の設定オプションがあります。
-
ビルドタイムオプション：アプリケーションのビルド時に処理されます。
-
ランタイムオプション: アプリケーションがビルドされた後、起動する前に調整することができます。
オーグメンテーションとは、アプリケーションのビルドプロセスの段階で、アプリケーションのバイトコードがアプリケーションのビルド時の設定に応じて最適化されることです。
EAR ファイルが Jakarta EE サーバーにデプロイされるときに行われていた初期化ステップ (静的設定のパース、プロキシーインスタンスの作成など) が、オーグメンテーション時に行われるようになりました。
オーグメンテーション後に追加されたCDI Beanは (プロキシークラスがないため) 動作しません。また、オーグメンテーション後に変更されたビルド時のプロパティー (例: quarkus.datasource.db-kind) は無視されます。
ビルド時のプロパティーには、すべての設定オプションのリスト でロックアイコン () が付いています。
プロファイルやその他の方法でプロパティーをオーバーライドしても関係ありません。
再オーグメンテーションとは、オーグメンテーション出力を異なるビルド時の設定で再作成するプロセスです。
どのような場合に再オーグメンテーションが有効ですか？
再オーグメンテーションは、アプリケーションのユーザーがビルド時のプロパティーの一部を変更できるようにしたい場合に便利です。
たとえば、データベースドライバーの変更や、機能のオン/オフ (例: OpenTelemetry または Config Consul) などの場合に便利です。
ユーザー環境に依存するビルド時のプロパティーが 2 つか 3 つしかない場合は、アプリケーションの代替ビルドの提供を検討してもよいでしょう。しかし、そのようなプロパティーが多い場合は、代わりに変更可能な jar を配布し、ユーザーが自分の環境に合わせてアプリケーションを再調整できるようにする方が良いかもしれません。
パッケージタイプ mutable-jar では、ネイティブイメージを使用できない点に注意してください。
その結果と、他にどんな選択肢があるかを考えてみてください。
サーバーの起動に数分かかり、準備が整うまでコーヒーを楽しむことができた古き良き時代を懐かしむのでなければ、ランタイムに再オーグメンテーションを行うことは得策ではありません。
Quarkusのアプリケーションを再オーグメンテーションする方法
オーグメンテーションステップを実行するためには、使用される Quarkus エクステンションのデプロイメント JAR が必要です。
これらのJARは、 mutable-jar のディストリビューションにのみ含まれています。つまり、 quarkus.package.jar.type=mutable-jar でアプリケーションを構築する必要があります。
mutable-jar ディストリビューションは、 fast-jar ディストリビューションと同じですが、追加のフォルダー quarkus-app/lib/deployment には、
デプロイメント JAR とその依存関係 (および一部のクラスローダ設定) が含まれています。
By default, you’ll get a warning if a build time property has been changed at runtime.
You may set the quarkus.config.build-time-mismatch-at-runtime=fail property to make sure your application does not start up if there is a mismatch.
However, as of this writing changing quarkus.datasource.db-kind at runtime did neither fail nor produce a warning but was silently ignored.
|
Build time configuration provided by build tools (properties in Maven pom.xml or gradle.properties
in Gradle) in the quarkus namespace will be part of the mutable-jar distribution, including configuration from
quarkus that reference secrets or passwords. Please, do not include sensitive information in the build tool
configuration files.
|
1. Build your application as mutable-jar
mvn clean install -Dquarkus.package.jar.type=mutable-jar2. ビルド時の設定を変えて、アプリケーションを再ビルドする
異なるビルド時のプロパティでQuarkusアプリケーションを再オーグメンテーションするには、目的の設定に加えて、 quarkus.launch.rebuild システムプロパティを true に設定してアプリケーションを起動します。
次の例では、 quarkus.datasource.db-kind を mysql に変更しています。これを実行するには、 mysql-extension がビルドに含まれている必要があります。オーグメンテーションは、コンパイル時に存在していたエクステンションのみを使用することができます。
java -jar -Dquarkus.launch.rebuild=true -Dquarkus.datasource.db-kind=mysql target/quarkus-app/quarkus-run.jar
It does not matter if you use system properties, environment variables, profiles, or an external config file. The current
configuration will be used for augmentation (the content of quarkus-app/quarkus will be replaced with the new augmentation output).
The command line above will not launch the application. Quarkus will exit immediately after the application has been re-augmented.
|
3. オプション: deployments フォルダの削除
ZIP配布やDockerイメージのスペースを節約するために、 quarkus-app/lib/deployment ディレクトリを削除しても構いません（不要なレイヤーを避けるために、多段階のDockerビルドを使用することを忘れないでください）。 deployment ディレクトリを削除すると、当然ながらアプリケーションの再オーグメンテーションはできなくなります。
