What Changed in Spring Boot 2.4 Config File Processing?

Spring Boot 2.4.0.M2 has just been released and it restructures the way application.properties and application.yml files are loaded. Simple single‑file configurations may not show any difference, but complex setups such as Spring Cloud Config require understanding the changes.

Why the changes?

Spring is improving native support for Kubernetes . In Spring Boot 2.3 the support for Kubernetes Volume configuration was added but not fully realized.

Volume mounting is a common Kubernetes feature; the ConfigMap directive can expose configuration directly on the file system, either as a full YAML file with multiple keys/values or as a simple directory‑tree where file names are keys and file contents are values.

To support both approaches while keeping compatibility with existing application.properties and application.yml, the core class ConfigFileApplicationListener needed to be modified.

ConfigFileApplicationListener issues

The listener is a core piece of Spring Boot’s configuration loading and is difficult to maintain. Two main problems are:

Configuration files are highly flexible and can enable other files from within a file.

The loading order of documents is not fixed.

Example of a multi‑document YAML file:

security.user.password: usera
---
spring.profiles: local
security.user.password: userb
runlocal: true
---
spring.profiles: !dev
spring.profiles.include: local
security.user.password: userc

This file contains three logical documents separated by ---. When the active profile is set with --spring.profile.actives=prod, the value of security.user.password and whether runlocal is applied become ambiguous, leading to frequent bugs.

Two major changes in Spring Boot 2.4

Documents are loaded in the order they are defined.

Profile activation switches can no longer be configured in a specific environment file.

Document ordering

From Spring Boot 2.4 onward, when loading Properties and YAML files, properties defined earlier are overridden by later ones, mirroring the behavior of a .properties map where later entries replace earlier values.

For multi‑document YAML the same rule applies: a lower‑ordered document is overridden by a higher‑ordered one.

test: "value"
---
test: "overridden-value"

Properties files now support multi‑document attributes

Spring Boot 2.4 adds a YAML‑like multi‑document capability to Properties files. Documents are separated by a comment line containing three dashes ( #---).

test=value
#---
test=overridden-value

Specific‑environment activation

In Spring Boot 2.3 the key spring.profiles was used to activate a profile. In 2.4 it has been replaced by spring.config.activate.on-profile.

Example: make the property test override only when the dev profile is active.

test=value
#---
spring.config.activate.on-profile=dev
test=overridden-value

Profile activation via root file

Using spring.profiles.active in the root application.properties or application.yml still activates the corresponding environment files, but it must not be combined with spring.config.activate.on-profile. Mixing them results in an exception.

Profile groups

Spring Boot 2.4 introduces profile groups, allowing a single logical profile to expand into multiple sub‑profiles. Define a group in the configuration file, e.g.:

spring.profiles.group.prod=proddb,prodmq,prodmetrics

Activating prod now activates all three listed profiles.

Importing extended configuration

The new spring.config.import property lets you import additional properties or yaml files directly from application.properties or application.yml. Earlier versions only supported spring.config.additional-location with limited file types.

Example importing a developer‑specific file:

application.name=myapp
spring.config.import=developer.properties

Import can be combined with profile activation:

spring.config.activate.on-profile=prod
spring.config.import=prod.properties

Imports are treated as additional documents inserted below the declaring document and follow the same top‑down ordering rules.

Volume‑mount configuration

Using the configtree: prefix tells Spring Boot to read configuration from a Kubernetes volume mount.

spring.config.import=configtree:/etc/config

Files under /etc/config become properties such as my.application and test with values taken from the corresponding files in the volume.

Activation by cloud platform

The property spring.config.activate.on-cloud-platform works like spring.config.activate.on-profile but activates based on the detected CloudPlatform (e.g., kubernetes).

spring.config.activate.on-cloud-platform=kubernetes
spring.config.import=configtree:/etc/config

Supporting other locations

The location string used with spring.config.import is fully pluggable. Custom ConfigDataLocationResolver and ConfigDataLoader implementations can add support for schemes such as archaius://…, vault://…, or zookeeper://….

Version rollback

If you need the old processing behavior, set spring.config.use-legacy-processing=true to revert to the pre‑2.4 handling.

Summary

The new configuration data processing in Spring Boot 2.4 aims to be more predictable, offering deterministic ordering, clearer profile activation, multi‑document support for both YAML and properties, profile groups, flexible imports, and Kubernetes‑aware configuration while still providing a legacy mode for backward compatibility.

References

Spring Boot 2.4.0.M2 release announcement.

Multi‑document YAML specification.

Report issues on GitHub.

Official Spring Boot reference documentation for external configuration files.