Skip to content

Commit

Permalink
Update the content for RHBQ docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@rolfedh
rolfedh committed Sep 12, 2023
1 parent 718a8d5 commit 3a49063
Showing 1 changed file with 39 additions and 37 deletions.
76 changes: 39 additions & 37 deletions docs/src/main/asciidoc/config-yaml.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
This guide 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"]
= YAML configuration
include::_attributes.adoc[]
:diataxis-type: howto
:categories: core
:summary: YAML as a Configuration Source.
:summary: Optionally, use `application.yaml` instead of `application.properties` to configure your application.

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.
You can use a YAML file,`application.yaml`, to configure your {project-name} application instead of the standard Java properties file, `application.properties`.

Quarkus offers the possibility to use YAML in addition to the standard Java Properties file.
link:https://en.wikipedia.org/wiki/YAML[YAML] is widely used for defining resource descriptors, especially in Kubernetes.

== Enabling YAML Configuration
== Enable YAML configuration

To enable YAML configuration, add the `quarkus-config-yaml` extension:

:add-extension-extensions: quarkus-config-yaml
include::{includes}/devtools/extension-add.adoc[]

You can also just add the following dependency into your project:
Alternatively, 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 @@ -37,16 +37,15 @@ You can also just add the following dependency into your project:
implementation("io.quarkus:quarkus-config-yaml")
----

Remove the `src/main/resources/application.properties` and create a `src/main/resources/application.yaml` file.
After adding the extension or dependency, to avoid confusion, remove the `src/main/resources/application.properties` file and create a `src/main/resources/application.yaml` file.

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.
NOTE: If both files are present, {project-name} gives precedence to properties in the YAML file.

TIP: Quarkus supports both the `yml` and `yaml` file extensions.
TIP: {project-name} recognizes both `.yml` and `.yaml` file extensions.

=== Example
=== Example YAML configurations

The following snippets provide examples of YAML configuration:
The following snippets give examples of YAML configurations:

[source,yaml]
----
Expand Down Expand Up @@ -111,13 +110,18 @@ app:

== Profiles

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 `%`.
As you can see in the previous snippet, you can use xref:{doc-guides}/config-reference.adoc#profiles[profiles] in YAML.

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:
In YAML, keys that begin with `%` are not allowed.
However, profile keys must start with this symbol.
To resolve this, enclose the profile keys in double quotes, as demonstrated by the example, `"%test"`.

Check warning on line 118 in docs/src/main/asciidoc/config-yaml.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 118, "column": 50}}}, "severity": "INFO"}

All configurations under the `"%test"` key activate only when the `test` profile is enabled.
For instance, the previous snippet shows that OpenID Connect (OIDC) (`quarkus.oidc.enabled: false`) is disabled when the `test` profile is active.
Without the `test` profile, OIDC is enabled by default.

You can also define custom profiles; like `%staging` in the following example:

[source, yaml]
----
Expand All @@ -131,12 +135,12 @@ quarkus:
port: 8082
----

If you enable the `staging` profile, the HTTP port will be 8082, whereas it would be 8081 otherwise.
If you enable the `staging` profile, the HTTP port is set to `8082` instead of `8081`.

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:
The YAML configuration also supports profile-aware files.
In this case, properties for a specific profile can reside in an `application-{profile}.yaml` named file.
The previous example can be expressed as:

Check warning on line 142 in docs/src/main/asciidoc/config-yaml.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 142, "column": 28}}}, "severity": "INFO"}

.application.yaml
[source, yaml]
----
quarkus:
Expand All @@ -154,8 +158,7 @@ quarkus:

== Expressions

The YAML format also supports xref:config-reference.adoc#property-expressions[property expressions], using the same format as Java
Properties:
The YAML format also supports xref:config-reference.adoc#property-expressions[property expressions], by using the same format as Java properties:

Check warning on line 161 in docs/src/main/asciidoc/config-yaml.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 161, "column": 127}}}, "severity": "INFO"}

[source, yaml]
----
Expand All @@ -170,12 +173,12 @@ display:
factor: ${x.factor}
----

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

Check warning on line 176 in docs/src/main/asciidoc/config-yaml.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 176, "column": 36}}}, "severity": "INFO"}

Check warning on line 176 in docs/src/main/asciidoc/config-yaml.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 176, "column": 68}}}, "severity": "INFO"}

== 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:
The `application.yaml` file can also be placed in `config/application.yaml` to specialize the runtime configuration.
The file must be present in the root of the working directory relative to the {project-name} application runner:

[source, text]
----
Expand All @@ -185,16 +188,16 @@ file has to be present in the root of the working directory relative to the Quar
├── my-app-runner
----

The values from this file override any values from the regular `application.yaml` file if exists.
The values from this file override any values from the regular `application.yaml` file if it 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.
The MicroProfile Config specification defines configuration keys as an arbitrary `.`-delimited string.

Check warning on line 195 in docs/src/main/asciidoc/config-yaml.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 195, "column": 55}}}, "severity": "INFO"}
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 might 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:
This is solved by using `~` as a `null` key to represent any YAML property that is a prefix of another one:

[source,yaml]
----
Expand All @@ -205,5 +208,4 @@ quarkus:
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.
YAML `null` keys are not included in the assembly of the configuration property name, allowing them to be used at any level for disambiguating configuration keys.

0 comments on commit 3a49063

Please sign in to comment.