Chapter 11. Adding YAML configuration support

Red Hat build of Quarkus supports YAML configuration files through the SmallRye Config implementation of Eclipse MicroProfile Config. You can add the Quarkus Config YAML extension and use YAML over properties for configuration. Quarkus supports using application.yml as well as application.yaml as the name of the YAML file.

The YAML configuration file takes precedence over the application.properties file. The recommended approach is to delete the application.properties file and use only one type of configuration file to avoid errors.

Procedure

  • Use one of the following methods to add the YAML extension in your project:

    • Open the pom.xml file and add the quarkus-config-yaml extension as a dependency: 

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

    • To add the quarkus-config-yaml extension from the command line, enter the following command from your project directory: 

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

11.1. Using nested object configuration with YAML

You can define a nested class inside an already existing class. This procedure shows how you can set nested configuration properties for your Quarkus application using a configuration file in YAML format.

Prerequisites

  • Have a Quarkus Maven project.
  • Have a PostgreSQL data source.

  • Have the following extensions as dependencies in the pom.xml file of your project:

    • quarkus-rest-client,
    • quarkus-jdbc-postgresql
    • quarkus-config-yaml

Procedure

  1. Open the src/main/resources/application.yaml configuration file.

  2. Add the nested class configuration properties to your application.yaml file as shown in the example:

    src/main/resources/application.yaml

    # Properties that configure the JDBC data source driver of your PostgreSQL data source
quarkus:
  datasource:
    url: jdbc:postgresql://localhost:5432/some-database
    driver: org.postgresql.Driver
    username: quarkus
    password: quarkus

# Property that configures the URL of the endpoint to which the rest client sends requests
org:
  acme:
    restclient:
      CountriesService/mp-rest/url: https://restcountries.eu/rest

# Property that configures the log message level for your application
quarkus:
  log:
    category:
      # Do not use spaces in names of configuration properties that you place inside quotation marks
      "io.quarkus.category":
        level: INFO

    Note, that you can use comments to describe your configuration properties in a similar way as you use them in application.properties.

    Note

    Always use spaces to indent the properties in your YAML configuration file. YAML does not allow using tabs for indentation.

11.2. Setting custom configuration profiles with YAML

With Quarkus you can set configuration properties and values that are specific to different configuration profiles of your application. You can start your application with a specific profile to access a particular configuration. This procedure demonstrates how you can provide a configuration for a specific profile in YAML format.

Prerequisites

  • Have a Quarkus Maven project that is configured to use a PostgreSQL data source with a JDBC data source driver.
  • Have the quarkus-jdbc-postgresql and quarkus-config-yaml extensions as dependencies in the pom.xml file of your project.

Procedure

  1. Open the src/main/resources/application.yaml configuration file.

  2. To set a profile dependent configuration, add the profile name before defining the key-value pairs using the "%<profile_name>" syntax. Ensure that you place the profile name inside quotation marks. In YAML, all strings that begin with a special character must be placed inside quotation marks.

    In the following example the PostgreSQL database is configured to be available at the jdbc:postgresql://localhost:5432/some-database URL when you start your Quarkus application in development mode:

    src/main/resources/application.yaml

    "%dev":
  # Properties that configure the JDBC data source driver of your PostgreSQL data source
  quarkus:
    datasource:
      url: jdbc:postgresql://localhost:5432/some-database
      driver: org.postgresql.Driver
      username: quarkus
      password: quarkus

11.3. Managing configuration key conflicts

Structured formats such as YAML only support a subset of the possible configuration namespace. The following procedure shows a solution of a conflict between two configuration properties, quarkus.http.cors and quarkus.http.cors.methods, where one property is the prefix of another.

Prerequisites

  • You have a Quarkus project configured to read YAML configuration files.

Procedure

  1. Open your YAML configuration file.

  2. To define a YAML property as a prefix of another property, add a tilde (~) in the scope of the property as shown in the following example: 

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

  3. To compile your Quarkus application in development mode, enter the following command from the project directory: 

    ./mvnw quarkus:dev
    Note

    You can use YAML keys for conflicting configuration keys at any level because they are not included in the assembly of configuration property name.