guides/config-yaml.adoc
標準の Java プロパティファイル application.properties の代わりに、YAML ファイル application.yaml を使って Quarkus アプリケーションを設定することもできます。
YAML は、特にKubernetesでリソース記述子を定義するために広く使用されています。
YAML設定の有効化
YAML設定を有効にするには、 quarkus-config-yaml エクステンションを追加します。
quarkus extension add quarkus-config-yaml./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'./gradlew addExtension --extensions='quarkus-config-yaml'あるいは、以下の依存関係をプロジェクトに追加してください：
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-config-yaml</artifactId>
</dependency>implementation("io.quarkus:quarkus-config-yaml")エクステンションまたは依存関係を追加した後、混乱を避けるために、 src/main/resources/application.properties ファイルを削除し、 src/main/resources/application.yaml ファイルを作成します。
| If both files are present, Quarkus gives precedence to properties in the YAML file. |
Quarkus recognizes both .yaml and .yml file extensions. If both files are available, Quarkus
gives precedence to the .yaml file and then the .yml file.
|
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: INFOquarkus:
datasource:
jdbc:
url: jdbc:postgresql://localhost:5432/quarkus_test
hibernate-orm:
schema-management:
strategy: 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 ファイル内で JSON を使用して設定を記述することもできます。ファイルごとに単一の形式を使用してください。ファイル拡張子は |
プロファイル
前のスニペットでわかるように、YAMLで プロファイル を使うことができます。
YAML において、 % で始まるキーは許されません。
しかし、プロファイルキーはこのシンボルで始めなければなりません。
"%test" これを解決するには、プロファイルキーを二重引用符で囲みます。
"%test" キーの下にあるすべての設定は、 test プロファイルが有効になっているときにのみ有効になります。
例えば、前述のスニペットでは、 test プロファイルが有効な場合、OpenID Connect (OIDC) ( quarkus.oidc.enabled: false ) は無効になっています。
test プロファイルがない場合、OIDC はデフォルトで有効になります。
以下の例の %staging のように、カスタムプロファイルを定義することもできます：
quarkus:
http:
port: 8081
"%staging":
quarkus:
http:
port: 8082staging プロファイルを有効にすると、HTTP ポートは 8081 ではなく 8082 に設定されます。
YAML 設定はプロファイル対応ファイルもサポートします。
この場合、特定のプロファイルのプロパティは application-{profile}.yaml という名前のファイルに保存できます。
先程の例は次のように表現できます：
quarkus:
http:
port: 8081quarkus:
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 つの 設定プロパティー one.two と one.two.three を考えてみましょう。一方のプロパティーはもう一方のプレフィックスであるため、YAML 設定で両方のキーを指定する方法はすぐに明らかではないかもしれません。
これは ~ を null キーとして使い、他のプロパティのプレフィックスである YAML プロパティを表すことで解決されます：
one:
two:
~: 12
three: 123YAML null キーは設定プロパティ名のアセンブリに含まれないので、設定プロパティを曖昧さをなくすためにどのレベルでも使うことができます。
