Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

config yaml guide updates #32869

Closed
wants to merge 2 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 195 additions & 49 deletions docs/src/main/asciidoc/config-yaml.adoc
Original file line number Diff line number Diff line change
@@ -1,26 +1,38 @@
////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
This document is maintained in the main Quarkus repository, and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= YAML Configuration
[id="config-yaml"]
= Configure Quarkus applications by using a YAML file
include::_attributes.adoc[]
:diataxis-type: howto
:categories: core
:summary: YAML as a Configuration Source.
:summary: Optionally, you can configure your application properties with an `application.yaml` file instead of the default `application.properties` file.

https://en.wikipedia.org/wiki/YAML[YAML] is a very popular format. Kubernetes relies heavily on the YAML format to
write the various resource descriptors.
[id="overview"]
== Overview

Quarkus offers the possibility to use YAML in addition to the standard Java Properties file.
This guide introduces the use of a YAML configuration file, `application.yaml`, as an alternative to the traditional `application.properties` file for application configuration. Functionality remains consistent across both formats.

== Enabling YAML Configuration
[id="proc_enabling-yaml-configuration"]
== Enabling YAML configuration

To enable YAML configuration, add the `quarkus-config-yaml` extension:
To enable support for a `application.yaml` file, add the `quarkus-config-yaml` extension to the `pom.xml` or `build.gradle` file in your project.

.Prerequisites

include::{includes}/prerequisites.adoc[]
* A {project-name} Maven project.

.Procedure

. Add the `quarkus-config-yaml` extension to your project:
+
--
:add-extension-extensions: quarkus-config-yaml
include::{includes}/devtools/extension-add.adoc[]

You can also just add the following dependency into your project:
Or, add the following dependency to your project:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
Expand All @@ -36,43 +48,112 @@ You can also just add the following dependency into your project:
----
implementation("io.quarkus:quarkus-config-yaml")
----
--
rolfedh marked this conversation as resolved.
Show resolved Hide resolved
. Create the `src/main/resources/application.yaml` file.
+
TIP: You can use the `yml` or `yaml` file extension.

. To avoid potential confusion, remove the `src/main/resources/application.properties` file.
+
NOTE: If both files are present, the values of properties in `application.yaml` override any duplicate properties in `application.properties`.

[id="proc_using-object-configuration-with-yaml"]
== Using object configuration with YAML

Remove the `src/main/resources/application.properties` and create a `src/main/resources/application.yaml` file.
In the YAML configuration file, you can define an element inside an existing element to set configuration properties for your {project-name} application.

NOTE: 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.
.Prerequisites

TIP: Quarkus supports both the `yml` and `yaml` file extensions.
include::{includes}/prerequisites.adoc[]
* A {project-name} Maven project.
* A PostgreSQL data source.
* The following extensions as dependencies in your project's `pom.xml` or `build.gradle` file:
** `quarkus-rest-client`
** `quarkus-jdbc-postgresql`
** `quarkus-config-yaml`

=== Example
.Procedure

The following snippets provide examples of YAML configuration:
. Open the `src/main/resources/application.yaml` configuration file.

. Add configuration properties to your `application.yaml` file.
+
.Example configuration properties
[source,yaml]
----
# YAML supports comments
# Properties that configure the JDBC data source driver of your PostgreSQL data source
quarkus:
datasource:
db-kind: postgresql
jdbc:
url: jdbc:postgresql://localhost:5432/some-database
url: jdbc:postgresql://localhost:5432/some-database
driver: org.postgresql.Driver
username: quarkus
password: quarkus

# REST Client configuration property
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 configuration profiles
"%test":
quarkus:
oidc:
enabled: false
security:
users:
file:
enabled: true
realm-name: quarkus
plain-text: true

# 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:
rest-client:
org.acme.rest.client.ExtensionsService:
url: https://stage.code.quarkus.io/api
----
log:
category:


[source,yaml]
----
# For configuration property names that use quotes, do not split the string inside the quotes
quarkus:
log:
category:
"io.quarkus.category":
level: INFO


# REST Client configuration property
quarkus:
rest-client:
url: https://stage.code.quarkus.io/api
org.acme.rest.client.ExtensionsService:

----
+
You can use comments to describe configuration properties.
+
[NOTE]
====
Always use spaces to indent the properties in your YAML configuration file.
YAML does not support using tabs for indentation.
====

=== Additional examples of configuration properties

[source, yaml]
----
Expand All @@ -96,7 +177,7 @@ app:
oidc-app: app
oidc-server: http://localhost:8180/auth

# With profiles
# With configuration profiles
"%test":
quarkus:
oidc:
Expand All @@ -109,7 +190,8 @@ app:
plain-text: true
----

== Profiles
[id="proc_using-configuration-profiles-with-yaml"]
== Using configuration profiles with YAML

