YAML ファイルを使用した Red Hat build of Quarkus アプリケーションの設定
概要
Red Hat build of Quarkus ドキュメントへのフィードバックの提供 リンクのコピーリンクがクリップボードにコピーされました!
エラーを報告したり、ドキュメントを改善したりするには、Red Hat Jira アカウントにログインし、課題を送信してください。Red Hat Jira アカウントをお持ちでない場合は、アカウントを作成するように求められます。
手順
- 次のリンクをクリックして チケットを作成します。
- Summary に課題の簡単な説明を入力します。
- Description に課題や機能拡張の詳細な説明を入力します。問題があるドキュメントのセクションへの URL も記載してください。
- Submit をクリックすると、課題が作成され、適切なドキュメントチームに転送されます。
第1章 YAML ファイルを使用した Red Hat build of Quarkus アプリケーションの設定 リンクのコピーリンクがクリップボードにコピーされました!
アプリケーション開発者は、Red Hat build of Quarkus を使用して、OpenShift Container Platform 環境およびサーバーレス環境で実行される、Java で書かれたマイクロサービスベースのアプリケーションを作成できます。ネイティブ実行可能ファイルにコンパイルされたアプリケーションは、メモリーのフットプリントが小さく、起動時間は高速です。
application.yaml ファイルを更新して構造化された設定を適用して、Quarkus アプリケーションを設定します。
あるいは、application.properties ファイルでプロパティーを設定して、Quarkus アプリケーションを設定することもできます。詳細は、設定プロパティーの設定 を参照してください。
この手順には、Quarkus config-quickstart 演習を使用して作成された設定例が含まれています。
アプリケーション設定演習の完成例を参照するには、Quarkus Quickstarts アーカイブをダウンロードするか、Quarkus Quickstarts Git リポジトリーのクローンを作成して config-quickstart ディレクトリーに移動してください。
1.1. 前提条件 リンクのコピーリンクがクリップボードにコピーされました!
OpenJDK 17 または 21 をインストールし、
JAVA_HOME環境変数を設定して Java SDK の場所を指定している。- Red Hat build of OpenJDK をダウンロードするには、Red Hat カスタマーポータルにログインし、ソフトウェアダウンロード に移動します。
Apache Maven 3.9.9 をインストールした。
- Maven は Apache Maven Project の Web サイトからダウンロードできます。
Apache Maven を、Quarkus Maven repository のアーティファクトを使用するように設定している。
- Apache Maven の設定方法は、Quarkus スタートガイド を参照してください。
1.2. 設定オプション リンクのコピーリンクがクリップボードにコピーされました!
アプリケーションの設定を 1 つの設定ファイルで管理できます。さらに、設定プロファイルを定義して、開発、テスト、運用などのさまざまな環境の関連設定をグループ化することもできます。この方法では、メインの設定ファイルを変更せずに、プロファイルを簡単に切り替えて、環境固有のプロパティーを適用できます。
デフォルトでは、Quarkus は src/main/resources ディレクトリーにある application.properties ファイルからプロパティーを読み取ります。代わりに、application.yaml ファイルでアプリケーションプロパティーを設定および管理する場合は、プロジェクトの pom.xml ファイルに quarkus-config-yaml 依存関係を追加します。詳細は、YAML 設定サポートの追加 を参照してください。
Red Hat build of Quarkus は MicroProfile Config もサポートしており、これを使用してさまざまなソースからアプリケーションの設定を読み込むことができます。Eclipse MicroProfile プロジェクトの MicroProfile Config 仕様 を使用すると、設定プロパティーをアプリケーションに挿入し、コードで定義されたメソッドを使用してそれらにアクセスできます。
Quarkus は、次のようなさまざまなオリジンからのアプリケーションプロパティーを読み取ることができます。
- ファイルシステム
- データベース
-
Kubernetes または OpenShift Container Platform の
ConfigMapまたはSecretオブジェクト - Java アプリケーションがロードできるソース
1.3. YAML 設定サポートの追加 リンクのコピーリンクがクリップボードにコピーされました!
Red Hat build of 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>コマンドラインから
quarkus-config-yamlエクステンションを追加するには、プロジェクトディレクトリーから以下のコマンドを入力します。quarkus-config-yamlエクステンションの追加./mvnw quarkus:add-extension -Dextensions="quarkus-config-yaml"
1.3.1. YAML を使用したネストされたオブジェクト設定の使用 リンクのコピーリンクがクリップボードにコピーされました!
application.yaml 設定ファイルを使用して、Red Hat build of Quarkus アプリケーションの既存の設定プロパティー内でネストされた設定プロパティーを定義できます。
前提条件
- Quarkus Maven プロジェクトがある。
- PostgreSQL データソースがある。
プロジェクトの
pom.xmlファイルの依存関係として、以下のエクステンションがある。-
quarkus-resteasy-client -
quarkus-jdbc-postgresql -
quarkus-config-yaml
-
手順
-
src/main/resources/application.yaml設定ファイルを開きます。 以下の例のように、ネストされたクラス設定プロパティーを
application.yamlファイルに追加します。application.yamlファイルの例# Properties that configure the JDBC data source driver of your PostgreSQL data source quarkus: datasource: db-kind: postgresql jdbc: url: jdbc:postgresql://localhost:5432/quarkus_test username: quarkus_test password: quarkus_test # Property that configures the URL of the endpoint to which the REST client sends requests quarkus: rest-client: org.acme.rest.client.ExtensionsService: url: https://stage.code.quarkus.io/api # Property that configures the log message level for your application # For configuration property names that use quotes, do not split the string inside the quotes quarkus: log: category: "io.quarkus.category": level: INFO警告実稼働環境の場合は、前述の例のように、設定ファイルにユーザー名とパスワードを設定しないでください。これは、説明のみを目的としています。代わりに、環境変数で設定します。詳細は、「プロパティーファイルを使用した Red Hat build of Quarkus アプリケーションの設定」ガイドの 設定プロパティーの設定 セクションを参照してください。
application.propertiesファイルと同様に、コメントを使用して設定プロパティーを YAML 形式で記述できます。注記YAML 設定ファイル内のプロパティーをインデントするには、常にスペースを使用してください。YAML は、インデントへのタブの使用をサポートしていません。
1.3.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/quarkus_testURL で使用できるように設定されています。src/main/resources/application.yaml
"%dev": quarkus: datasource: db-kind: postgresql jdbc: url: jdbc:postgresql://localhost:5432/quarkus_test username: quarkus_test password: quarkus_test警告実稼働環境の場合は、前述の例のように、設定ファイルにユーザー名とパスワードを設定しないでください。これは、説明のみを目的としています。代わりに、環境変数で設定します。詳細は、「プロパティーファイルを使用した Red Hat build of Quarkus アプリケーションの設定」ガイドの 設定プロパティーの設定 セクションを参照してください。
1.4. プロパティー式 リンクのコピーリンクがクリップボードにコピーされました!
プロパティー参照とテキスト文字列を組み合わせてプロパティー式を作成し、プロパティー式を Red Hat build of Quarkus 設定の値として使用できます。
プロパティー式は、変数と同様に、設定値を動的に置き換えます。そのため、値のハードコードを回避するのに役立ちます。
ある設定ソースで定義されたプロパティーを別のソースから参照できます。
Red Hat build of Quarkus は、設定プロパティーを読み取るとき、つまり以下のタイミングでプロパティー式を解決します。
- ビルド時 (ビルド時にプロパティーが読み取られる場合)
- 実行時 (実行時にプロパティーが読み取られる場合)
プロパティー式を解決できず、式にデフォルト値が含まれていない場合、Red Hat build of Quarkus は NoSuchElementException を出力します。
1.4.1. 例: YAML ファイル内のプロパティー式 リンクのコピーリンクがクリップボードにコピーされました!
次の例は、Quarkus アプリケーションを柔軟に設定するためにプロパティー式を使用する方法を示しています。
application.yaml ファイルの例
mach: 3
x:
factor: 2.23694
display:
mach: ${mach}
unit:
name: "mph"
factor: ${x.factor}
ネストされたプロパティーを参照するには、{x.factor} のように、. (ドット) 区切り文字を使用します。
1.5. 実行時にプロパティーを設定するための外部 application.yaml ファイル リンクのコピーリンクがクリップボードにコピーされました!
実行時にアプリケーションのプロパティーを設定するには、application.yaml ファイルを config ディレクトリーに追加します。
config/application.yaml と src/main/resources/application.yaml がプロパティーを共有する場合は、config/application.yaml の値が src/main/resources/application.yaml の値をオーバーライドします。
次の例に示すように、config/application.yaml ファイルが、Quarkus アプリケーションランナーを基準とした作業ディレクトリーのルートにあることを確認します。
├── config
│ └── application.yaml
├── my-app-runner
1.6. 設定プロパティーの競合の管理 リンクのコピーリンクがクリップボードにコピーされました!
YAML などの構造化フォーマットは、設定可能な名前空間の一部しかサポートしていません。次の手順は、一方のプロパティーがもう一方のプロパティーの接頭辞となっている 2 つの設定プロパティー quarkus.http.cors と quarkus.http.cors.methods 間の競合を解決する方法を示しています。
前提条件
- YAML 設定ファイルを読み取るように Quarkus プロジェクトが設定されている。
手順
- YAML 設定ファイルを開きます。
YAML プロパティーを別のプロパティーの接頭辞として定義するには、以下の例に示すようにプロパティーの範囲にティルデ (
~) を追加します。YAML プロパティーを接頭辞として定義する例
quarkus: http: cors: ~: true methods: GET,PUT,POST開発モードで Quarkus アプリケーションをコンパイルするには、プロジェクトディレクトリーから以下のコマンドを入力します。
アプリケーションをコンパイルします。
./mvnw quarkus:dev注記YAML キーは設定プロパティー名のアセンブリーに含まれないため、任意のレベルの競合する設定キーに使用できます。