# YAML configuration

You can use a YAML file,`application.yaml`, to configure your Quarkus application instead of the standard Java properties file, `application.properties`.

YAML is widely used for defining resource descriptors, especially in Kubernetes.

## Enable 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'

Alternatively, add the following dependency to your project:

pom.xml

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

build.gradle

    implementation("io.quarkus:quarkus-config-yaml")

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.

| If both files are present, Quarkus gives precedence to properties in the YAML file.

| Quarkus recognizes both `.yml` and `.yaml` file extensions.

### Example YAML configurations

The following snippets give examples of YAML configurations:

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

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"`.

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:

    quarkus:
      http:
        port: 8081

    "%staging":
        quarkus:
            http:
              port: 8082

If you enable the `staging` profile, the HTTP port is set to `8082` instead of `8081`.

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:

    quarkus:
      http:
        port: 8081

application-staging.yaml

    quarkus:
      http:
        port: 8082

| An `application.yaml` file must exist (even if empty) in the exact location of the profile-aware (`application-{profile}.yaml`) file to be included in the configuration to ensure a consistent order when loading the files.

## Expressions

The YAML format also supports property expressions, by using the same format as Java properties:

    mach: 3
    x:
      factor: 2.23694

    display:
      mach: ${mach}
      unit:
        name: "mph"
        factor: ${x.factor}

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

## External application.yaml file

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 Quarkus application runner:

    .
    ├── config
    │    └── application.yaml
    ├── my-app-runner

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

## Configuration property conflicts

The MicroProfile Config specification defines configuration properties as an arbitrary `.`-delimited string. 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 `~` as a `null` key to represent any YAML property that 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 at any level for disambiguating configuration properties.

Although Quarkus primarily uses `.properties` file extension for configuration, the snakeyaml library, which is used for parsing YAML in Quarkus, can also parse JSON structures. This means you can use YAML files with JSON content inside.

YAML and JSON structures can be read in an application.yaml file.

Certainly, here’s a step-by-step guide on how to use complex configuration structures with Quarkus:

- Define Your Configuration Interface.

    @ConfigMapping(prefix = "server")
    public interface ServiceConfig {

      List<Environment> environments();

      interface Environment {
        String name();
        String services();
      }
    }

- Create the appropriate JSON structure and store it in a YAML file.

    {
      "server": {
        "environments": [
          {
            "name": "dev",
            "services": "bookstore"
          },
          {
            "name": "batch",
            "services": "warehouse"
          }
        ]
      }
    }