The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

YAML設定

標準の Java プロパティファイル application.properties の代わりに、YAML ファイル application.yaml を使って Quarkus アプリケーションを設定することもできます。

YAML は、特にKubernetesでリソース記述子を定義するために広く使用されています。

YAML設定の有効化

YAML設定を有効にするには、 quarkus-config-yaml エクステンションを追加します。

コマンドラインインタフェース
quarkus extension add quarkus-config-yaml
Maven
./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'
Gradle
./gradlew addExtension --extensions='quarkus-config-yaml'

あるいは、以下の依存関係をプロジェクトに追加してください:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-config-yaml</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-config-yaml")

エクステンションまたは依存関係を追加した後、混乱を避けるために、 src/main/resources/application.properties ファイルを削除し、 src/main/resources/application.yaml ファイルを作成します。

両方のファイルが存在する場合、QuarkusはYAMLファイルのプロパティを優先します。
Quarkusは、 .yml.yaml の両方のファイル拡張子を認識します。

YAML 設定例

次のスニペットは YAML 設定の例です:

# YAML supports comments
quarkus:
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://localhost:5432/some-database

# REST Client configuration property
quarkus:
  rest-client:
    org.acme.rest.client.ExtensionsService:
      url: https://stage.code.quarkus.io/api
# For configuration property names that use quotes, do not split the string inside the quotes
quarkus:
  log:
    category:
      "io.quarkus.category":
        level: INFO
quarkus:
  datasource:
    url: jdbc:postgresql://localhost:5432/quarkus_test

  hibernate-orm:
    database:
      generation: drop-and-create

  oidc:
    enabled: true
    auth-server-url: http://localhost:8180/auth/realms/quarkus
    client-id: app


app:
  frontend:
    oidc-realm: quarkus
    oidc-app: app
    oidc-server: http://localhost:8180/auth

# With profiles
"%test":
   quarkus:
     oidc:
       enabled: false
     security:
        users:
            file:
              enabled: true
              realm-name: quarkus
              plain-text: true

プロファイル

前のスニペットでわかるように、YAMLで プロファイル を使うことができます。

YAML において、 % で始まるキーは許されません。 しかし、プロファイルキーはこのシンボルで始めなければなりません。 "%test" これを解決するには、プロファイルキーを二重引用符で囲みます。

"%test" キーの下にあるすべての設定は、 test プロファイルが有効になっているときにのみ有効になります。 例えば、前述のスニペットでは、 test プロファイルが有効な場合、OpenID Connect (OIDC) ( quarkus.oidc.enabled: false ) は無効になっています。 test プロファイルがない場合、OIDC はデフォルトで有効になります。

以下の例の %staging のように、カスタムプロファイルを定義することもできます:

quarkus:
  http:
    port: 8081

"%staging":
    quarkus:
        http:
          port: 8082

staging プロファイルを有効にすると、HTTP ポートは 8081 ではなく 8082 に設定されます。

YAML 設定はプロファイル対応ファイルもサポートします。 この場合、特定のプロファイルのプロパティは application-{profile}.yaml という名前のファイルに保存できます。 先程の例は次のように表現できます:

quarkus:
  http:
    port: 8081
application-staging.yaml
quarkus:
  http:
    port: 8082

YAML フォーマットは Java プロパティと同じフォーマットを使うことで プロパティ式 もサポートします:

mach: 3
x:
  factor: 2.23694

display:
  mach: ${mach}
  unit:
    name: "mph"
    factor: ${x.factor}

${x.factor} の よ う に、 . (ド ッ ト ) セパレーターを用い る こ と で、 入れ子にな っ たプ ロ パテ ィ を参照す る こ と がで き ます。

外部application.yamlファイル

application.yaml ファイルは、実行時設定を特殊化するために config/application.yaml に置くこともできます。 このファイルはQuarkusアプリケーション・ランナーに相対する作業ディレクトリのルートに存在しなければなりません:

.
├── config
│    └── application.yaml
├── my-app-runner

このファイルの値は、通常の application.yaml ファイルが存在する場合、そのファイルの値を上書きします。

設定プロパティの競合

MicroProfile Config 仕様では、設定プロパティを . で区切られた任意の文字列として定義します。 しかし、YAML のような構造化フォーマットはありうる設定名前空間のサブセットしかサポートしません。 例えば、2 つの設定プロパティ quarkus.http.corsquarkus.http.cors.methods を考えてみましょう。 一方のプロパティはもう一方のプロパティのプレフィックスなので、YAML 設定で両方のキーを指定する方法はすぐにはわからないかもしれません。

これは ~null キーとして使い、他のプロパティのプレフィックスである YAML プロパティを表すことで解決されます:

quarkus:
  http:
    cors:
      ~: true
      methods: GET,PUT,POST

YAML null キーは設定プロパティ名のアセンブリに含まれないので、設定プロパティを曖昧さをなくすためにどのレベルでも使うことができます。

Quarkusでは、主に設定に .properties ファイル拡張子を使用しますが、QuarkusでYAMLのパースに使用されるsnakeyamlライブラリは、JSON構造もパースできます。つまり、JSONコンテンツを含むYAMLファイルを使用できます。

YAMLとJSON構造はapplication.yamlファイルから読み込むことができます。

Quarkusで複雑な設定構造を使用する方法について、ステップバイステップで説明します:

  • 設定インターフェースを定義します。

@ConfigMapping(prefix = "server")
public interface ServiceConfig {

  List<Environment> environments();

  interface Environment {
    String name();
    String services();
  }
}
  • 適切なJSON構造を作成し、YAMLファイルに格納します。

{
  "server": {
    "environments": [
      {
        "name": "dev",
        "services": "bookstore"
      },
      {
        "name": "batch",
        "services": "warehouse"
      }
    ]
  }
}

関連コンテンツ