The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

設定リファレンスガイド

このリファレンスガイドでは、Quarkus の設定の様々な側面について説明します。Quarkus アプリケーションと Quarkus 自体 (コアとエクステンション) の両方は、 MicroProfile Config 仕様の実装である SmallRye Config APIを活用した同じメカニズムを介して設定されます。

Quarkus エクステンションを設定可能にする方法については、独自のエクステンションの作成 ガイドを参照してください。

1. 設定ソース

デフォルトでは、Quarkus は複数のソースから設定プロパティーを読み取ります (降順)。

  1. (400) System properties

  2. (300) Environment variables

  3. (295) 現在の作業ディレクトリーの .env ファイル

  4. (260) $PWD/config/application.properties の Quarkus アプリケーション設定ファイル

  5. (250) クラスパスの Quarkus アプリケーション設定ファイル application.properties

  6. (100) クラスパスの MicroProfile Config 設定ファイル META-INF/microprofile-config.properties

最終的な設定は、これらすべてのソースによって定義されたプロパティーの集約です。設定プロパティーのルックアップは、使用可能な最も高い序数の設定ソースから始まり、一致するものが見つかるまで他のソースに下がっていきます。つまり、上位の序数設定ソースに別の値を設定するだけで、設定プロパティーが値をオーバーライドする可能性があります。たとえば、環境プロパティーを使用して設定されたプロパティーは、 application.properties ファイルを使用して提供された値をオーバーライドします。

config sources

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 で指定された変換ルールに従います。 Config は、指定されたプロパティ名に対して 3 つの環境変数を検索します (例: foo.BAR.baz )：

  • foo.BAR.baz - 完全一致

  • foo_BAR_baz - 英数字でもなく、 でもない各文字を、 で置換

  • FOO_BAR_BAZ - 英数字でも でもない各文字を で置換。その後、名前を大文字に変換

SmallRye Configでは、 追加の変換ルール を指定しています。

  • 二重引用符で囲まれたプロパティ foo."bar".baz の場合、英数字でも でもない各文字を で置換します: FOOBARBAZ

  • ダッシュを含むプロパティ foo.bar-baz の場合、英数字でも でもない各文字を で置換します: FOO_BAR_BAZ

  • インデックス付きプロパティ foo.bar[0] または foo.bar[0].baz の場合、英数字でも でもない各文字を で置換します : FOO_BAR_0_ または FOO_BAR_0__BAZ

状況によ っ ては、 正確なプ ロ パテ ィ 名を検索す る こ と が不可能な場合 も あ り ます。これは、ユーザー定義のパスセグメントを含む設定名の場合です。

環境変数名の変換ルールを適用すると、 quarkus.datasource."datasource-name".jdbc.url は QUARKUS_DATASOURCEDATASOURCE_NAMEJDBC_URL になります。 設定システムで両方のプロパティが利用可能であれば、設定は期待通りに動作します。

QUARKUS_DATASOURCEDATASOURCE_NAMEJDBC_URL のみが存在する場合、Config システムは設定名を最も可能性の高いドット形式に再変換する必要があります。これは固定コンフィギュレーションセグメントに対しては問題なく機能しますが、ダイナミックセグメントを含む名前に対しては機能しません。この場合、Quarkusは DATASOURCE_NAME を datasource.name や datasource-name （またはその他の特殊文字区切り）に変換すべきかどうかを判断できません。

このため、このようなプロパティは常に、環境変数名を曖昧にしないために、別のソースでのドット付きバージョン名を必要とします。 これは、双方向変換を実行し、プロパティ名を一緒に一致させるための追加情報を提供します。

# value can be left empty but must be supplied by another source at runtime (or be an optional)
quarkus.datasource."datasource-name".jdbc.url=
EXPORT QUARKUS_DATASOURCE__DATASOURCE_NAME__JDBC_URL=jdbc:postgresql://localhost:5432/database

1.3. 現在の作業ディレクトリーにある .env ファイル

.env
QUARKUS_DATASOURCE_PASSWORD=youshallnotpass (1)
1 QUARKUS_DATASOURCE_PASSWORD という名前は、 環境変数 で使われたのと同じ変換ルールに従います。

