skip to content

How does multi-document YAML with the profile activation property work in a single application.yaml?

level: middleimportance: should knowfreq 55%

answer

  1. '---' separates YAML documents
  2. spring.config.activate.on-profile gates a document
  3. No key = always applied
  4. Later matching document wins
  5. Old key spring.profiles is deprecated

basics

~10 s

You split one YAML file into sections with '---'. Each section can be tagged with 'spring.config.activate.on-profile: prod' so its properties only apply when that profile is active. It keeps env-specific config in one file.

solid answer

~40 s

YAML supports multiple documents in one file separated by '---'. Spring Boot lets each document be conditionally activated using 'spring.config.activate.on-profile: <profile>' (Boot 2.4+; the old key was 'spring.profiles'). Documents without that key are always applied; documents with it apply only when the named profile is active. This lets you keep base config plus per-profile overrides in a single application.yaml instead of separate application-{profile}.yaml files. Documents are processed top-to-bottom, so a later matching document overrides an earlier one for the same key. You can also gate on other conditions via 'spring.config.activate.on-cloud-platform'. As with profile-specific files, you cannot set spring.profiles.active inside a profile-conditional document.

code

java · 19 lines
java
// single application.yaml, three documents
// ---- doc 1 (always) ----
// app:
//   name: katajob
//   cache-ttl: 60
// ---
// spring:
//   config:
//     activate:
//       on-profile: prod
// app:
//   cache-ttl: 3600   // overrides 60 only when prod active
// ---
// spring:
//   config:
//     activate:
//       on-profile: "!prod"   // expression grammar allowed
// app:
//   cache-ttl: 5

go deeper

for a junior

Knows '---' splits a YAML file and profiles can gate sections.

for a middle

Should know the on-profile key, that keyless docs always apply, and top-to-bottom override order.

for a senior

Knows the 2.4 key rename, expression grammar, on-cloud-platform, and the .properties '#---' equivalent.

for a principal

Chooses between single multi-document files and split profile files based on config size and team ownership.

### Multi-document YAML basics The YAML spec allows several **documents** in one physical file, separated by a line containing exactly `---`. Spring Boot treats each document as a separate unit of configuration that can be **conditionally activated**. ### Activating a document: `spring.config.activate.on-profile` Since Spring Boot **2.4**, the key is: ```yaml spring: config: activate: on-profile: prod ``` (The pre-2.4 key was `spring.profiles:` at the document root — now deprecated/removed.) A document carrying this key is applied **only** when the named profile is active. Documents **without** any activation key are applied **unconditionally** (they are your base/shared config). The `on-profile` value accepts the same expression grammar as `@Profile`: `dev | test`, `!prod`, `prod & eu`. ### Example ```yaml # base document — always applied server: port: 8080 --- spring: config: activate: on-profile: prod server: port: 80 --- spring: config: activate: on-profile: dev server: port: 8081 ``` With `prod` active the port is 80; with `dev` active it is 8081; with neither, 8080. ### Ordering and precedence Documents are processed **top to bottom**. If two active documents set the same key, the **later** document wins. So place more-specific overrides lower in the file. This mirrors how separate profile files layer, but within one file document order is the tie-breaker. ### Other activation conditions Besides `on-profile`, you can gate on `spring.config.activate.on-cloud-platform` (e.g. `kubernetes`) so a document applies only on a given platform. Multiple conditions in one document are AND-ed. ### Gotchas - **You cannot set `spring.profiles.active` inside a profile-activated document** — activation can only be declared where the document is unconditional (or use `spring.profiles.group`). - Mixing multi-document YAML *and* separate `application-{profile}.yaml` files is legal but can be confusing; pick one convention. - A stray blank document or misplaced `---` can silently create an empty document. Keep the separator on its own line. - In `.properties` files the equivalent is `#---` as a document separator (Boot 2.4+), with the same `spring.config.activate.on-profile` key. ### When to use Multi-document YAML shines for small apps or when you want *everything* visible in one file. Separate profile files scale better when per-environment config is large or owned by different teams.

  • What replaced the old 'spring.profiles:' document key in Boot 2.4?
    spring.config.activate.on-profile. The old spring.profiles key inside a document was deprecated and removed as part of the config-data overhaul.
  • If two active documents set the same property, which wins?
    The one that appears later in the file. Documents are processed top-to-bottom and later values override earlier ones.

saying these in an interview costs you the question

  • Using the removed spring.profiles: key instead of spring.config.activate.on-profile
  • Thinking earlier documents override later ones
  • Trying to set spring.profiles.active inside a conditional document

context

resolving links…