Master Spring Boot 3 Configuration: Multi‑File Profiles & Cloud Platform Activation

1. Introduction

Spring Boot can load configuration properties from various sources such as application.properties , application.yml , command‑line arguments, and system environment variables. Different environments (development, test, production) typically use separate configuration files.

2. Activating Configuration Files

Traditional activation uses spring.profiles.active in application.yml or as a command‑line argument:

<code>spring:
  profiles:
    active:
      - prod</code>

or

<code>java -jar app.jar --spring.profiles.active=prod</code>

This approach has drawbacks: it is a global setting affecting the entire configuration and lacks fine‑grained control.

3. Using spring.config.activate.on-profile

A more flexible way is to activate configuration documents conditionally with spring.config.activate.on-profile . Example:

<code>spring:
  profiles:
    active:
      - test
      - live
---
pack.app:
  name: dev app
spring.config.activate:
  on-profile:
    - dev
---
pack.app:
  name: test app
spring.config.activate:
  on-profile:
    - test
---
pack.app:
  name: prod app
spring.config.activate:
  on-profile:
    - prod</code>

Depending on the active profile, the corresponding logical document is applied.

4. Multi‑Document YAML Files

Spring Boot supports splitting a single physical file into multiple logical documents separated by --- . Later documents can override earlier ones. Example (YAML):

<code>spring:
  application:
    name: pack-app
---
logging:
  pattern:
    dateformat: yyyy-MM-dd HH:mm 
---
spring:
  profiles:
    active:
      - prod</code>

For .properties format, use #--- as a separator.

5. Conditional Activation for Cloud Platforms

Spring can also activate configuration based on the detected cloud platform using spring.config.activate.on-cloud-platform . Example for Kubernetes:

<code>public enum CloudPlatform {
  KUBERNETES {
    private static final String KUBERNETES_SERVICE_HOST = "KUBERNETES_SERVICE_HOST";
    private static final String KUBERNETES_SERVICE_PORT = "KUBERNETES_SERVICE_PORT";
    public boolean isDetected(Environment environment) {
      if (environment instanceof ConfigurableEnvironment configurableEnvironment) {
        return isAutoDetected(configurableEnvironment);
      }
      return false;
    }
    private boolean isAutoDetected(ConfigurableEnvironment environment) {
      PropertySource<?> envSource = environment.getPropertySources()
        .get(StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME);
      if (envSource != null) {
        return envSource.containsProperty(KUBERNETES_SERVICE_HOST) &&
               envSource.containsProperty(KUBERNETES_SERVICE_PORT);
      }
      return false;
    }
  }
}</code>

Configuration example:

<code>---
pack.app:
  name: dev app
spring.config.activate:
  on-cloud-platform: kubernetes
  on-profile:
    - dev
---</code>

The configuration becomes effective only when the application runs on Kubernetes and the dev profile is active.

6. Summary

By leveraging profile‑specific YAML files, the spring.config.activate family of properties, and multi‑document files, developers can finely control configuration for different environments and cloud platforms in Spring Boot 3.