dev モードの場合、このファイルはプロジェクトのルートに置くことができるが、通常パスワードやアクセストークン、APIキーなどの秘密が含まれているため、バージョン管理にはチェックイン しない ことをお勧めします。

.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 を使用することをお勧めします。

1.6. ロケーション

Quarkus は、設定プロパティーファイルをデフォルトの設定場所だけでなく、別の場所でもスキャンするための方法を提供します。

quarkus.config.locations 設定プロパティーは、コンマ , で区切られた複数の場所を受け入れます。 場所は、それぞれ有効な URI を表す必要があります。サポートされている URI スキームは次のとおりです。

  • ファイルまたはディレクトリー (file:)

  • クラスパスリソース

  • jar リソース (jar:)

  • http リソース (http:)

読み込まれたすべてのソースは、 quarkus.config.locations 設定プロパティーを見つけたソースと同じ序数を使用します。たとえば、 quarkus.config.locations がシステムプロパティーとして設定されている場合、ロードされたすべてのソースの序数は 400 に設定されています (システムプロパティーは序数として 400 を使用します)。序数は、 config_ordinal と序数値を設定することで、設定ソースごとに直接オーバーライドできます。 config_ordinal プロパティーは、設定されているソースの序数にのみ影響します。ソースは、まず序数でソートされ、次に場所の順序、最後に読み込み順序でソートされます。

1.7. その他の設定ソース

Quarkus は、他の設定フォーマットとストアをカバーする追加のエクステンションを提供します。

Custom Config Source を作成することもできます。

2. ConfigMapping

Quarkus アプリケーションに設定を公開するための推奨される方法は、インターフェースでマッピングすることです。 SmallRye Config Mappings を使用すると、同じプレフィックス (または名前空間) を共有する複数の設定プロパティーを単一のインターフェースにグループ化できます。以下の機能セットをサポートしています。

  • List、 Set、 Map、 Optional、およびプリミティブ型を含む、設定型の自動変換。

  • ネストされた設定マッピンググループ。

  • 設定プロパティーの命名戦略

  • Bean Validation との統合

設定マッピングには、 @io.smallrye.config.ConfigMapping アノテーションが付与された最小限のメタデータ設定を持つインターフェースが必要です。

@ConfigMapping(prefix = "server")
public interface Server {
    String host();

    int port();

    int sslPort();
}

複雑なオブジェクト型は、以下のルールを使用して設定値をメンバーの値にマッピングします。

  • 設定パスは、オブジェクト型のプレフィックス (または名前空間) とマッピングメンバー名を取得して構築されます。

  • メンバー名はケバブケース (kebab-case) 形式に変換されます。

  • メンバー名がゲッターとして表現されている場合、メンバー名はそのプロパティー名に相当するものから取得され、ケバブケース形式に変換されます。

  • 設定値は自動的にメンバー型に変換されます。

  • 設定パスには有効な設定値が存在する必要があります。存在しない場合、マッピングは失敗します。

Kebab-case - メソッド名は、設定プロパティーをマッピングするために、大文字と小文字の変化をダッシュに置き換えることで派生します。

Server インターフェースは、 server.host という名前の設定プロパティーを Server.host() メソッドに、 server.port を Server.port() メソッドに、 server.ssl-port を Server.sslPort() メソッドにマッピングできます。検索対象の設定プロパティー名は、プレフィックスとメソッド名 (ケバブケース) をドット (.) 文字で区切って構築されます。

@ConfigMapping は、任意の CDI 対応 Bean にインジェクトできます。

@ApplicationScoped
class BusinessBean {
    @Inject
    Server server;

    void businessMethod() {
        String host = server.host();
    }
}

非 CDI コンポーネントの場合は、 io.smallrye.config.SmallRyeConfig#getConfigMapping API を使用して設定マッピングインスタンスを取得します。

SmallRyeConfig config = ConfigProvider.getConfig().unwrap(SmallRyeConfig.class);
Server server = config.getConfigMapping(Server.class);
@ConfigMapping を使用した高度な用法については、 オブジェクトへの設定のマッピング ガイドを確認してください。

