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:

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:

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:

See also