Chapter 1. Configuring your Red Hat build of Quarkus applications by using a YAML file
Chapter 1. Configuring your Red Hat build of 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 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.8.6 or later. Download Maven from the Apache Maven Project website. You have configured Apache Maven to use artifacts from the Quarkus Maven repository . To learn how to configure Apache Maven settings, see Getting started with Quarkus . 1.1. 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 . Red Hat 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 1.2. 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 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 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" 1.2.1. Using nested object configuration with YAML You can define nested configuration properties within the existing ones for your Red Hat 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 Open the src/main/resources/application.yaml configuration file. 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 only for illustration purposes. Instead set them in your environmental variables. For more information, see Setting configuration properties section of the "Configuring your Red Hat 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. 1.2.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 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 Open your project's configuration file, src/main/resources/application.yaml . 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 only for illustration purposes. Instead set them in your environmental variables. For more information, see Setting configuration properties section of the "Configuring your Red Hat build of Quarkus applications by using a properties file" guide. 1.3. Property expressions You can combine property references and text strings into property expressions and use these expressions as values in your Quarkus configuration. Like variables, property expressions substitute configuration property values dynamically, avoiding hard-coded values. You can expand an expression in one configuration source with a value defined in another. The application resolves a property expression when java.util.Properties reads the property value from a configuration source: at compile time if read then, and at runtime if overridden at that point. If the application cannot resolve the value of a property in an expression, and the property does not have a default value, your application throws a NoSuchElementException error. 1.3.1. 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: USD{mach} unit: name: "mph" factor: USD{x.factor} Note To reference nested properties, use the . (dot) separator, as in {x.factor} . Additional resources For more information about property expressions, see Property expressions . For an example usage of property expressions in a properties file, see Example usage of property expressions . 1.4. 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 For more information about adding YAML configuration support, see Adding YAML configuration support . 1.5. 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 Open your YAML configuration file. 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 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. 1.6. Additional resources Configuring your Quarkus applications by using a properties file
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-config-yaml</artifactId> </dependency> ./mvnw quarkus:add-extension -Dextensions="quarkus-config-yaml" 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 "%dev": quarkus: datasource: db-kind: postgresql jdbc: url: jdbc:postgresql://localhost:5432/quarkus_test username: quarkus_test password: quarkus_test mach: 3 x: factor: 2.23694 display: mach: USD{mach} unit: name: "mph" factor: USD{x.factor} ├── config │ └── application.yaml ├── my-app-runner quarkus: http: cors: ~: true methods: GET,PUT,POST ./mvnw quarkus:dev