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

YAML設定

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

両方が存在する場合、QuarkusはまずYAMLファイルからの設定プロパティを優先し、次にPropertiesファイルからの設定プロパティを読み込みます。ただし、混乱を避けるため、Propertiesファイルを削除することをお勧めします。
Quarkusは、 ymlyaml の両方のファイル拡張子をサポートしています。

次のスニペットは、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ファイル

The application.yaml file may also be placed in config/application.yaml to specialize the runtime configuration. The file has to be present in the root of the working directory relative to the Quarkus application runner:

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

このファイルの値は、通常の application.yaml ファイルが存在する場合、そちらの値よりも優先されます。

設定キーの競合

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

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

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

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