Master Spring Boot 2.4+ Multi‑Environment Config: From Deprecated Profiles to spring.config.activate.on-profile

Spring Boot Multi‑Environment Configuration

Spring Boot 2.4+ marks spring.profiles.active as deprecated, encouraging developers to adopt the newer spring.config.activate.on-profile approach while still supporting the classic method for backward compatibility.

Traditional Multi‑File Configuration

Projects typically define a base application.yml (or .properties) and environment‑specific files such as application-dev.yml, application-test.yml, and application-prod.yml. The active profile is set either in the base file or via a JVM argument.

server:
  port: 8080
spring:
  profiles:
    active: dev

Alternatively, start the JAR with -Dspring.profiles.active=dev,master to activate multiple profiles without rebuilding.

Single‑File Profile Configuration

All profiles can be defined in one application.yml using document separators ( ---) and the spring.profiles key. Each section begins with spring.profiles: <profile>, producing the same effect as separate files.

server:
  port: 8080
spring:
  profiles:
    active: test
---
spring:
  profiles: test
server:
  port: 9090
---
spring:
  profiles: prod
server:
  port: 9090

New Configuration Style (spring.config.activate.on-profile)

From Spring Boot 2.4 onward, the preferred way is to replace spring.profiles.active with spring.config.activate.on-profile inside each profile’s YAML block. The activation command remains unchanged.

server:
  port: 8080
spring:
  profiles:
    active: test
---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 9090
---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 9090

Additional Considerations

YAML loading order : In 2.4+, properties are loaded in the order they appear; later entries override earlier ones.

Profile overriding : External application.properties now overrides internal profile‑specific files, regardless of activation.

Legacy mode : Set spring.config.use-legacy-processing=true to retain the old processing behavior, though this is not recommended for long‑term projects.

Conclusion

Upgrading to the new configuration model brings better Kubernetes compatibility and resolves previous file‑loading issues, but it also introduces ordering and overriding nuances that require careful testing before migration.