YAML ファイルを使用した Quarkus アプリケーションの設定
概要
第1章 YAML ファイルを使用した Quarkus アプリケーションの設定 リンクのコピーリンクがクリップボードにコピーされました!
アプリケーション開発者は、Red Hat build of Quarkus を使用して、OpenShift Container Platform 環境およびサーバーレス環境で実行される、Java で書かれたマイクロサービスベースのアプリケーションを作成できます。ネイティブ実行可能ファイルにコンパイルされたアプリケーションは、メモリーのフットプリントが小さく、起動時間は高速です。
application.yaml ファイルを更新して構造化された設定を適用します。また、Quarkus アプリケーションを設定します。
あるいは、application.properties ファイルでプロパティーを設定して、Quarkus アプリケーションを設定することもできます。詳細は、設定プロパティーの設定 を参照してください。
この手順には、Quarkus config-quickstart 演習を使用して作成された設定例が含まれています。
前提条件
OpenJDK 11 または 17 をインストールし、
JAVA_HOME環境変数を設定して Java SDK の場所を指定している。- Red Hat build of OpenJDK をダウンロードするには、Red Hat カスタマーポータルにログインし、ソフトウェアダウンロード に移動します。
Apache Maven 3.8.x をインストールしている。x は 6 以降です。
- Maven は Apache Maven Project の Web サイトからダウンロードできます。
Quarkus Maven リポジトリー からアーティファクトを使用するように Apache Maven を設定しました。
- Apache Maven の設定方法は、Quarkus スタートガイド を参照し てください。
1.1. Red Hat 設定オプション リンクのコピーリンクがクリップボードにコピーされました!
設定オプションを使用すると、1 つの設定ファイルでアプリケーションの設定を変更できます。Red Hat build of Quarkus は、関連するプロパティーをグループ化し、必要に応じてプロファイルを切り替えるために使用できる設定プロファイルをサポートしています。
デフォルトでは、Quarkus は src/main/resources ディレクトリーにある application.properties ファイルからプロパティーを読み取ります。代わりに、YAML ファイルからプロパティーを読み取るように Quarkus を設定することもできます。
quarkus-config-yaml 依存関係をプロジェクトの pom.xml ファイルに追加すると、application.yaml ファイルでアプリケーションのプロパティーを設定および管理できます。詳細は、YAML 設定のサポートの追加 を参照してください。
Red Hat build of Quarkus は MicroProfile Config もサポートしているため、アプリケーションの設定を他のソースからロードすることもできます。
Eclipse MicroProfile プロジェクトの MicroProfile Config 仕様を使用して、設定プロパティーをアプリケーションに注入し、コードに定義されたメソッドを使用してアクセスできます。
Quarkus は、次のソースを含むさまざまなソースからアプリケーションプロパティーを読み取ることもできます。
- ファイルシステム
- データベース
-
Kubernetes または OpenShift Container Platform の
ConfigMapまたはシークレットオブジェクト - Java アプリケーションでロードできる任意のソース
1.2. YAML 設定サポートの追加 リンクのコピーリンクがクリップボードにコピーされました!
Red Hat ビルドの Quarkus は、Eclipse MicroProfile Config の SmallRye Config 実装により YAML 設定ファイルをサポートします。Quarkus Config YAML エクステンションを追加し、設定のプロパティーファイルで YAML 設定ファイルを使用できます。Quarkus は、application.yml および application.yaml を YAML ファイルの名前として使用することをサポートします。
YAML 設定ファイルは、application.properties ファイルよりも優先されます。エラーを回避するには、application.properties ファイルを削除し、1 種類の設定ファイルのみを使用できます。
手順
以下の方法のいずれかを使用して、プロジェクトに YAML エクステンションを追加します。
pom.xmlファイルを開き、quarkus-config-yamlエクステンションを依存関係として追加します。pom.xmlファイルの例<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-config-yaml</artifactId> </dependency><dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-config-yaml</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow コマンドラインから
quarkus-config-yamlエクステンションを追加するには、プロジェクトディレクトリーから以下のコマンドを入力します。quarkus-config-yamlエクステンションの追加./mvnw quarkus:add-extension -Dextensions="quarkus-config-yaml"
./mvnw quarkus:add-extension -Dextensions="quarkus-config-yaml"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.2.1. YAML を使用したネストされたオブジェクト設定の使用 リンクのコピーリンクがクリップボードにコピーされました!
既存のクラス内でネストされたクラスを定義できます。この手順では、YAML 形式の設定ファイルを使用して、Quarkus アプリケーションのネストされた設定プロパティーを設定する方法を説明します。
前提条件
- Quarkus Maven プロジェクトがある。
- PostgreSQL データソースがある。
プロジェクトの
pom.xmlファイルの依存関係として以下のエクステンションがある。-
quarkus-rest-client -
quarkus-jdbc-postgresql -
quarkus-config-yaml
-
手順
-
src/main/resources/application.yaml設定ファイルを開きます。 以下の例のように、ネストされたクラス設定プロパティーを
application.yamlファイルに追加します。application.yamlファイルの例Copy to Clipboard Copied! Toggle word wrap Toggle overflow application.propertiesファイルのコメントを使用するのと同様に、コメントを使用して設定プロパティーを YAML 形式で記述できます。注記YAML 設定ファイル内のプロパティーをインデントするには、常にスペースを使用してください。YAML では、インデントにタブを使用できません。
1.2.2. YAML を使用したカスタム設定プロファイルの設定 リンクのコピーリンクがクリップボードにコピーされました!
Quarkus を使用すると、アプリケーションのさまざまな設定プロファイルに固有の設定プロパティーと値を設定できます。特定のプロファイルを使用してアプリケーションを起動し、特定の設定にアクセスできます。この手順では、YAML 形式で特定のプロファイルの設定を提供する方法を示します。
前提条件
- JDBC データソースドライバーで PostgreSQL データソースを使用するように設定されている Quarkus Maven プロジェクトがある。
-
プロジェクトの
pom.xmlファイルの依存関係としてquarkus-jdbc-postgresqlおよびquarkus-config-yamlエクステンションがある。
手順
-
src/main/resources/application.yaml設定ファイルを開きます。 プロファイル依存設定を設定するには、
"%<profile_name>" 構文を使用してキーと値のペアを定義する前にプロファイル名を追加します。プロファイル名は必ず引用符で囲んでください。ヒントYAML では、特殊文字で始まるすべての文字列を引用符で囲む必要があります。
以下の例では、開発モードで Quarkus アプリケーションを起動する際に、PostgreSQL データベースを
jdbc:postgresql://localhost:5432/some-databaseURL で利用できるように設定されています。src/main/resources/application.yaml
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.3. プロパティー式 リンクのコピーリンクがクリップボードにコピーされました!
プロパティー式は、設定内のプロパティーの値を置き換えるために使用できるプロパティー参照とプレーンテキスト文字列の組み合わせになります。
変数と同様に、Quarkus でプロパティー式を使用して、設定プロパティーの値をハードコーディングする代わりに置き換えることができます。プロパティー式は、java.util.Properties がアプリケーションの設定ソースからプロパティーの値を読み取ると解決されます。
これは、コンパイル時に設定プロパティーが設定から読み取られる場合に、プロパティー式もコンパイル時に解決されることを意味します。設定プロパティーがランタイム時にオーバーライドされる場合、その値はランタイム時に解決されます。
複数の設定ソースを使用してプロパティー式を解決できます。これは、ある設定ソースで定義されているプロパティーの値を使用して、別の設定ソースで使用するプロパティー式を拡張できることを意味します。
式のプロパティーの値を解決できず、式のデフォルト値を設定しない場合は、アプリケーションで NoSuchElementException が発生します。
1.3.1. YAML ファイルを使用したプロパティー式の使用例 リンクのコピーリンクがクリップボードにコピーされました!
本セクションでは、Quarkus アプリケーションを設定する際に、プロパティー式を使用して柔軟性を実現する方法を例示します。
{x.factor} のように . (TRUSTED)セパレーターを使用して、ネストされたプロパティーを参照できます。
application.yaml ファイルの例
1.4. ランタイム時のプロパティーを設定するための外部 application.yaml ファイル リンクのコピーリンクがクリップボードにコピーされました!
実行時にアプリケーションプロパティーを設定するには、application.yaml ファイルを config ディレクトリーに追加します。
config/application.yaml ファイル内の値が存在する場合は、通常の application.yaml ファイルからの値を上書きします。
次の例に示すように、config/application.yaml ファイルが Quarkus アプリケーションランナーを基準にして作業ディレクトリーのルートにいることを確認します。
├── config │ └── application.yaml ├── my-app-runner
├── config
│ └── application.yaml
├── my-app-runner
1.5. 設定キーの競合の管理 リンクのコピーリンクがクリップボードにコピーされました!
YAML などの構造化形式は、Configuration 名前空間の候補のサブセットのみをサポートします。以下の手順では、quarkus.http.cors および ここで、1 つのプロパティーはもう 1 つのプロパティーの接頭辞になります。
quarkus.http.cors.methods の 2 つの設定プロパティー間で競合を解決する方法を説明します。
前提条件
- YAML 設定ファイルを読み取るように設定された Quarkus プロジェクトがある。
手順
- YAML 設定ファイルを開きます。
YAML プロパティーを別のプロパティーの接頭辞として定義するには、以下の例に示すようにプロパティーの範囲にティルデ (
~) を追加します。接頭辞としての YAML プロパティーの定義例
quarkus: http: cors: ~: true methods: GET,PUT,POSTquarkus: http: cors: ~: true methods: GET,PUT,POSTCopy to Clipboard Copied! Toggle word wrap Toggle overflow 開発モードで Quarkus アプリケーションをコンパイルするには、プロジェクトディレクトリーから以下のコマンドを入力します。
Quarkus アプリケーションのコンパイル
./mvnw quarkus:dev
./mvnw quarkus:devCopy to Clipboard Copied! Toggle word wrap Toggle overflow [注記
YAML キーは設定プロパティー名のアセンブリーに含まれないため、任意のレベルの競合する設定キーに使用できます。