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

Copyedit the style of config-yaml.adoc for reuse in the product docs #35622

Merged
merged 1 commit into from
Oct 26, 2023
Merged
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
76 changes: 39 additions & 37 deletions docs/src/main/asciidoc/config-yaml.adoc
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
////
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

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

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'YAML configuration'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'YAML configuration'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 6, "column": 3}}}, "severity": "INFO"}
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.
:topics: configuration
:extensions: io.quarkus:quarkus-config-yaml

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

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

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Enable YAML configuration'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Enable YAML configuration'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 18, "column": 4}}}, "severity": "INFO"}

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 @@ -39,16 +39,15 @@
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

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

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Example YAML configurations'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Example YAML configurations'.", "location": {"path": "docs/src/main/asciidoc/config-yaml.adoc", "range": {"start": {"line": 48, "column": 5}}}, "severity": "INFO"}

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

[source,yaml]
----
Expand Down Expand Up @@ -113,13 +112,18 @@

== 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 120 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": 120, "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, such as `%staging` in the following example:

[source, yaml]
----
Expand All @@ -133,12 +137,12 @@
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 144 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": 144, "column": 28}}}, "severity": "INFO"}

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

== 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 163 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": 163, "column": 127}}}, "severity": "INFO"}

[source, yaml]
----
Expand All @@ -172,12 +175,12 @@
factor: ${x.factor}
----

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

Check warning on line 178 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": 178, "column": 71}}}, "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 @@ -187,16 +190,16 @@
├── 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 197 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": 197, "column": 55}}}, "severity": "INFO"}
rolfedh marked this conversation as resolved.
Show resolved Hide resolved
However, structured formats such as 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 @@ -207,5 +210,4 @@
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.