設定リファレンスガイド
| 本ガイドの内容を改訂し、さらにトピックを分割しました。追加情報をご覧ください。 |
このリファレンスガイドでは、Quarkus の設定の様々な側面について説明します。Quarkus アプリケーションと Quarkus 自体 (コアとエクステンション) の両方は、 MicroProfile Config 仕様の実装である SmallRye Config APIを活用した同じメカニズムを介して設定されます。
| Quarkus エクステンションを設定可能にする方法については、独自のエクステンションの作成 ガイドを参照してください。 |
1. 設定ソース
デフォルトでは、Quarkus は複数のソースから設定プロパティーを読み取ります (降順)。
-
(400) システムプロパティー
-
(300) 環境変数
-
(295) 現在の作業ディレクトリーの .env ファイル
-
(260)
$PWD/config/application.propertiesの Quarkus アプリケーション設定ファイル -
(250) クラスパスの Quarkus アプリケーション設定ファイル
application.properties -
(100) クラスパスの MicroProfile Config 設定ファイル
META-INF/microprofile-config.properties
最終的な設定は、これらすべてのソースによって定義されたプロパティーの集約です。設定プロパティーのルックアップは、使用可能な最も高い序数の設定ソースから始まり、一致するものが見つかるまで他のソースに下がっていきます。つまり、上位の序数設定ソースに別の値を設定するだけで、設定プロパティーが値をオーバーライドする可能性があります。たとえば、環境プロパティーを使用して設定されたプロパティーは、 application.properties ファイルを使用して提供された値をオーバーライドします。
1.1. システムプロパティー
システムプロパティーは、起動時に -D フラグを介してアプリケーションに渡すことができます。次の例では、値 youshallnotpass を属性 quarkus.datasource.password に割り当てます。
-
Quarkus 開発モードの場合:
./mvnw quarkus:dev -Dquarkus.datasource.password=youshallnotpass -
runner jar の場合:
java -Dquarkus.datasource.password=youshallnotpass -jar target/quarkus-app/quarkus-run.jar -
ネイティブ実行可能ファイルの場合:
./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass
1.2. 環境変数
-
runner jar の場合:
export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; java -jar target/quarkus-app/quarkus-run.jar -
ネイティブ実行可能ファイルの場合:
export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; ./target/myapp-runner
| 環境変数名は、MicroProfile Config の変換ルールに従っています。 |
| SmallRye Config は 追加の規約ルール を指定します。 |
1.3. 現在の作業ディレクトリーにある .env ファイル
QUARKUS_DATASOURCE_PASSWORD=youshallnotpass (1)| 1 | 名前 QUARKUS_DATASOURCE_PASSWORD は、環境変数 に使用されるものと同じ変換ルール。 |
dev モードの場合、このファイルはプロジェクトのルートに置くことができますが、バージョン管理を選択 しない ことが推奨されます。
.env ファイルの環境変数は、 System.getenv(String) API を介して利用できません。
|
1.4. Quarkus アプリケーション設定ファイル
Quarkus アプリケーション設定ファイルは、クラスパスリソース (たとえば、 src/main/resources/application.properties、 src/test/resources/application.properties) から、または application.properties エントリーが含まれる jar 依存関係から読み込まれます。見つかった各 application.properties は個別の ConfigSource として扱われ、他のすべてのソースと同じルールに従います (プロパティーごとのオーバーライド)。さらに、設定ファイルは $PWD/config/application.properties に存在する場合もあります。読み込みは config フォルダーから始まり、次にクラスパスの順序になります (アプリケーションソース内の application.properties ファイルがクラスローダー読み込み順序で優先されます)。
application.propertiesgreeting.message=hello (1)
quarkus.http.port=9090 (2)| 1 | これは、ユーザー定義の設定プロパティーです。 |
| 2 | これは quarkus-vertx-http エクステンションによって消費される設定プロパティーです。 |
config/application.properties は dev モードでも利用可能です。ファイルは、ビルドツールの出力ディレクトリー (Maven の場合は target 、Gradle の場合は build/classes/java/main) の中に置く必要があります。ただし、 mvn clean や gradle clean のようなビルドツールからのクリーンアップ操作は、 config ディレクトリーも削除してしまうことに注意してください。
|
1.5. MicroProfile Config 設定ファイル
src/main/resources/META-INF/microprofile-config.properties にある MicroProfile Config 設定ファイル。
microprofile-config.propertiesgreeting.message=hello (1)
quarkus.http.port=9090 (2)| 1 | これは、ユーザー定義の設定プロパティーです。 |
| 2 | これは quarkus-vertx-http エクステンションによって消費される設定プロパティーです。 |
これは、Quarkus アプリケーション設定ファイル application.properties とまったく同じように機能します。Quarkus の application.properties を使用することをお勧めします。
|
2. Inject
Quarkus では、 MicroProfile Config アノテーションを使用して、アプリケーションに設定プロパティーを注入しています。
@ConfigProperty(name = "greeting.message") (1)
String message;| 1 | @Inject @ConfigProperty を使用することも、 @ConfigProperty だけを使用することもできます。 @Inject アノテーションは、 @ConfigProperty でアノテーションされたメンバーには必要ありません。 |
| アプリケーションが設定されていない設定プロパティーを注入しようとすると、エラーがスローされます。 |
@ConfigProperty(name = "greeting.message") (1)
String message;
@ConfigProperty(name = "greeting.suffix", defaultValue="!") (2)
String suffix;
@ConfigProperty(name = "greeting.name")
Optional<String> name; (3)| 1 | このプロパティーに値を指定しないと、アプリケーションの起動は javax.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message エラーで失敗します。 |
| 2 | デフォルト値は、設定が greeting.suffix の値を提供していない場合に注入されます。 |
| 3 | このプロパティーはオプションです - 設定が greeting.name の値を提供していない場合は、空の Optional が注入されます。 |
| Config Mappings を使用して、同様の設定プロパティーをグループ化します。 |
2.1. デフォルト値
プロパティーが (defaultValue 属性を介して) デフォルト値に関連付けられており、プロパティーに設定値が指定されていない場合、 javax.enterprise.inject.spi.DeploymentException をスローせずにデフォルト値が使用されます。 defaultValue の値は String として表され、設定値の処理に使用されるのと同じ変換メカニズムを使用します。プリミティブ、ボックス化されたプリミティブ、およびその他のクラス用に、いくつかの組み込みコンバーターがすでに存在します。以下に例を示します。
-
プリミティブ:
boolean、byte、shortなど -
ボックス化されたプリミティブ:
java.lang.Boolean、java.lang.Byte、java.lang.Shortなど -
オプションのコンテナー:
java.util.Optional、java.util.OptionalInt、java.util.OptionalLong、およびjava.util.OptionalDouble -
Java
enumタイプ -
JSR 310
java.time.Duration -
JDK ネットワーキング
java.net.SocketAddress、java.net.InetAddressなど
ご想像のとおり、これらのコンバーターは org.eclipse.microprofile.config.spi.Converter の実装です。したがって、これらのコンバーターは、次のような Microprofile またはカスタム実装プロバイダーの式ルールに準拠しています。
-
"true"、"1"、"YES"、"Y"、"ON" の場合、ブール値は
trueになる。それ以外の場合、値は false として解釈される -
float 型および double 型の値の場合、小数桁はドット
.で区切る必要がある
Optional* タイプと defaultValue 属性の組み合わせが使用される場合、定義された defaultValue が引き続き使用され、プロパティーに値が指定されていない場合、 Optional* が存在し、変換されたデフォルト値が入力されることに注意してください。ただし、プロパティーが明示的に空の場合、デフォルト値は使用されず、 Optional は空になります。この例を考えてみましょう。
# missing value, optional property
greeting.name =この場合、 greeting.name は上記の Optional* になるように設定されているため、対応するプロパティー値は空の Optional になり、実行は通常どおり続行されます。これは、デフォルト値が設定されている場合でも当てはまります。プロパティーが設定で明示的にクリアされている場合、デフォルト値は 使用されません。
一方、以下の例では、
# missing value, non-optional
greeting.suffix =起動時に java.util.NoSuchElementException: SRCFG02004: Required property greeting.message not found が発生し、デフォルト値は割り当てられません。
以下は、Quarkus が提供するコンバーターの例です。
@ConfigProperty(name = "server.address", defaultValue = "192.168.1.1")
InetAddress serverAddress;3. プログラムでアクセス
org.eclipse.microprofile.config.ConfigProvider.getConfig() APIを使用すると、Config APIにプログラムでアクセスすることができます。このAPIは、CDIインジェクションが利用できない状況で主に役立ちます。
String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);
設定値を取得するために System.getProperty(String) または System.getEnv(String) を使用しないでください。これらの API は設定に対応しておらず、このガイドで説明されている機能をサポートしていません。
|
4. プロファイル
多くの場合、ターゲットの 環境 に応じて、アプリケーションを異なる方法で設定する必要があります。たとえば、ローカルの開発環境は本番環境とは異なる場合があります。
設定プロファイルでは、同じファイルまたは個別のファイルで複数の設定を行い、プロファイル名を使用してそれらから選択できます。
4.1. プロパティー名のプロファイル
同じ名前のプロパティーを設定できるようにするには、各プロパティーは、 %{profile-name}.config.name の構文で、プロファイル名とドット . の前にパーセント記号 % を付ける必要があります。
quarkus.http.port=9090
%dev.quarkus.http.port=8181Quarkus HTTP ポートは 9090 になります。 dev プロファイルがアクティブな場合、8181 になります。
.env ファイルのプロファイルは構文 _{PROFILE}_CONFIG_KEY=value に従います。
QUARKUS_HTTP_PORT=9090
_DEV_QUARKUS_HTTP_PORT=8181プロファイルが特定の属性の値を定義していない場合、デフォルト (プロファイルなし) の値が使用されます。
bar=”hello”
baz=”bonjour”
%dev.bar=”hallo”dev プロファイルを有効にすると、プロパティー bar の値は hallo になりますが、プロパティー baz の値は bonjour になります。 prod プロファイルが有効になっている場合、 bar の値は hello (` prod` プロファイルには特定の値がないため) であり、 baz の値は bonjour です。
4.2. デフォルトのプロファイル
デフォルトでは、Quarkus は 3 つのプロファイルを提供し、特定の条件で自動的にアクティブになります。
-
dev - 開発モードのときに有効になる (つまり
quarkus:dev) -
test - テストを実行しているときに有効になる
-
prod - 開発モードまたはテストモード以外で使用されるデフォルトプロファイル
4.3. カスタムプロファイル
追加のプロファイルを作成し、 quarkus.profile 設定プロパティーを使用してそれらをアクティブ化することもできます。新しいプロファイル名を持つ単一の設定プロパティーが唯一の要件です。
quarkus.http.port=9090
%staging.quarkus.http.port=9999quarkus.profile を staging に設定すると、 staging プロファイルがアクティブになります。
|
|
4.4. プロファイル対応ファイル
この場合、特定のプロファイルのプロパティは、 application-{profile}.properties という名前のファイルに格納されます。先ほどの例は次のように表現できます。
quarkus.http.port=9090
%staging.quarkus.http.test-port=9091quarkus.http.port=9190
quarkus.http.test-port=9191|
このスタイルでは、プロファイル対応ファイルの設定名の前にプロファイル名を付ける必要はありません。 プロファイル対応ファイルのプロパティーは、メインファイルで定義されているプロファイル対応プロパティーよりも優先されます。 |
|
プロファイル対応ファイルは、メインの |
4.5. 親プロファイル
親プロファイルは、現在のプロファイルに 1 レベルの階層を追加します。設定 quarkus.config.profile.parent は、単一のプロファイル名を受け入れます。
親プロファイルがアクティブなときに、現在アクティブなプロファイルにプロパティーが見つからない場合、設定ルックアップは親プロファイルにフォールバックします。以下の例を考えてみます。
quarkus.profile=dev
quarkus.config.profile.parent=common
%common.quarkus.http.port=9090
%dev.quarkus.http.ssl-port=9443
quarkus.http.port=8080
quarkus.http.ssl-port=8443この場合、
-
アクティブなプロファイルは
devです -
親プロファイルは
commonです -
quarkus.http.portis 9090 -
quarkus.http.ssl-portis 9443
|
設定 |
5. プロパティー式
Quarkus は、設定値のプロパティー式拡張を提供します。式文字列は、プレーン文字列と式セグメントの組み合わせであり、シーケンス ${ … } でラップされます。
これらの式は、プロパティーの読み込み時に解決されます。したがって、設定プロパティーがビルド時である場合、プロパティー式はビルド時に解決されます。設定プロパティーが実行時にオーバーライド可能になると、実行時に解決されます。
以下だとすると、
remote.host=quarkus.io
callable.url=https://${remote.host}/callable.url プロパティーの解決された値は https://quarkus.io/ です。
別の例としては、プロファイルで異なるデータベースサーバーを定義できます。
%dev.quarkus.datasource.jdbc.url=jdbc:mysql://localhost:3306/mydatabase?useSSL=false
quarkus.datasource.jdbc.url=jdbc:mysql://remotehost:3306/mydatabase?useSSL=false次のように簡略化できます。
%dev.application.server=localhost
application.server=remotehost
quarkus.datasource.jdbc.url=jdbc:mysql://${application.server}:3306/mydatabase?useSSL=falseさらに、式拡張エンジンは次のセグメントをサポートします。
-
${expression:value}- 拡張で値が見つからない場合、:の後にデフォルト値を提供します。 -
${my.prop${compose}}- 構成された式。内部式が最初に解決されます。 -
${my.prop}${my.prop}- 複数の式。
式を展開できず、デフォルトが指定されていない場合、 NoSuchElementException が出力されます。
| 式のルックアップは、すべての設定ソースで実行されます。式の値と展開値は、異なる設定ソースに存在する場合があります。 |
6. 生成中の UUID へのアクセス
Quarkus のデフォルトの設定ソースはランダムな UUID 値を提供します。起動時に UUID を生成します。そのため、開発モードでのリロードを含め、スタートアップ間で値が変化します。
生成された値には、 quarkus.uuid プロパティーを使用してアクセスできます。expressions を使用してアクセスします (${quarkus.uuid})。たとえば、Kafka クライアントを一意のコンシューマーグループで設定する場合に便利です。
mp.messaging.incoming.prices.group.id=${quarkus.uuid}7. プロパティーの削除
任意であり、ビルド時に値が設定されていたり、デフォルト値が設定されていたりする実行時プロパティーは、空の文字列をプロパティーに代入することで明示的に削除することができます。これは実行時プロパティーに のみ 影響し、値が必須ではないプロパティーで のみ 動作することに注意してください。
remote.host=quarkus.io-Dremote.host= を指定して remote.host を検索すると、システムプロパティーが値をクリアしたため、例外がスローされます。
8. インデックスされたプロパティ
エスケープされていないコンマを含む設定値は、 Collection に変換できます。これは単純なケースでは機能しますが、面倒になり、より高度なケースでは制限されます。
インデックス付きプロパティーは、設定プロパティー名のインデックスを使用して、 Collection タイプの特定の要素をマップする方法を提供します。インデックス付き要素はプロパティー名の一部であり、値に含まれていないため、これを使用して、複雑なオブジェクトタイプを Collection 要素としてマップすることもできます。以下の例の場合、
my.collection=dog,cat,turtle
my.indexed.collection[0]=dog
my.indexed.collection[1]=cat
my.indexed.collection[2]=turtleインデックス付きプロパティーの構文では、プロパティー名と大かっこ [ ] を使用し、その間にインデックスを付けます。
Config#getValues("my.collection", String.class) を呼び出すと、値 dog、 cat、および turtle が含まれる List<String> が自動的に作成および変換されます。 Config#getValues("my.indexed.collection", String.class) を呼び出すと、まったく同じ結果が返されます。同じプロパティー名が両方の形式 (通常およびインデックス付き) に存在する場合、通常の値が優先されます。
インデックス付きのプロパティーは、ターゲットの Collection に追加される前に、インデックスで並べ替えられます。インデックスに含まれるギャップはターゲットの Collection に解決されません。つまり、 Collection の結果にはギャップのないすべての値が格納されます。
9. Quarkus の設定
Quarkus自体は、アプリケーションと同じメカニズムで設定されます。Quarkusは、自身の設定のために quarkus. 名前空間を予約します。例えば、HTTPサーバーポートを設定するには、 quarkus.http.port を application.properties に設定します。Quarkusのすべての設定プロパティは 文書化されており、検索可能です。
|
上述したように、 |
9.1. ビルド時設定
Quarkusの設定の中には、ビルド時にのみ有効になるものがあり、ランタイムに変更することはできません。これらの設定はランタイムでも利用可能ですが、読み取り専用であり、Quarkusの動作には影響しません。これらの設定を変更するには、そのようなプロパティの変更を反映させる場合、アプリケーション自体を再ビルドする必要があります。
| ビルド時に固定されたプロパティーは、 すべての設定オプションのリスト でロックアイコン () でマークされます。 |
しかし、いくつかのエクステンションは 実行時にオーバーライド可能な プロパティーを定義しています。定型的な例としては、データベースの URL、ユーザー名とパスワードがあります。これはターゲット環境によって定まるものであり、実行時にセットされ、アプリケーションの動作に影響を与えるものです。
10. アプリケーションが公開された後、ビルド時のプロパティー変更
アプリケーションのビルド後にビルド時の設定を変更する必要があるというまれな状況にある場合は、再オーグメンテーション を使用して、別のビルド時設定のオーグメンテーション出力を再ビルドする方法を確認してください。
11. 追加情報
Quarkus は SmallRye Config に依存しており、その機能を継承しています。
-
追加
ConfigSource -
追加
Converter -
インデックスされたプロパティ
-
親プロファイル
-
設定値解決のためのインターセプタ―
-
設定プロパティーの移動
-
設定プロパティーのフォールバック
-
ロギング
-
シークレットを隠す
詳細は、SmallRye Config のドキュメント を参照してください。
12. 設定リファレンス
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
Profile that will be active when Quarkus launches. Environment variable: Show more |
string |
|
Accepts a single configuration profile name. If a configuration property cannot be found in the current active profile, the config performs the same lookup in the profile set by this configuration. Environment variable: Show more |
string |
|
Additional config locations to be loaded with the Config. The configuration support multiple locations separated by a comma and each must represent a valid Environment variable: Show more |
list of URI |
|
A property that allows accessing a generated UUID. It generates that UUID at startup time. So it changes between two starts including in dev mode.
Access this generated UUID using expressions: Environment variable: Show more |
string |
