By Version

YAML Configuration

Enabling YAML Configuration
- Example
Profiles
Expressions
External application.yaml file
Configuration key conflicts

YAML is a very popular format. Kubernetes relies heavily on the YAML format to write the various resource descriptors.

Quarkus offers the possibility to use YAML in addition to the standard Java Properties file.

Enabling YAML Configuration

To enable YAML configuration, add the quarkus-config-yaml extension:

CLI

quarkus extension add 'quarkus-config-yaml'

Maven

./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'

Gradle

./gradlew addExtension --extensions='quarkus-config-yaml'

You can also just add the following dependency into your project:

pom.xml

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

build.gradle

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

Remove the src/main/resources/application.properties and create a src/main/resources/application.yaml file.

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.

Example

The following snippets provide examples of YAML configuration:

# 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

Profiles

As you can see in the previous snippet, you can use profiles in YAML. The profile key requires double quotes: "%test". This is because YAML does not support keys starting with %.

Everything under the "%test" key is only enabled when the test profile is active. For example, in the previous snippet it disables OIDC (quarkus.oidc.enabled: false), whereas without the test profile, it would be enabled.

As for the Java Properties format, you can define your own profile:

quarkus:
  http:
    port: 8081

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

If you enable the staging profile, the HTTP port will be 8082, whereas it would be 8081 otherwise.

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

application.yaml

quarkus:
  http:
    port: 8081

application-staging.yaml

quarkus:
  http:
    port: 8082

Expressions

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

mach: 3
x:
  factor: 2.23694

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

Note that you can reference nested properties using the . (dot) separator as in ${x.factor}.

External application.yaml file

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

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

Configuration key conflicts

The MicroProfile Config specification defines configuration keys as an arbitrary .-delimited string. However, structured formats like 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 may not be immediately evident how to specify both keys in your YAML configuration.

This is solved by using a null key (represented by ~) for any YAML property which 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 in any level for disambiguating configuration keys.