YAML Configuration
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:
quarkus extension add quarkus-config-yaml
./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'
./gradlew addExtension --extensions='quarkus-config-yaml'
You can also just add the following dependency into your project:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-config-yaml</artifactId>
</dependency>
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:
quarkus:
http:
port: 8081
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.