选择指南版本

YAML configuration

Enable YAML configuration
- Example YAML configurations
环境配置(Profiles)
表达式
外部application.yaml 文件
配置键冲突

You can use a YAML file,application.yaml, to configure your Quarkus application instead of the standard Java properties file, application.properties.

YAML is widely used for defining resource descriptors, especially in Kubernetes.

Enable YAML configuration

要启用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'

Alternatively, add the following dependency to your project:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-config-yaml</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-config-yaml")

After adding the extension or dependency, to avoid confusion, remove the src/main/resources/application.properties file and create a src/main/resources/application.yaml file.

If both files are present, Quarkus gives precedence to properties in the YAML file.

Quarkus recognizes both .yml and .yaml file extensions.

Example YAML configurations

The following snippets give examples of YAML configurations:

# YAML支持注释
quarkus:
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://localhost:5432/some-database

# REST Client 配置属性
quarkus:
  rest-client:
    org.acme.rest.client.ExtensionsService:
      url: https://stage.code.quarkus.io/api

# 对于使用引号的配置属性名称，不需要拆分引号内的字符串
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

# 使用环境
"%test":
   quarkus:
     oidc:
       enabled: false
     security:
        users:
            file:
              enabled: true
              realm-name: quarkus
              plain-text: true

环境配置(Profiles)

As you can see in the previous snippet, you can use profiles in YAML.

In YAML, keys that begin with % are not allowed. However, profile keys must start with this symbol. To resolve this, enclose the profile keys in double quotes, as demonstrated by the example, "%test".

All configurations under the "%test" key activate only when the test profile is enabled. For instance, the previous snippet shows that OpenID Connect (OIDC) (quarkus.oidc.enabled: false) is disabled when the test profile is active. Without the test profile, OIDC is enabled by default.

You can also define custom profiles, such as %staging in the following example:

quarkus:
  http:
    port: 8081

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

If you enable the staging profile, the HTTP port is set to 8082 instead of 8081.

The YAML configuration also supports profile-aware files. In this case, properties for a specific profile can reside in an application-{profile}.yaml named file. The previous example can be expressed as:

quarkus:
  http:
    port: 8081

application-staging.yaml

quarkus:
  http:
    port: 8082

表达式

The YAML format also supports property expressions, by using the same format as Java properties:

mach: 3
x:
  factor: 2.23694

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

You can reference nested properties by using the . (dot) separator, as in ${x.factor}.

外部application.yaml 文件

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

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

The values from this file override any values from the regular application.yaml file if it exists.

配置键冲突

The MicroProfile Config specification defines configuration keys as an arbitrary .-delimited string. However, structured formats such as YAML only support a subset of the possible configuration namespace. For example, consider the two configuration properties quarkus.http.cors and quarkus.http.cors.methods. One property is the prefix of another, so it might not be immediately evident how to specify both keys in your YAML configuration.

This is solved by using ~ as a null key to represent any YAML property that is a prefix of another one:

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

YAML null keys are not included in the assembly of the configuration property name, allowing them to be used at any level for disambiguating configuration keys.