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:

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

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.

<code>test: "value"
---
test: "overridden-value"
</code>

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 (

#---

).

<code>test=value
#---
test=overridden-value
</code>

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.

<code>test=value
#---
spring.config.activate.on-profile=dev
test=overridden-value
</code>

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

<code>spring.profiles.group.prod=proddb,prodmq,prodmetrics
</code>

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:

<code>application.name=myapp
spring.config.import=developer.properties
</code>

Import can be combined with profile activation:

<code>spring.config.activate.on-profile=prod
spring.config.import=prod.properties
</code>

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.

<code>spring.config.import=configtree:/etc/config
</code>

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

).

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

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.