# Spring Config Import Demystified

> How Spring Boot processes spring.config.import: loading passes, property precedence, resolvers, loaders, and integration with Vault and Config Server.

- URL: https://foojay.io/today/spring-config-import-demystified/
- Published: 2026-11-16
- Authors: Dmitry Mazurov
- Categories: Java, Spring
- Originally published at: https://axelix.io/blog/spring-config-import-demystified


Hi everyone! My name is Dmitry Mazurov, and I am an OSS contributor [to the Axelix project](https://github.com/axelixlabs/axelix). It is an open-source product that helps find common problems and inefficiencies in Spring Boot applications.

In [the previous article](/today/environment-post-processor/), Mikhail examined `EnvironmentPostProcessor` and briefly mentioned `ConfigDataEnvironmentPostProcessor`, which loads `application.yml`, handles profiles, and processes `spring.config.import`. Today, we will look inside it.

This investigation started with a practical task. We needed to integrate Axelix Master with Vault in such a way that users could configure it through our own properties under `axelix.master.*`, rather than through `spring.cloud.vault.*`. To do this cleanly, we first had to understand how entries like these actually work:

```yaml
spring:
  config:
    import:
      - "configserver:http://config:8888"
      - "vault://secret/my-app"
      - "optional:kubernetes:"
```

**TL;DR:** all three prefixes are backed by the same small contract consisting of two interfaces: `ConfigDataLocationResolver` and `ConfigDataLoader`. All loading happens inside a single `EnvironmentPostProcessor`, over three passes. Once you understand these three passes, it becomes clear where each value comes from and in what order.

## A Bit of History

Before Spring Boot 2.4, configuration was loaded by `ConfigFileApplicationListener`. Over time, its logic accumulated so many special cases that changing it became nearly impossible. [Phil Webb described this in detail in his post about the redesign](https://spring.io/blog/2020/08/14/config-file-processing-in-spring-boot-2-4).

At the same time, there was another world. Spring Cloud Config and Spring Cloud Vault fetched remote configuration through a separate bootstrap context, with its own `bootstrap.yml`, its own parent `ApplicationContext`, and its own precedence rules. An application had two loading mechanisms, each with its own surprises.

Spring Boot 2.4 unified these two worlds. It introduced the Config Data API and the `spring.config.import` property, while Spring Cloud, starting with version 2020.0, migrated Config, Vault, Consul, and Zookeeper to it. Support was later added to Spring Cloud Kubernetes as well. The bootstrap context had primarily been needed to fetch configuration from remote sources; now, ordinary imports handle that job.

For this reason, [Spring Cloud 2020.0 disabled the bootstrap context by default](https://spring.io/blog/2020/10/07/spring-cloud-2020-0-0-m4-aka-ilford-is-available). It can be restored with `spring.cloud.bootstrap.enabled=true` or the `spring-cloud-starter-bootstrap` starter, but that is now a legacy mode.

In practice, this means that every configuration source, from a file on disk to Vault, is now connected in the same way and follows the same precedence rules. You only need to understand the mechanism once.

## One `EnvironmentPostProcessor` and Three Passes

All loading is performed by `ConfigDataEnvironmentPostProcessor`, an ordinary `EnvironmentPostProcessor` that Spring Boot runs very early. It delegates the work to `ConfigDataEnvironment`, which traverses the configuration sources three times and adds the loaded data to the `Environment`.

`ConfigDataEnvironment` stores configuration sources as a tree of `ConfigDataEnvironmentContributor` objects. The root of this tree contains everything already present in the `Environment`, such as environment variables and command-line arguments, as well as standard locations such as `application.yml`. If any of these sources or any loaded file contains `spring.config.import`, child `ConfigDataEnvironmentContributor` objects are added beneath it.

The tree is traversed three times:

1. **Initial pass, without an activation context.** Imports are processed from every source that has no activation conditions: environment variables, command-line arguments, and files. Activation conditions can only belong to loaded sources, such as files or data from Config Server, not to environment variables or command-line arguments. There are only two such conditions: `spring.config.activate.on-profile`, which includes a source only when one of the specified profiles is active, and `spring.config.activate.on-cloud-platform`, which includes it only on the specified platform, such as Kubernetes.
2. **Pass without profiles.** The initial configuration has now been loaded, and Spring Boot uses it to determine the cloud platform. This activates sources with `spring.config.activate.on-cloud-platform`, and their imports are processed as well.
3. **Pass with profiles.** Spring Boot determines the active profiles from everything loaded so far. It then resolves every location again, this time with profile information, and includes sources with `spring.config.activate.on-profile`.

![Three Config Data passes: load unconditional imports, activate cloud-platform sources, then resolve profile-specific configuration.](three-passes-two-phases.jpg)

The three passes form two phases: the first two passes run before profile activation, and the third runs afterward. Within each phase, the imports of a given source are processed no more than once, so they are processed at most twice in total.

The second pass therefore does not repeat the first. It only picks up sources that became active after the cloud platform was determined. The third pass, after profile activation, finds everything that depends on profiles. For example, the same standard location with the `dev` profile finds not only `application.yml`, but also `application-dev.yml`.

`ConfigDataImporter` remembers resources that have already been loaded, so it does not load `application.yml` again; only new data is added to the tree. Sources with `spring.config.activate.on-profile` are inactive before profile activation, so their imports are processed only during the third pass.

## Which Source Overrides Which?

Sources are loaded during the passes, but they are added to the `Environment` only at the very end. The `Environment` keeps its sources in a list and searches for a property from top to bottom, so the first source containing the key wins. From this point onward, a "more important" source means one that appears higher in this list.

After all three passes are complete, `ConfigDataEnvironment` traverses the tree and appends the loaded sources to the end of the list, below the sources that were already there. This produces the following rules:

- **Environment variables, system properties, and command-line arguments take precedence over configuration files and everything connected through `spring.config.import`.** They were already present in the `Environment` before configuration loading began, while loaded sources are placed below them. Therefore, `--server.port=9090` overrides `server.port` from both `application.yml` and Vault.
- **An imported source takes precedence over the source that declares the import.** The import is placed in the list immediately above the file that declared it. If `application.yml` contains `vault://`, values from Vault override properties with the same names in `application.yml`.
- **Among multiple imports in one list, the import declared later takes precedence.** With `spring.config.import: ["configserver:", "vault://"]`, Vault wins when both sources contain the same key.
- **Profile-specific sources take precedence over non-profile-specific ones.** `application-dev.yml` overrides `application.yml`, and `secret/my-app/dev` overrides `secret/my-app`.

The most important source is at the top and the least important at the bottom, with each source overriding everything below it.

![Property sources from highest to lowest precedence: command-line arguments, system properties, environment variables, application-dev.yml, profile-specific Vault secrets, base Vault secrets, and application.yml.](who-overrides-whom.jpg)

Consider the final order for an `application.yml` that imports `optional:vault://` while the `dev` profile is active. `application-dev.yml` appears above Vault, even though Vault overrides `application.yml`.

The reason is that an import is placed immediately above the file in which it was declared, not above every file. Vault is declared in `application.yml` and sits directly above it. `application-dev.yml`, however, is discovered as a separate file during the third pass and therefore comes first.

This leads to a non-obvious consequence: if the same property is defined in both Vault and `application-dev.yml`, the value from `application-dev.yml` wins.

You can see the final ordering of sources in a running application at the `/actuator/env` endpoint, where sources are listed from highest to lowest precedence. It is even easier [to inspect on the **Environment** page in Axelix](https://axelix.io/docs/features/spring-framework/properties). Properties are grouped by source, and a crown icon marks the value that is actually used when the same key is defined in multiple places.

## The Resolver and the Loader

Every entry in `spring.config.import` goes through two steps. First, a resolver turns the location string into one or more resources. Then, a loader turns each resource into a collection of `PropertySource` objects.

Both are registered in `META-INF/spring.factories`. Spring Boot itself uses this mechanism to register `ConfigTreeConfigDataLocationResolver` for the `configtree:` prefix, `SystemEnvironmentConfigDataLocationResolver` for `env:`, and `StandardConfigDataLocationResolver` for ordinary files.

A resolver has two methods: `resolve` and `resolveProfileSpecific`. Only `resolve` is called during the first two passes. During the third pass, both methods are called and their results are combined. Vault and Kubernetes need profile information, so they do all their work in `resolveProfileSpecific` and run only during the third pass.

Spring Boot selects the resolver as follows:

- Resolvers are sorted according to `Ordered` or `@Order`, and `isResolvable` is called on each resolver in turn. The first resolver to return `true` claims the location; the remaining resolvers are not consulted.
- `StandardConfigDataLocationResolver` is willing to accept any location: its `isResolvable` method always returns `true`. To prevent it from intercepting prefixes that belong to other resolvers, `ConfigDataLocationResolvers` explicitly moves it to the end of the list at startup, regardless of its order.

The loader in each pair is responsible for accessing the source itself. It reads a file, calls Vault or the Kubernetes API, and turns the response into a `PropertySource`. Spring Boot chooses a loader according to the resource type returned by the resolver. A resolver and loader for the same source therefore always operate as a pair, such as `VaultConfigDataLocationResolver` and `VaultConfigDataLoader`. If the source is unavailable or the resource does not exist, the error occurs at this step.

The `optional:` prefix marks a location as optional. If nothing is found there, the application still starts without an error. However, it also suppresses errors when the source is disabled in the configuration or its starter is missing, causing `StandardConfigDataLocationResolver` to claim the location. A typo in a prefix and a disabled source therefore look identical: nothing is loaded and no error is reported.

## Where a Resolver Gets Its Settings

A resolver reads its own settings, such as the Vault address, a Kubernetes namespace, or an application name, through the `Binder` available from `ConfigDataLocationResolverContext`. This `Binder` sees sources that are already in the `Environment` and everything loaded up to that point, but it cannot see anything that will be loaded later.

This is why Vault settings can be placed in `application.yml`. The file is loaded before the `vault://` import declared inside that same file is processed.

## One Pattern, Many Implementations

There are many implementations of this contract, including implementations for Consul, Zookeeper, and AWS Parameter Store. We will look at three popular sources from Spring Cloud. They all share the same structure, and their differences lie precisely in the areas described above.

Config Client contacts the server twice. A resource created without profiles is not equal to a resource created with profiles, so `ConfigDataImporter` cannot deduplicate them. This is intentional: the first request returns configuration before the profiles are determined, and that configuration may influence which profiles become active.

Kubernetes performs an additional platform check. Its `isResolvable` returns `true` only inside a cluster or when `spring.main.cloud-platform=kubernetes`. When running locally, `optional:kubernetes:` is simply skipped without a message. This is a common reason for asking, "Why weren't my ConfigMaps loaded?"

| Prefix | When it runs |
| --- | --- |
| [`configserver:`](https://github.com/spring-cloud/spring-cloud-config/blob/main/spring-cloud-config-client/src/main/java/org/springframework/cloud/config/client/ConfigServerConfigDataLocationResolver.java) | During the first and third passes, so the server is queried twice |
| [`vault:`](https://github.com/spring-cloud/spring-cloud-vault/blob/main/spring-cloud-vault-config/src/main/java/org/springframework/cloud/vault/config/VaultConfigDataLocationResolver.java) | Only during the third pass |
| [`kubernetes:`](https://github.com/spring-cloud/spring-cloud-kubernetes/blob/v5.0.3/spring-cloud-kubernetes-commons/src/main/java/org/springframework/cloud/kubernetes/commons/configdata/KubernetesConfigDataLocationResolver.java) | Only during the third pass, and only inside a cluster |

## `EnvironmentPostProcessor` Before and After Config Data

The previous article established this rule: an `EnvironmentPostProcessor` that reads configuration must run after `ConfigDataEnvironmentPostProcessor`, while one that determines where configuration comes from must run before it. Now that we understand the loading process, we can see where this rule comes from.

An `EnvironmentPostProcessor` that runs **before Config Data**, meaning its `getOrder()` is less than `ConfigDataEnvironmentPostProcessor.ORDER`, writes to the `Environment`, and everything it adds there becomes part of the root of the `ConfigDataEnvironmentContributor` tree. As a result, every resolver's `Binder` can see it. This can be used to supply `spring.cloud.vault.uri`, change the Kubernetes namespace, or add `spring.config.additional-location`. This is how Axelix Master turns its own `axelix.master.config.location` property into [an additional configuration location](https://github.com/axelixlabs/axelix/blob/master/master/src/main/java/com/axelixlabs/axelix/master/autoconfiguration/config/AxelixConfigLocationEnvironmentPostProcessor.java).

An `EnvironmentPostProcessor` that runs **after Config Data**, meaning its `getOrder()` is greater, runs after everything has been loaded, including secrets from Vault and ConfigMaps from Kubernetes. It can read and override the final values. This is how Axelix adds its endpoints to `management.endpoints.web.exposure.include`. However, such an `EnvironmentPostProcessor` can no longer affect loading itself: the resolvers have already run, and loading is complete.

Sometimes neither option works. An `EnvironmentPostProcessor` that runs before Config Data cannot see `application.yml`, because the file has not yet been loaded. If users put settings that need to be remapped into `application.yml`, an early `EnvironmentPostProcessor` cannot read them, while a late one arrives too late. This is exactly what we encountered in Axelix when moving Vault settings under our own prefix.

![An EnvironmentPostProcessor before Config Data can change loading settings; one after Config Data can read final values but cannot change what gets loaded.](before-and-after-config-data.jpg)

There is only one way out of this trap: intervene in Config Data processing after `application.yml` has been read but before the remote source is loaded. In Axelix, we did this in two ways: with placeholders and with a custom resolver.

## How Axelix Connects Config Server and Vault Through Its Own Settings

In Axelix Master, all settings live under `axelix.master.*`, and we want external configuration to be no exception. Users configure `axelix.master.external-config.spring-cloud-vault.*`, not `spring.cloud.vault.*`.

The task is exactly the one described above: these properties are stored in `application.yml`, but they must be applied before the `vault://` import runs.

### Config Server and Placeholders

Spring Cloud Config Client has relatively few settings, so placeholders are sufficient:

```yaml
spring:
  config:
    import:
      - "optional:configserver:"
      - "optional:vault://"
  cloud:
    config:
      enabled: "${axelix.master.external-config.spring-cloud-config.enabled}"
      fail-fast: true
      uri: "${axelix.master.external-config.spring-cloud-config.uri:}"
      username: "${axelix.master.external-config.spring-cloud-config.username:}"
      password: "${axelix.master.external-config.spring-cloud-config.password:}"
```

This works because the resolver's `Binder` resolves placeholders when reading the properties, and `application.yml` has already been loaded by then.

Notice the `optional:` prefix before `configserver:`. This is where our knowledge of `isResolvable` becomes useful: the Config Client resolver returns `true` only when `spring.cloud.config.enabled` is `true`. If the user disables Config Server, `StandardConfigDataLocationResolver` claims the `configserver:` location and cannot parse it as a file.

Without `optional:`, this causes a startup error. With it, the import is simply skipped. At the same time, `fail-fast` continues to work when the server is enabled.

### Vault and a Custom Resolver

Placeholders are not suitable for Vault. `VaultProperties` has dozens of properties covering different authentication methods, SSL, timeouts, and more. Listing all of them manually would mean maintaining a copy of someone else's class.

Instead, we wrote a custom resolver: [`AxelixVaultConfigDataLocationResolver`](https://github.com/axelixlabs/axelix/blob/master/master/src/main/java/com/axelixlabs/axelix/master/autoconfiguration/externalconfig/AxelixVaultConfigDataLocationResolver.java). It extends the standard Vault resolver and runs before it, so it claims the `vault://` location.

In `resolveProfileSpecific`, it reads our settings through the `Binder`, adds them to the `BootstrapContext` as `VaultProperties` by calling `registerIfAbsent`, and then delegates to the parent implementation of `resolveProfileSpecific`. The parent method attempts to register its own `VaultProperties` instance, but that slot is already occupied, so Vault uses our settings from that point onward.

This technique relies on `BootstrapContext`, a small object registry that exists from the very beginning of application startup until the `ApplicationContext` is created. A resolver uses it to pass clients and fully assembled settings to a loader.

The `registerIfAbsent` method does not replace an object when an object of the same type has already been registered, so our `VaultProperties` instance remains in the registry.

This technique did not work for KV engine settings. The Vault resolver does not obtain `VaultKeyValueBackendProperties` from the `BootstrapContext`; instead, it binds them from the `Binder` under the `spring.cloud.vault.kv` prefix every time. Fortunately, KV has relatively few settings, so we returned to placeholders, as we did with Config Server. The `spring.cloud.vault.kv.*` properties in `application.yml` refer to `axelix.master.external-config.spring-cloud-vault.kv.*`.

## How to See It for Yourself

Everything described above is visible in the logs. Enable `TRACE` for the Config Data package in `application.yml`, through a command-line argument, or with an environment variable:

```yaml
logging:
  level:
    org.springframework.boot.context.config: TRACE
```

The actual logging system is not yet running at this point, so Spring Boot buffers these messages and prints them a little later, after the configured logging levels have taken effect.

## Conclusion

We have examined how Spring Boot processes `spring.config.import`, how many passes it uses to load sources, which sources override which, and why `EnvironmentPostProcessor` cannot always influence loading. Keeping a few points in mind answers most questions:

1. All imports are processed at startup, before the `ApplicationContext` is created, over three passes — before profiles are determined and after.
2. A source's settings, such as a Vault address, can be stored in `application.yml` or in anything loaded before it, but not in something that will be loaded later.
3. Different sources run at different times. Some load immediately, while others wait for profiles.
4. An import is placed immediately above the file that declares it, so a profile-specific file can take precedence over a source imported by the base file.
5. `optional:` allows startup to continue when the specified configuration location is missing; it does not suppress every loading error. Provider-specific errors and fail-fast settings can still stop startup. If the application behaves unexpectedly, enable `TRACE` logging, inspect `/actuator/env`, or open [the **Environment** page in Axelix](https://axelix.io/docs/features/spring-framework/properties).

[Axelix is an open-source project](https://github.com/axelixlabs/axelix). The code discussed in this article is available on GitHub, and you can always inspect how the complete implementation works.

