# 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:

CLI

    quarkus extension add 'quarkus-config-yaml'

Maven

    ./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'

Gradle

    ./gradlew addExtension --extensions='quarkus-config-yaml'

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

pom.xml

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-config-yaml</artifactId>
    </dependency>

build.gradle

    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:

application.yaml

    quarkus:
      http:
        port: 8081

application-staging.yaml

    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.