As an application developer, you can use IBM Enterprise Build of Quarkus to create microservices-based applications written in Java that run on OpenShift Container Platform and serverless environments. Applications compiled to native executables have small memory footprints and fast startup times.

Apply structured configuration by updating the application.yaml file to configure your Quarkus application.

Note: Alternatively, you can configure your Quarkus application by setting properties in the application.properties file. For more information, see Setting configuration properties.

The procedures include configuration examples that are created by using the Quarkus config-quickstart exercise.

Note: For a completed example of the application configuration exercise, download the Quarkus Quickstarts archive or clone the Quarkus Quickstarts Git repository and go to the config-quickstart directory.

Prerequisites

  • You have installed OpenJDK 17 or 21 and set the JAVA_HOME environment variable to specify the location of the Java SDK.

    • To download Red Hat build of OpenJDK, log in to the Red Hat Customer Portal and go to Software Downloads.

  • You installed Apache Maven 3.9.9.

  • You have configured Apache Maven to use artifacts from the Quarkus Maven repository.

Configuration options

You can manage your application’s settings in a single configuration file. Additionally, you can define configuration profiles to group related settings for different environments, such as development, testing, or production. This way, you can easily switch between profiles and apply environment-specific properties without altering your main configuration file.

By default, Quarkus reads properties from the application.properties file located in the src/main/resources directory. If, instead, you prefer to configure and manage application properties in an application.yaml file, add the quarkus-config-yaml dependency to your project’s pom.xml file. For more information, see Adding YAML configuration support.

IBM Enterprise Build of Quarkus also supports MicroProfile Config, which you can use to load your application’s configuration from various sources. By using the MicroProfile Config specification from the Eclipse MicroProfile project, you can inject configuration properties into your application and access them by using methods defined in your code.

Quarkus can read application properties from different origins, including:

  • The file system

  • A database

  • A Kubernetes or OpenShift Container Platform ConfigMap or Secret object

  • Any source that a Java application can load

Adding YAML configuration support

IBM Enterprise 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 the YAML configuration file over the properties file for configuration. Quarkus supports the use of application.yml and application.yaml as the name of the YAML file.

The YAML configuration file takes precedence over the application.properties file. To avoid errors, you can delete the application.properties file and use only one type of configuration file.

Procedure

  1. Use one of the following methods to add the YAML extension to your project:

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

      Example pom.xml file
      <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:

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

Using nested object configuration with YAML

You can define nested configuration properties within the existing ones for your IBM Enterprise Build of Quarkus application by using the application.yaml configuration file.

Prerequisites

  • You have a Quarkus Maven project.

  • You have a PostgreSQL data source.

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

    • quarkus-resteasy-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 following example:

    Example application.yaml file
    # Properties that configure the JDBC data source driver of your PostgreSQL data source
quarkus:
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://localhost:5432/quarkus_test
    username: quarkus_test
    password: quarkus_test

# Property that configures the URL of the endpoint to which the REST client sends requests
quarkus:
  rest-client:
    org.acme.rest.client.ExtensionsService:
      url: https://stage.code.quarkus.io/api

# Property that configures the log message level for your application
# For configuration property names that use quotes, do not split the string inside the quotes
quarkus:
  log:
    category:
      "io.quarkus.category":
        level: INFO

     

    Warning: For production, do not set the username and password in the configuration file, as shown in the preceding example. This was for illustration purposes only. Instead, set the username and password in your environmental variables. For more information, see the Setting configuration properties section of the "Configuring your IBM Enterprise Build of Quarkus applications by using a properties file" guide.

    Similar to the application.properties file, you can use comments to describe your configuration properties in YAML format.

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

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 also configure profile-aware files, where the properties for a specific profile are defined in an application-{profile}.yaml named file.

Note: When configuring profile-aware files, consider the following:

  • With a profile-aware file, you do not need to prefix configuration names with the profile name.

  • You cannot use profile-aware files to set the quarkus.profile configuration option because the active profile must be known before you can load these files.

  • An application.yaml file must exist (even if empty) in the same location as the profile-aware file to ensure a consistent order when loading the files.

You can start your application with a specific profile to access a particular configuration. This procedure shows how you can provide a configuration for a specific profile in YAML format.

Prerequisites

  • You have a Quarkus Maven project configured to use a PostgreSQL data source with a JDBC data source driver.

  • You have the quarkus-jdbc-postgresql and quarkus-config-yaml extensions as dependencies in your project’s pom.xml file.

Procedure

  1. Open your project’s configuration file, src/main/resources/application.yaml.

  2. To set a profile-dependent configuration, add the profile name before defining the key-value pairs by using the "%<profile_name>" syntax. Ensure that you place the profile name inside quotation marks.

    Tip: In YAML, you must place all strings that begin with a special character inside quotation marks.

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

    src/main/resources/application.yaml
    "%dev":
  quarkus:
    datasource:
      db-kind: postgresql
        jdbc:
          url: jdbc:postgresql://localhost:5432/quarkus_test
        username: quarkus_test
        password: quarkus_test

     

    Warning: For production, do not set the username and password in the configuration file, as shown in the preceding example. This was for illustration purposes only. Instead, set the username and password in your environmental variables. For more information, see the Setting configuration properties section of the "Configuring your IBM Enterprise Build of Quarkus applications by using a properties file" guide.

Property expressions

You can combine property references and text strings into property expressions and use them as values in your IBM Enterprise Build of Quarkus configuration.

Like variables, property expressions substitute configuration values dynamically, helping you avoid hard-coded values.

You can reference a property defined in one configuration source from another source.

IBM Enterprise Build of Quarkus resolves a property expression when it reads the configuration property:

  • At build time, if the property is read at build time

  • At runtime, if the property is read at runtime

If a property expression cannot be resolved and does not include a default value, IBM Enterprise Build of Quarkus throws a NoSuchElementException.

Example: Property expressions in a YAML file

The following example shows how to use property expressions for flexible configuration of your Quarkus application.

Example application.yaml file
mach: 3
x:
  factor: 2.23694

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

 

Note: To reference nested properties, use the . (dot) separator, as in {x.factor}.
Additional resources

External application.yaml file for configuring properties at runtime

To configure your application properties at runtime, add your application.yaml file to the config directory.

When config/application.yaml and src/main/resources/application.yaml share properties, values from config/application.yaml override those in src/main/resources/application.yaml.

Ensure that the config/application.yaml file is in the root of the working directory relative to the Quarkus application runner, as outlined in the following example:

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

Managing configuration property conflicts

Structured formats such as YAML only support a subset of the possible configuration namespace. The following procedure shows how to resolve 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 that is 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:

    Example of defining a YAML property as a prefix
    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:

    Compile your application
    ./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 the configuration property name.

Additional resources