Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Configuring your Quarkus applications by using a YAML file

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

This guide describes how to configure your Quarkus application by applying structured configuration by updating the application.yaml file.

You can also 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.

Prerequisites

  • Have OpenJDK 11 or 17 installed and the JAVA_HOME environment variable set to specify the location of the Java SDK.

    • In Quarkus 2.7, building native executables by using Java 17 is provided as a Technology Preview feature. To build native executables for production deployments, use Java 11.
    • Log in to the Red Hat Customer Portal to download the Red Hat build of OpenJDK from the Software Downloads page.

  • Have Apache Maven 3.8.4 or higher installed.

  • Have Maven configured to use artifacts from the Quarkus Maven repository.

Configuration options enable you to change the settings of your application in a single configuration file. Red Hat build of Quarkus supports configuration profiles that you can use to group related properties and switch between profiles as required.

By default, Quarkus reads properties from the application.properties file located in the src/main/resources directory. You can also configure Quarkus to read properties from a YAML file instead.

When you add the quarkus-config-yaml dependency to your project pom.xml file, you can configure and manage your application properties in the application.yaml file. For more information, see Adding YAML configuration support.

Red Hat build of Quarkus also supports MicroProfile Config, which enables you to load the configuration of your application from other sources.

You can use the MicroProfile Config specification from the Eclipse MicroProfile project to inject configuration properties into your application and access them using a method defined in your code.

Quarkus can also read application properties from different origins, including the following sources:

  • The file system
  • A database
  • A Kubernetes or OpenShift ConfigMap or Secret object
  • Any source that can be loaded by a Java application

1.2. Adding YAML configuration support
Copy link

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 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. You can delete the application.properties file and use only one type of configuration file to avoid errors.

Procedure

  1. 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:

      Example pom.xml file

      <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-config-yaml</artifactId>
</dependency>
      Copy to Clipboard Toggle word wrap

    • 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"
      Copy to Clipboard Toggle word wrap

1.2.1. Using nested object configuration with YAML
Copy link

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 by 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 following example:

    Example application.yaml file

    # 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
    Copy to Clipboard Toggle word wrap

    In a similar way of using the comments in 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 allow you to use tabs for indentation.

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 shows 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 by using the "%<profile_name>" syntax. Ensure that you place the profile name inside quotation marks.

    Tip

    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
    Copy to Clipboard Toggle word wrap

1.3. Property expressions
Copy link

Property expressions are combinations of property references and plain text strings that you can use to substitute values of properties in your configuration.

Much like a variable, you can use a property expression in Quarkus to substitute a value of a configuration property instead of hardcoding it. A property expression is resolved when java.util.Properties reads the value of the property from a configuration source in your application.

This means that if a configuration property is read from your configuration at compile time, the property expression is also resolved at compile time. If the configuration property is overriden at runtime, its value is resolved at runtime.

You can resolve property expressions by using more than one configuration source. This means that you can use a value of a property that is defined in one configuration source to expand a property expression that you use in another configuration source.

If the value of a property in an expression cannot be resolved, and you do not set a default value for the expression, your application encounters a NoSuchElementException.

This section shows examples of how you can use property expressions to achieve flexibility when configuring your Quarkus application.

Note

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

Example application.yaml file

mach: 3
x:
  factor: 2.23694

display:
  mach: ${mach}
  unit:
    name: "mph"
    factor: ${x.factor}
Copy to Clipboard Toggle word wrap

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

Note

The values in the config/application.yaml file, if exists, override any values from the regular application.yaml file.

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
Copy to Clipboard Toggle word wrap

1.5. Managing configuration key conflicts
Copy link

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

  • 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 defininf a YAML property as a prefix

    quarkus:
  http:
    cors:
      ~: true
      methods: GET,PUT,POST
    Copy to Clipboard Toggle word wrap

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

    Compile your Quarkus application

    ./mvnw quarkus:dev
    Copy to Clipboard Toggle word wrap

    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.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat