diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index 33109f1b38aaa..64cb37de65775 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -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 @@ -36,43 +48,112 @@ You can also just add the following dependency into your project: ---- implementation("io.quarkus:quarkus-config-yaml") ---- +-- +. 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] ---- @@ -96,7 +177,7 @@ app: oidc-app: app oidc-server: http://localhost:8180/auth -# With profiles +# With configuration profiles "%test": quarkus: oidc: @@ -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 `%`. @@ -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: @@ -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 + +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. -== 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: @@ -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 +---- ++ +[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