The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Quarkusアプリケーションの再オーグメンテーション

オーグメンテーションとは?

Quarkusのアプリケーション設定には、2種類の設定オプションがあります。

  • ビルドタイムオプション:アプリケーションのビルド時に処理されます。

  • ランタイムオプション:アプリケーションがビルドされた後、起動する前に調整することができます。

The augmentation is a phase of an application build process during which the byte code of the application is optimized according to the application build time configuration. Initialization steps that used to happen when an EAR file was deployed on a Jakarta EE server such as parsing static configuration, creating proxy instances, etc. now happen at augmentation time. CDI beans added after augmentation won’t work (because of the missing proxy classes) as well as build time properties (e.g. quarkus.datasource.db-kind) changed after augmentation will be ignored. Build time properties are marked with a lock icon () in the list of all configuration options. It doesn’t matter if you use profiles or any other way to override the properties.

再オーグメンテーションとは、オーグメンテーション出力を異なるビルド時の設定で再作成するプロセスです。

どのような場合に再オーグメンテーションが有効ですか?

Re-augmentation is useful in case the users of your application want to be able to change some of its build time properties. For instance changing the database driver or switching features on or off (e.g. OpenTelemetry or Config Consul). If there are only two or three build time properties that depend on the user environment, you may consider providing alternative builds of the application. However, in case there are more such properties you may prefer shipping a mutable jar instead and let your users re-augment the application for their environment. Please notice that you won’t be able to use native images with the package type mutable-jar. Think of the consequences and what other options you have!

It is not a good idea to do re-augmentation at runtime unless you miss the good old times when starting up a server took several minutes, and you could enjoy a cup of coffee until it was ready.

Quarkusのアプリケーションを再オーグメンテーションする方法

オーグメンテーションステップを実行するためには、使用されるQuarkusエクステンションのデプロイメントJARが必要です。これらのJARは、 mutable-jar のディストリビューションにのみ含まれています。つまり、 quarkus.package.type=mutable-jar でアプリケーションを構築する必要があります。 mutable-jar ディストリビューションは、 fast-jar ディストリビューションと同じですが、追加のフォルダ quarkus-app/lib/deployment には、デプロイメントJARとその依存関係(およびクラスローダの設定)が含まれています。

デフォルトでは、ビルド時プロパティが実行時に変更された場合、警告が表示されます。 quarkus.configuration.build-time-mismatch-at-runtime=fail プロパティを設定して、不一致があった場合にアプリケーションが起動しないようにすることもできます。しかし、この記事を書いている時点では、実行時に quarkus.datasource.db-kind を変更しても、失敗することも警告が出ることもなく、静かに無視されました。
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. mutable-jar として、アプリケーションを構築します。

mvn clean install -Dquarkus.package.type=mutable-jar

2. ビルド時の設定を変えて、アプリケーションを再ビルドする

異なるビルド時のプロパティでQuarkusアプリケーションを再オーグメンテーションするには、目的の設定に加えて、 quarkus.launch.rebuild システムプロパティを true に設定してアプリケーションを起動します。

次の例では、 quarkus.datasource.db-kindmysql に変更しています。これを実行するには、 mysql-extension がビルドに含まれている必要があります。オーグメンテーションは、コンパイル時に存在していたエクステンションのみを使用することができます。

java -jar -Dquarkus.launch.rebuild=true -Dquarkus.datasource.db-kind=mysql target/quarkus-app/quarkus-run.jar
システムプロパティ、環境変数、プロファイル、外部の設定ファイルのどれを使っても構いません。現在の設定がオーグメンテーションに使用されます( quarkus-app/quarkus の内容は、新しいオーグメンテーション出力に置き換えられます)。上記のコマンドラインでは、アプリケーションは起動しません。アプリケーションが再オーグメンテーションされた後、Quarkusは直ちに終了します。

3. オプション: deployments フォルダの削除

ZIP配布やDockerイメージのスペースを節約するために、 quarkus-app/lib/deployment ディレクトリを削除しても構いません(不要なレイヤーを避けるために、多段階のDockerビルドを使用することを忘れないでください)。 deployment ディレクトリを削除すると、当然ながらアプリケーションの再オーグメンテーションはできなくなります。

関連コンテンツ