From ef7d7487fa9ab8de2f549b0df5cf447f4ebbf7a0 Mon Sep 17 00:00:00 2001 From: Madhura Bhave Date: Tue, 8 Mar 2022 21:58:43 -0800 Subject: [PATCH] Document when config data properties are invalid This commit also reinstates documentation for `spring.profiles.include` Closes gh-25849 Closes gh-28451 --- .../src/docs/asciidoc/features/profiles.adoc | 39 ++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/profiles.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/profiles.adoc index 55ee0caa3a..3602354de6 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/profiles.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/profiles.adoc @@ -34,6 +34,27 @@ The name of the default profile is `default` and it can be tuned using the confi default: "none" ---- +`spring.profiles.active` and `spring.profiles.default` can only be used in non-profile specific documents. +This means they cannot be included in <> or <> by `spring.config.activate.on-profile`. + +For example, the second document configuration is invalid: + +[source,yaml,indent=0,subs="verbatim",configprops,configblocks] +---- + # this document is valid + spring: + profiles: + active: "prod" + --- + # this document is invalid + spring: + config: + activate: + on-profile: "prod" + profiles: + active: "metrics" +---- + [[features.profiles.adding-active-profiles]] @@ -42,8 +63,24 @@ The configprop:spring.profiles.active[] property follows the same ordering rules This means that you can specify active profiles in `application.properties` and then *replace* them by using the command line switch. Sometimes, it is useful to have properties that *add* to the active profiles rather than replace them. -The `SpringApplication` entry point has a Java API for setting additional profiles (that is, on top of those activated by the configprop:spring.profiles.active[] property). +The `spring.profiles.include` property can be used to add active profiles on top of those activated by the configprop:spring.profiles.active[] property. +The `SpringApplication` entry point also has a Java API for setting additional profiles. See the `setAdditionalProfiles()` method in {spring-boot-module-api}/SpringApplication.html[SpringApplication]. + +For example, when an application with the following properties is run, the common and local profiles will be activated even when it runs using the --spring.profiles.active switch: + +[source,yaml,indent=0,subs="verbatim",configprops,configblocks] +---- + spring: + profiles: + include: + - "common" + - "local" +---- + +WARNING: Similar to `spring.profiles.active`, `spring.profiles.include` can only be used in non-profile specific documents. +This means it cannot be included in <> or <> by `spring.config.activate.on-profile`. + Profile groups, which are described in the <> can also be used to add active profiles if a given profile is active.