バージョン:

YAML Configuration

YAMLはとても人気のあるフォーマットです。Kubernetesは、さまざまなリソース記述子を記述するためにYAMLフォーマットに大きく依存しています。

Quarkusでは、標準のJavaプロパティファイルに加えてYAMLを使用することができます。

YAML設定の有効化

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

CLI

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 のファイルを作成します。

If both are present, Quarkus prioritizes configuration properties from the YAML file first and then from the Properties file. However, to avoid confusion, we recommend removing the Properties file.

Quarkus supports both the yml and yaml file extensions.

例

次のスニペットは、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でプロファイルを使うことができます。プロファイルのキーには二重引用符が必要です: "%test".これはYAMLが % で始まるキーをサポートしていないためです。

"%test" キーの下にあるすべてのものは、 test プロファイルがアクティブな場合にのみ有効です。例えば、前述のスニペットでは、OIDC ( quarkus.oidc.enabled: false) を無効にしていますが、 test プロファイルがなければ、有効になります。

Javaプロパティ形式については、独自のプロファイルを定義することができます。

quarkus:
  http:
    port: 8081

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

staging プロファイルを有効にした場合、HTTP ポートは 8082 になりますが、そうでない場合は 8081 になります。

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

application.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.cors と quarkus.http.cors.methods を考えてみましょう。1つのプロパティは別のプロパティのプレフィックスであるため、YAML設定で両方のキーを指定する方法はすぐにはわからないかもしれません。

これは、別のプロパティのプレフィックスであるYAMLプロパティに null キー（ ~ で表される）を使用することで解決します。

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

YAML null キーは、設定プロパティ名の組み合わせには含まれないため、設定キーの曖昧さを解消するために任意のレベルで使用することができます。