Profiles
A profile is a name for a situation the application runs in, such as dev, test, prod or eu. Activating a profile reads more config files and documents, and creates the beans meant for that situation. The rest of the setup stays shared.
Why
Environments often differ by more than one or two values: another database, a fake payment service in development, other URLs per region. Profiles group these differences under one name, chosen at launch, so the code never asks "am I in production?".
Example
# lib/resources/application.yml
shop:
payment: fake
url: http://localhost:8080
spring:
profiles:
group:
prod: [eu, monitoring] # prod also activates eu and monitoring
# lib/resources/application-prod.yml
shop:
payment: stripe
url: https://neon.books
# lib/resources/application-eu.yml
shop:
currency: EUR
dart run bin/main.dart --spring.profiles.active=prod
SPRING_PROFILES_ACTIVE=prod dart run bin/main.dart
flutter run --dart-define=SPRING_PROFILES_ACTIVE=prod
The start logs The following 3 profiles are active: "prod", "eu", "monitoring", and shop.payment is stripe.
// A bean that exists only with the prod profile.
@Service()
@Profile(['prod'])
class StripePayments implements Payments { ... }
Activating profiles
| Key | Type | Meaning |
|---|---|---|
spring.profiles.active |
comma list or YAML list | The active profiles. The first source that has the key wins, so the command line beats a file |
spring.profiles.include |
comma list or YAML list | Profiles added to the active ones, from every source |
spring.profiles.default |
comma list | The profiles used while none is active; default when not set |
spring.profiles.group.<name> |
list | Activating <name> activates these too. Groups can contain groups. <name> is matched exactly (group.Prod is no group of prod) |
spring.profiles.validate |
bool, default true |
Checks the names: letters, digits and -_.+@, starting and ending with a letter or digit |
In code:
SpringApplication(additionalProfiles: ['mobile'])activates profiles on every run, before the configured ones (so their files have the lowest precedence of the profile files).run(args, additionalProfiles: [...])adds profiles for one launch.springBootTest(profiles: ['test'])replacesspring.profiles.activein a test.
The order of activation: additionalProfiles first, then the profiles set in code, then spring.profiles.active, then include, each followed by its groups. With several active profiles, the files of the last one win.
Profile files
For each active profile, application-{profile}.yml (or .yaml, .properties) is read in every location, after the plain file, so its values win. While no profile is active, the default profile (or those of spring.profiles.default) picks the files: application-default.yml is read then.
An imported file has profile variants too: when application.yml imports local.yml, local-dev.yml is read with dev and wins over application-dev.yml. See Imports.
Documents for some profiles or platforms
Instead of a separate file, a document inside a file can be limited:
| Key | Meaning |
|---|---|
spring.config.activate.on-profile |
The document applies when this profile expression matches. A comma list means "any of". An empty value is no condition |
spring.config.activate.on-cloud-platform |
The document applies on this platform: kubernetes, heroku, cloud-foundry, azure-app-service, amazon-ecs, nomad, sap, or none (no platform) |
shop:
region: local
---
spring:
config:
activate:
on-profile: "prod & !us"
shop:
region: eu
---
spring:
config:
activate:
on-cloud-platform: kubernetes
shop:
region: cluster
shop.region=local
#---
spring.config.activate.on-profile=prod & !us
shop.region=eu
#---
spring.config.activate.on-cloud-platform=kubernetes
shop.region=cluster
The pre-2.4 key spring.profiles (as a document condition) is rejected; write spring.config.activate.on-profile.
Profile expressions
| Expression | Matches when |
|---|---|
prod |
prod is active |
!prod |
prod is not active |
prod & eu |
both are active |
prod | staging |
one of them is active |
prod & (eu | us) |
parentheses group; & and | cannot be mixed without them |
prod, staging |
a comma list: any of them |
The same expressions work in @Profile. Malformed expressions ((dev, a &, a b) fail the start with Malformed profile expression; Spring accepts some of them.
Cloud platforms
The platform is detected from environment variables, as Spring Boot does it:
| Platform | Detected when these are set |
|---|---|
kubernetes |
KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT |
heroku |
DYNO |
cloud-foundry |
VCAP_APPLICATION or VCAP_SERVICES |
azure-app-service |
WEBSITE_SITE_NAME, WEBSITE_INSTANCE_ID, WEBSITE_RESOURCE_GROUP and WEBSITE_SKU |
amazon-ecs |
ECS_CONTAINER_METADATA_URI or ECS_CONTAINER_METADATA_URI_V4 |
nomad |
NOMAD_ALLOC_ID |
sap |
HC_LANDSCAPE |
spring.main.cloud-platform forces a platform, or turns detection off with none. Beans use @ConditionalOnCloudPlatform (see Conditions). The list forms (on-cloud-platform[0]) are ignored, as in Spring Boot.
The rules that keep profiles stable
The profiles are decided before the profile files are read, as in Spring Boot, so those files cannot change them:
- A profile file (
application-dev.yml, orlocal-dev.ymlfor an importedlocal.yml) may not setspring.profiles.active,.defaultor.include; the start fails with anInvalidConfigDataPropertyException. Itsspring.profiles.group.*is ignored. - A document limited to a profile, in a file read before the profiles are decided (
application.ymland what it imports), may set none of the four keys; the start fails when the document applies. - In a file read after the profiles are decided (imported by a profile file or an
on-profiledocument), the four keys are ignored.
These keys are found under any spelling relaxed names allow: spring.profiles.Active in a profile file fails too.
Profiles in Flutter apps
With spring_boot_starter_flutter, the platform is a profile as well: android, ios, web, macos, windows or linux, plus mobile (Android, iOS) or desktop (macOS, Windows, Linux). The build mode is one too, after the platform: release, profile or debug. So application-ios.yml and application-release.yml are read with no setup:
# lib/resources/application-release.yml: a release logs only warnings
logging:
level:
root: warn
In Spring (Java)
The same keys, files and expressions as Spring Boot 2.4 and later. Differences:
spring.profiles.active,.defaultand.group.*in a document limited to a profile fail the start when the document applies, and are ignored when it does not (Spring Boot 4.1 reads them).- Placeholders in
on-profileare resolved once the profiles are decided, not at the first pass. - A profile group written as a list with a gap is read up to the gap instead of failing.
- Profile expressions are stricter.