As you can see in the previous snippet, you can use xref:config-reference.adoc#profiles[profiles] in YAML. The profile
key requires double quotes: `"%test"`. This is because YAML does not support keys starting with `%`.
Expand Down Expand Up @@ -152,12 +234,30 @@ quarkus:
port: 8082
----

== Expressions
[id="con_property-expressions"]
== Using property expressions in a YAML file

The YAML format also supports xref:config-reference.adoc#property-expressions[property expressions], using the same format as Java
Properties:
Property expressions are similar to variables: instead of hardcoding a property value, you can use a property expression.
The configuration system resolves the property expression when it gets the values from the configuration source in the application:

[source, yaml]
* If it reads the configuration property from your configuration at compile time, the property expression is also resolved at compile time.
* If the configuration property is overridden at run time, its value is resolved at run time.

You can use multiple sources to resolve property expressions.
You can use a property value from one source to expand an expression in another.

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

.Procedure

Property expressions have the `${property_name}` format.

.Example property expressions in `application.yaml`

This section shows examples of using property expressions to achieve flexibility when configuring your {project-name} application.

.Example file
[source,properties,options="nowrap"]
----
mach: 3
x:
Expand All @@ -170,32 +270,63 @@ display:
factor: ${x.factor}
----

Note that you can reference nested properties using the `.` (dot) separator as in `${x.factor}`.
[NOTE]
====
You can reference properties by using the `.` (dot) separator, as in `{x.factor}`.
====

.Additional resources

* For more information about property expressions, see xref:con_property-expressions[Property expressions].
// * For an example of property expressions using a properties file, see link:{URL_CONFIGURATION_QUARKUS}#ref_example-usage-of-property-expressions_quarkus-configuration-guide[Example usage of property expressions]. // TBD update and enable this ^ link later when this guide becomes available

[id="proc_configure-properties-at-run-time-external-yaml"]
== Configure properties at run time
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't we write it runtime? At least that's how we used to write it everywhere? Did it change?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IBM Style states:

run time, runtime noun
- Write as two words to refer to the time at which an application runs (for example, “At run time, you can…”).
- Write as one word to refer to the environment in which an application runs (for example, “The Java runtime is
controlled by…”).

However, if you feel strongly about it, we can use runtime. Most users are probably fine with it as a single word. Just let me know.


To configure properties at run time, you can create an external configuration file by placing an `application.yaml` file in the `config` directory.

When you run the application, the values from the `config/application.yaml` file override those of identical properties in `resources/application.yaml` file.

== External application.yaml file
.Prerequisites

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:
include::{includes}/prerequisites.adoc[]
* The `quarkus-config-yaml` extension as a dependency in your project's `pom.xml` or `build.gradle` file.

[source, text]
.Procedure

. Add an `application.yaml` file to the `config` directory.

. Verify that the `config/application.yaml` file is in the root of the working directory relative to the {project-name} application runner, as shown in the following example:
+
[source,properties,options="nowrap"]
----
.
├── config
│ └── application.yaml
├── my-app-runner
----

The values from this file override any values from the regular `application.yaml` file if exists.
.Additional resources

* xref:proc_enabling-yaml-configuration[Enabling YAML configuration].

[id="proc_managing-configuration-key-conflicts"]
== Managing configuration key 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about the rules and maybe this needs to be discussed at a higher level but we are adding a ton of procedures/prerequisites and this adds a lot of noise when you are trying to find some information.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please feel free to strike any information that doesn't add value for our customers.
In future projects, rather than trying to merge the community and product content, I'll adopt an "additive" process. That is, I'll ask the SME to identify which product content they want to migrate to the community docs first.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, if you feel like that's too much trouble, I can toss out this PR and we start over with the proposed "additive" process instead.


== Configuration key conflicts
.Prerequisites

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.
include::{includes}/prerequisites.adoc[]
* The `quarkus-config-yaml` extension as a dependency in your project's `pom.xml` or `build.gradle` file.

This is solved by using a `null` key (represented by `~`) for any YAML property which is a prefix of another one:
.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
[source,yaml]
----
quarkus:
Expand All @@ -204,6 +335,21 @@ quarkus:
~: 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.
+
. To compile your {project-name} application in development mode, enter the following command from the project directory:
+
.Compile your {project-name} application
[source,bash]
----
./mvnw quarkus:dev
----
+
Comment on lines +338 to +346
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure of the value of this here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally, this type of information is useful for non-expert users such as students. Red Hat generally gets complaints from newer users that our documentation assumes too much expertise or prior knowledge.

[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
//
// * link:{URL_CONFIGURATION_QUARKUS}[Configuring your {project-name} applications by using a properties file] // TBD update link
// TBD update and enable this ^ link later when this guide becomes available