設定リファレンスガイド
本ガイドの内容を改訂し、さらにトピックを分割しました。Additional Informationをご覧ください。 |
このリファレンスガイドでは、Quarkus の設定の様々な側面について説明します。Quarkus アプリケーションと Quarkus 自体 (コアとエクステンション) の両方は、 MicroProfile Config 仕様の実装である SmallRye Config APIを活用した同じメカニズムを介して設定されます。
Quarkus エクステンションを設定可能にする方法については、Writing Your Own Extension ガイドを参照してください。 |
1. 設定ソース
デフォルトでは、Quarkus は複数のソースから設定プロパティーを読み取ります (降順)。
-
(400) System properties
-
(300) Environment variables
-
(295) 現在の作業ディレクトリーの .env ファイル
-
(260)
$PWD/config/application.properties
の Quarkus Application configuration file -
(250) クラスパスの Quarkus Application configuration file
application.properties
-
(100) クラスパスの MicroProfile Config configuration file
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 specifies additional conversion rules. |
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.properties
greeting.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.properties
greeting.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
など
As you might expect, these converters are org.eclipse.microprofile.config.spi.Converter
implementations. Therefore, these converters comply with the Microprofile or custom implementation providers expression rules like:
-
"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=8181
Quarkus 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=9999
quarkus.profile
を staging
に設定すると、staging
プロファイルがアクティブになります。
一度にアクティブにできるプロファイルは 1 つだけです。 |
|
4.4. プロファイル対応ファイル
この場合、特定のプロファイルのプロパティは、 application-{profile}.properties
という名前のファイルに格納されます。先ほどの例は次のように表現できます。
quarkus.http.port=9090
%staging.quarkus.http.test-port=9091
quarkus.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.port
is 9090 -
quarkus.http.ssl-port
is 9443
The configuration |
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
に変換できます。これは単純なケースでは機能しますが、面倒になり、より高度なケースでは制限されます。
Indexed Properties provide a way to use indexes in config property names to map specific elements in a Collection
type. Since the indexed element is part of the property name and not contained in the value, this can also be used to map complex object types as Collection
elements. Consider:
my.collection=dog,cat,turtle
my.indexed.collection[0]=dog
my.indexed.collection[1]=cat
my.indexed.collection[2]=turtle
インデックス付きプロパティーの構文では、プロパティー名と大かっこ [ ] を使用し、その間にインデックスを付けます。
A call to Config#getValues("my.collection", String.class)
, will automatically create and convert a List<String>
that contains the values dog
, cat
and turtle
. A call to Config#getValues("my.indexed.collection", String.class)
returns the exact same result. If the same property name exists in both forms (regular and indexed), the regular value has priority.
インデックス付きのプロパティーは、ターゲットの 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
-
インデックスされたプロパティ
-
親プロファイル
-
設定値解決のためのインターセプタ―
-
設定プロパティーの移動
-
設定プロパティーのフォールバック
-
ロギング
-
シークレットを隠す
For more information, please check the SmallRye Config documentation.
12. 設定リファレンス
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
---|---|---|
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: |
list of URI |
|
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: |
string |
|
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: |
string |