3. ConfigProperty

@ConfigMapping が推奨されるアプローチですが、 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 このプロパティーに値を提供しない場合、アプリケーションの起動は io.quarkus.runtime.configuration.ConfigurationException: Failed to load config value of type class java.lang.String for: greeting.messagee で失敗します。
2 デフォルト値は、設定が greeting.suffix の値を提供していない場合に注入されます。
3 このプロパティーは任意です。設定が greeting.name の値を提供していない場合は、空の Optional が注入されます。
Config Mappings を使用して、同様の設定プロパティーをグループ化します。

4. デフォルト値

設定に (io.smallrye.config.WithDefault または org.eclipse.microprofile.config.inject.ConfigProperty.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* 型とデフォルト値を組み合わせて使用する場合、定義されたデフォルト値が引き続き使用されます。プロパティーに値が指定されていない場合、 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 が発生し、デフォルト値は割り当てられません。

5. プログラムでアクセス

io.smallrye.config.SmallRyeConfig API を使用すると、プログラムで設定 API にアクセスできます。この API は、主に CDI インジェクションが利用できない状況で役立ちます。

SmallRyeConfig config = org.eclipse.microprofile.config.ConfigProvider.getConfig().unwrap(SmallRyeConfig.class);
String databaseName = config.getValue("database.name", String.class);
Optional<String> maybeDatabaseName = config.getOptionalValue("database.name", String.class);
設定値を取得するために System.getProperty(String) または System.getEnv(String) を使用しないでください。これらの API は設定に対応しておらず、このガイドで説明されている機能をサポートしていません。

6. プロファイル

私たちはしばしば、ターゲット 環境 に応じてアプリケーションを異なるように設定する必要があります。たとえば、ローカルの開発環境と本番環境は異なるかもしれません。

設定プロファイルでは、同じファイルまたは個別のファイルで複数の設定を行い、プロファイル名を使用してそれらから選択できます。

6.1. プロパティー名のプロファイル

同じ名前のプロパティーを設定できるようにするには、各プロパティーは、 %{profile-name}.config.name の構文で、プロファイル名とドット . の前にパーセント記号 % を付ける必要があります。

application.properties
quarkus.http.port=9090
%dev.quarkus.http.port=8181

Quarkus HTTP ポートは 9090 になります。 dev プロファイルがアクティブな場合、8181 になります。

.env ファイルのプロファイルは構文 _{PROFILE}_CONFIG_KEY=value に従います。

.env
QUARKUS_HTTP_PORT=9090
_DEV_QUARKUS_HTTP_PORT=8181

プロファイルが特定の属性の値を定義していない場合、デフォルト (プロファイルなし) の値が使用されます。

application.properties
bar=”hello”
baz=”bonjour”
%dev.bar=”hallo”

dev プロファイルを有効にすると、プロパティー bar の値は hallo になりますが、プロパティー baz の値は bonjour になります。 prod プロファイルが有効になっている場合、 bar の値は hello (` prod` プロファイルには特定の値がないため) であり、 baz の値は bonjour です。

6.2. デフォルトのプロファイル

デフォルトでは、Quarkus は 3 つのプロファイルを提供し、特定の条件で自動的にアクティブになります。

  • dev - 開発モードのときに有効になる (つまり quarkus:dev)

  • test - テストを実行しているときに有効になる

  • prod - 開発モードまたはテストモード以外で使用されるデフォルトプロファイル

6.3. カスタムプロファイル

追加のプロファイルを作成し、 quarkus.profile 設定プロパティーを使用してそれらをアクティブ化することもできます。新しいプロファイル名を持つ単一の設定プロパティーが唯一の要件です。

application.properties
quarkus.http.port=9090
%staging.quarkus.http.port=9999

quarkus.profile を staging に設定すると、 staging プロファイルがアクティブになります。

io.quarkus.runtime.configuration.ConfigUtils.getProfiles API は、プログラムでアクティブなプロファイルを取得する方法を提供します。

6.4. プロファイル対応ファイル

この場合、特定のプロファイルのプロパティは、 application-{profile}.properties という名前のファイルに格納されます。先ほどの例は次のように表現できます。

application.properties
quarkus.http.port=9090
%staging.quarkus.http.test-port=9091
application-staging.properties
quarkus.http.port=9190
quarkus.http.test-port=9191

このスタイルでは、プロファイル対応ファイルの設定名の前にプロファイル名を付ける必要はありません。

プロファイル対応ファイル内のプロパティーは、メインファイルで定義されているプロファイル対応プロパティーよりも優先されます。

quarkus.profile または quarkus.test.profile を設定する際に、プロファイル対応ファイルは使用しないでください。これらのプロファイルは、プロファイル対応ファイルをロードする前に必要になるため、この方法は機能しません。

ファイルを設定に含めて一貫した順序でロードするためには、 application.properties ファイルがプロファイル対応ファイル (application-{profile}.properties) の正確な場所に (空の場合でも) 存在する必要があります。

6.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

quarkus.config.profile.parent を設定するために、プロファイル対応ファイルを使用しないでください。プロファイル対応ファイルをロードする前にプロファイルが必要になるため、この方法ではうまくいきません。

6.6. 複数のプロファイル

複数のプロファイルを同時にアクティブにすることができます。 quarkus.profile 設定では、カンマで区切られたプロファイル名のリストを受け付けます: quarkus.profile=common,dev 。 common と dev はどちらも別のプロファイルです。

複数のプロファイルが有効な場合、プロファイル設定に関するルールは同じです。2つのプロファイルが同じ設定を定義している場合、最後にリストされたプロファイルが優先されます。と考えてください:

application.properties
quarkus.profile=common,dev

my.prop=1234
%common.my.prop=1234
%dev.my.prop=5678

%common.commom.prop=common
%dev.dev.prop=dev
%test.test.prop=test

この場合、

  • common.prop 値は common

  • dev.prop 値は dev

  • my.prop 値は 5678

  • test.prop 値は value

また、プロファイル名をカンマで区切って、複数のプロファイルプロパティを定義することも可能です。同じプロパティ名が複数のプロファイルプロパティに存在する場合、最も具体的なプロファイルを持つプロパティ名が優先されます:

application.properties
quarkus.profile=dev

%prod,dev.my.prop=1234
%dev.my.prop=5678

%prod,dev.another.prop=1234

この場合、

  • my.prop の値は5678です。

  • another.prop の値は1234です。

複数のプロファイルの優先順位は逆順で動作します。 quarkus.profile=common,dev の場合、Quarkus はまず dev プロファイルを、次に common プロファイルをチェックします。

7. プロパティー式

Quarkus は、設定値のプロパティー式拡張を提供します。式文字列は、プレーン文字列と式セグメントの組み合わせであり、シーケンス ${ …​ } でラップされます。

これらの式は、プロパティーの読み込み時に解決されます。したがって、設定プロパティーがビルド時である場合、プロパティー式はビルド時に解決されます。設定プロパティーが実行時にオーバーライド可能になると、実行時に解決されます。

以下だとすると、

application.properties
remote.host=quarkus.io
callable.url=https://${remote.host}/

callable.url プロパティーの解決された値は https://quarkus.io/ です。

別の例としては、プロファイルで異なるデータベースサーバーを定義できます。

application.properties
%dev.quarkus.datasource.jdbc.url=jdbc:mysql://localhost:3306/mydatabase?useSSL=false
quarkus.datasource.jdbc.url=jdbc:mysql://remotehost:3306/mydatabase?useSSL=false

次のように簡略化できます。

application.properties
%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 が出力されます。

式のルックアップは、すべての設定ソースで実行されます。式の値と展開値は、異なる設定ソースに存在する場合があります。

7.1. 環境変数を使用

プロパティー式は環境変数でも機能します。

application.properties
remote.host=quarkus.io
application.host=${HOST:${remote.host}}

これは HOST 環境変数を展開し、 HOST が設定されていない場合は、プロパティー remote.host の値をデフォルト値として使用します。

8. シークレット・キー式

シークレット設定は、 ${handler::value} と表現することができます。 handler は、 value を解読または復号するための io.smallrye.config.SecretKeysHandler の名前です :

application.properties
my.secret=${aes-gcm-nopadding::DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg}

# the encryption key required to decode the secret. It can be set in any source.
smallrye.config.secret-handler.aes-gcm-nopadding.encryption-key=somearbitrarycrazystringthatdoesnotmatter

my.secret を読み出すと、 aes-gcm-nopadding という名前の SecretKeysHandler を使って、値 DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg がデコードされます。

詳しくは、SmallRye Config Secret Keys のドキュメントをご確認ください。

SmallRye Configは、Quarkusが完全にサポートしていないハンドラを提供する場合があります。現在のところ、 smallrye-config-crypto のみがサポートされています。

9. 生成中の UUID へのアクセス

Quarkus のデフォルトの設定ソースはランダムな UUID 値を提供します。起動時に UUID を生成します。そのため、開発モードでのリロードを含め、スタートアップ間で値が変化します。

生成された値には、 quarkus.uuid プロパティーを使用してアクセスできます。アクセスするには、expressions を使用します (${quarkus.uuid})。たとえば、一意のコンシューマーグループを使用して Kafka クライアントを設定する場合に便利です。

mp.messaging.incoming.prices.group.id=${quarkus.uuid}

10. プロパティーの削除

任意であり、ビルド時に値が設定されていたり、デフォルト値が設定されていたりする実行時プロパティーは、空の文字列をプロパティーに代入することで明示的に削除することができます。これは実行時プロパティーに のみ 影響し、値が必須ではないプロパティーで のみ 動作することに注意してください。

application.properties
remote.host=quarkus.io

-Dremote.host= を指定して remote.host を検索すると、システムプロパティーが値をクリアしたため、例外がスローされます。

11. インデックスされたプロパティ

エスケープされていないコンマを含む設定値は、 Collection に変換できます。これは単純なケースでは機能しますが、面倒になり、より高度なケースでは制限されます。

インデックス付きプロパティーは、設定プロパティー名のインデックスを使用して、 Collection タイプの特定の要素をマップする方法を提供します。インデックス付き要素はプロパティー名の一部であり、値に含まれていないため、これを使用して、複雑なオブジェクトタイプを Collection 要素としてマップすることもできます。以下の例の場合、

application.properties
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 の結果にはギャップのないすべての値が格納されます。

12. Quarkus の設定

Quarkus自体は、アプリケーションと同じメカニズムで設定されます。Quarkusは、自身の設定のために quarkus. 名前空間を予約します。例えば、HTTPサーバーポートを設定するには、 quarkus.http.port を application.properties に設定します。Quarkusのすべての設定プロパティは 文書化されており、検索可能です。

上述したように、 quarkus. で始まるプロパティーは、Quarkus 自体を設定するために実質的に予約されているため、アプリケーション固有のプロパティーのプレフィックスとして quarkus. を使用してはいけ ません 。

12.1. ビルド時設定

一部の Quarkus 設定はビルド時 (コンパイル時) にのみ有効になり、実行時に変更することはできません。これらの設定は実行時にも読み取り専用として利用可能ですが、 Quarkus の動作には影響しません。これらの設定を変更した場合は、プロパティーの変更を反映させるためにアプリケーション自体の再ビルドが必要です。これにより、 Quarkus は現在のビルド設定に基づいて最適化を提供し、複雑さを軽減することができます。デフォルトでは、 Quarkus は prod 設定プロファイルを使用してアプリケーションをビルドします。

ビルド時に固定されたプロパティーは、 すべての設定オプションのリスト でロックアイコン () でマークされます。

しかし、いくつかのエクステンションは 実行時にオーバーライド可能な プロパティーを定義しています。定型的な例としては、データベースの URL、ユーザー名とパスワードがあります。これはターゲット環境によって定まるものであり、実行時にセットされ、アプリケーションの動作に影響を与えるものです。

12.2. 設定の記録

ビルドプロセス中に、 Quarkus は最終的なバイナリに必要な設定が不足せずに実行時に正常に起動できるように、利用可能な設定を記録します。以下のソースは記録から除外されます。

  • システムプロパティ

  • 環境変数

  • .env

  • ビルドシステムソース (Maven または Gradle によって提供されるもの)

12.3. デフォルトの実行時プロファイル

デフォルトの Quarkus 実行時プロファイルは、アプリケーションのビルドに使用されるプロファイルに設定されます。

./mvnw package -Dnative -Dquarkus.profile=prod-aws
./target/my-app-1.0-runner (1)
1 コマンドは、 prod-aws プロファイルで実行されます。これは quarkus.profile 設定を使用して上書きすることができます。

アプリケーションのビルド時に使用したものとは異なる設定プロファイルを実行時に使用すると、予期しない結果を招く可能性があります。

13. ビルド後の設定変更 (再オーグメンテーション)

アプリケーションのビルド後にビルド時の設定を変更する必要があるというまれな状況にある場合は、再オーグメンテーション を使用して、別のビルド時設定のオーグメンテーション出力を再ビルドする方法を確認してください。

14. ビルド時に使用される有効なビルド時設定の追跡

設定ソースは通常、ビルド中に実際に使用されるよりも多くのオプションを提供するため、Quarkusのビルドプロセスで実際に使用された設定オプションを知ることは有益です。

14.1. ビルド中に読み込まれたビルド時設定オプションのダンプ

quarkus.config-tracking.enabled を true に設定すると、設定インターセプターが有効になり、ビルドプロセス中に読み込まれたすべての設定オプションを、その値とともに記録します。結果のレポートはデフォルトで ${project.basedir}/.quarkus/quarkus-prod-config-dump に保存されます。ターゲット・ファイルは以下のオプションで設定できます：

  • quarkus.config-tracking.directory - 設定ダンプが保存されるディレクトリ、デフォルトは ${project.basedir}/.quarkus

  • quarkus.config-tracking.file-prefix - ファイル名のプレフィックス、デフォルト値は quarkus

  • quarkus.config-tracking.file-suffix - ファイル名のサフィックス、デフォルト値は -config-dump

  • quarkus.config-tracking.file - 設定ダンプを保存するファイルへのパス。このオプションは file-prefix と file-suffix のオプションに優先します。また、値が相対パスでない限り、 quarkus.config-tracking.directory の値にも優先します。

quarkus-prod-config-dump ファイル名の prod 部分は Quarkus ビルドモードを参照します。これは、ダンプが実稼働環境用のビルドのために取得されたことを示します。

${project.basedir}/.quarkus ディレクトリーがデフォルトの場所として選択された理由は、ビルド時におけるビルド間の設定変更を追跡しやすくするためです。出力キャッシュツール (Apache Maven Build Cache や Develocity Build Cache など) は、これを指標として使用することで、アプリケーションバイナリーを再構築する必要があるかどうかを判断できます。

14.1.1. 設定オプションのフィルタリング

除外する設定オプション名のコンマ区切りリストを使用して quarkus.config-tracking.exclude を設定することで、設定トラッカーにレポートから一部のオプションを除外するように指示できます。

14.1.2. パス値

ユーザーのホームディレクトリーで始まる 絶対 パス値を持つ設定オプションは、デフォルトでは、ユーザーのホームディレクトリー部分を Unix ホームディレクトリーエイリアス '~' に置き換え、パス要素の区切り文字として / を使用して変換されます。

この変換は、 quarkus.config-tracking.use-user-home-alias-in-paths を false に設定することで無効にできます。

14.1.3. 記録された設定値のハッシュ化

設定値は、ファイルに書き込まれる前に SHA-512 アルゴリズムを使用してハッシュ化できます。値をハッシュ化する必要がある設定オプション名は、 quarkus.config-tracking.hash-options でコンマ区切りのリストとして設定できます。

14.2. ビルド間のビルド時設定の変化の追跡

quarkus.config-tracking.enabled は効果的なビルド時設定レポートの生成を有効にしますが、プロジェクトの次のビルドが開始される前に、そのレポートに保存されている値が変更されたかどうかを確認する方法もあります。

Maven プロジェクトでは、 quarkus-maven-plugin 設定に次のゴールを追加できます。

      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <executions>
          <execution>
            <id>track-prod-config-changes</id>
            <phase>process-resources</phase>
            <goals>
              <goal>track-config-changes</goal>
            </goals>
          </execution>
        </executions>

track-config-changes ゴールは ${project.basedir}/.quarkus/quarkus-prod-config-dump (ファイル名とディレクトリーは設定可能) を検索し、ファイルがすでに存在する場合は、設定ダンプに保存されている値が変更されているかどうかを確認します。 変更されたオプションを記録し、 ${project.basedir}/target/quarkus-prod-config.check (ターゲットファイル名と場所は設定可能) の ${project.basedir}/.quarkus/quarkus-prod-config-dump にある各オプションの現在の値を保存します。ビルド時の設定が前回のビルドから変更されていない場合は、 ${project.basedir}/.quarkus/quarkus-prod-config-dump と ${project.basedir}/.quarkus/quarkus-prod-config-dump はまったく同じになります。

14.2.1. Quarkus アプリケーションの依存関係をダンプする

track-config-changes ゴールは、設定値だけでなく、Quarkus ビルド時の依存関係を含むすべての Quarkus アプリケーションの依存関係もダンプします。 このファイルは、たとえば Develocity のクラスパスのチェックサム機能と組み合わせて、Quarkus ビルドクラスパスが前回の実行以降に変更されたかどうかを確認するために使用できます。 デフォルトでは、依存関係のリストは target/quarkus-prod-dependencies.txt ファイルに保存されます。プラグインパラメーターを使用して別の場所を設定することもできます。

14.2.2. 記録された設定が見つからない場合、現在のビルド時設定をダンプする

デフォルトでは、 track-config-changes は前回のビルド時に記録された設定を探し、見つからなければ何もしない。 dumpCurrentWhenRecordedUnavailable パラメータを有効にすると、 quarkus.config-tracking.* の設定を考慮して、現在のビルド設定オプションをダンプします。

quarkus:build ゴールで記録されたビルド設定オプションとは異なり、 dumpCurrentWhenRecordedUnavailable を有効にした quarkus:track-config-changes で保存された設定オプションには、 org.eclipse.microprofile.config.Config インスタンスにより公開されたすべてのビルド設定オプションが含まれます。 つまり、このレポートには、Quarkus アプリケーションのビルドプロセスでは使用されないビルド設定オプションが含まれている可能性があります。しかし MicroProfile Config 仕様では、設定ソースがユーザーに提供する一部のプロパティー名を非公開にできるため、いくつかのビルド設定オプションが欠落している可能性もあります。

15. 静的初期化フェーズで注入される設定プロパティ値

Quarkus は、静的初期化フェーズ で CDI Bean に注入された設定プロパティー値を収集します。 収集された値はランタイムの初期化値と比較され、不一致が検出されるとアプリケーションの起動は失敗します。 どうしてそんなことが起こるのでしょうか? たとえば、 org.acme.MyBean という CDI Bean があるとします。 MyBean は foo という名前の @ConfigProperty を注入し、ネイティブビルド中に初期化されます。 ネイティブビルド中は設定プロパティーが存在しないため、デフォルト値 bar が使用されます。 しかし、後でアプリケーションが起動されると、プロパティーはシステムプロパティー -Dfoo=baz で定義されます。 これにより、一貫性のない状態と予期しない動作が発生します。 したがって、この状況になると Quarkus はデフォルトで失敗します。

package org.acme;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import jakarta.enterprise.context.Initialized;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
public class MyBean {

   @ConfigProperty(name = "foo", defaultValue = "bar") (1)
   String foo;

    void onInit(@Observes @Initialized(ApplicationScoped.class) Object event) { (2)
       // this observer method is notified during STATIC_INIT...
    }
}
1 設定プロパティはBeanの生成時に注入され、値は固定されます。
2 この特定のケースでは、オブザーバー @Initialized(ApplicationScoped.class) が Bean の初期化を引き起こしました。しかし、他の可能性もあります。例えば、静的初期化フェーズでコンポーネントを初期化するエクステンションもあります。

注入されたフィールド/パラメータに @io.quarkus.runtime.annotations.StaticInitSafe のアノテーションを付けることで、静的初期化フェーズで注入された設定オブジェクトを安全に初期化できるようにマークすることができます。

package org.acme;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import jakarta.enterprise.context.Initialized;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import io.quarkus.runtime.annotations.StaticInitSafe;

@ApplicationScoped
public class MyBeanNoFailure {

   @StaticInitSafe (1)
   @ConfigProperty(name = "foo", defaultValue = "bar")
   String foo;

    void onInit(@Observes @Initialized(ApplicationScoped.class) Object event) {
       // this observer method is notified during STATIC_INIT...
    }
}
1 不一致が検出された場合にQuarkusが失敗しないように指示します。

16. 追加情報

Quarkus は SmallRye Config に依存しており、その機能を継承しています。

詳しくは、 SmallRye Configのドキュメント をご確認ください。

17. 設定リファレンス

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは実行時にオーバーライド可能

Configuration property

タイプ

デフォルト

quarkus.config.sources.system-only

Set this to true to read configuration from system properties and environment variables only. This only applies to runtime.

Environment variable: QUARKUS_CONFIG_SOURCES_SYSTEM_ONLY

Show more

ブーリアン

false

quarkus.config.fixed-at-build-time

If set to true, all configuration is frozen at build time. All values from application.properties and similar file-based sources are baked into the application artifact at the highest priority. At runtime, no external configuration sources are consulted: no application.properties, no .env files, no system properties, and no environment variables can affect configuration values.

The only exceptions are a small set of JVM environment properties (java.io.tmpdir, user.home, user.dir) which are resolved at runtime to support @WithDefault expressions whose values are inherently machine-dependent.

This is useful for CLI applications and sealed/immutable deployments where the binary’s behavior must be fully determined at build time.

Computed defaults (@WithDefault) and programmatic values set by recorders still work normally. When enabled, this supersedes quarkus.config.sources.system-only.

Environment variable: QUARKUS_CONFIG_FIXED_AT_BUILD_TIME

Show more

ブーリアン

false

quarkus.profile

A comma separated list of profiles that will be active when Quarkus launches.

Environment variable: QUARKUS_PROFILE

Show more

文字列のリスト

quarkus.config.profile.parent

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: QUARKUS_CONFIG_PROFILE_PARENT

Show more

string

quarkus.config.locations

Additional config locations to be loaded with the Config. The configuration support multiple locations separated by a comma and each must represent a valid java.net.URI.

Environment variable: QUARKUS_CONFIG_LOCATIONS

Show more

list of URI

quarkus.config.mapping.validate-unknown

Validates that a @ConfigMapping maps every available configuration name contained in the mapping prefix.

Environment variable: QUARKUS_CONFIG_MAPPING_VALIDATE_UNKNOWN

Show more

ブーリアン

quarkus.config.log.values

Enable logging of configuration values lookup in DEBUG log level.
The log of configuration values require the category set to DEBUG in the io.smallrye.config category: quarkus.log.category."io.smallrye.config".level=DEBUG.

Environment variable: QUARKUS_CONFIG_LOG_VALUES

Show more

ブーリアン

quarkus.config.build-time-mismatch-at-runtime

What should happen if the application is started with a different build time configuration than it was compiled against. This may be useful to prevent misconfiguration.

If this is set to warn the application will warn at start up.

If this is set to fail the application will fail at start up.

Native tests leveraging`@io.quarkus.test.junit.TestProfile` are always run with quarkus.config.build-time-mismatch-at-runtime = fail.

Environment variable: QUARKUS_CONFIG_BUILD_TIME_MISMATCH_AT_RUNTIME

Show more

warn, fail

warn

関連コンテンツ

同じトピックについて

Quarkus はオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスの下で利用可能です。 CC by 3.0

このウェブサイトは Jekyll で構築され、GitHub Pages でホストされており、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークして、あなたのアイデアを見せてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.