Document how Map properties are bound from environment variables

Closes gh-40936

Author: mhalbritter

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/external-config.adoc

@@ -943,6 +943,24 @@ For example, the configuration property `my.service[0].other` would use an envir
 Support for binding from environment variables is applied to the `systemEnvironment` property source and to any additional property source whose name ends with `-systemEnvironment`.
 
 
+
+[[features.external-config.typesafe-configuration-properties.relaxed-binding.maps-from-environment-variables]]
+===== Binding Maps from environment variables
+
+When Spring Boot binds an environment variable to a property class, it lowercases the environment variable name before binding.
+Most of the time this detail isn't important, except when binding to `Map` properties.
+
+The keys in the `Map` are always in lowercase, as seen in the following example:
+
+include::code:MyMapsProperties[]
+
+When setting `MY_PROPS_VALUES_KEY=value`, the `values` `Map` contains a `{"key"="value"}` entry.
+
+Only the environment variable *name* is lower-cased, not the value.
+When setting `MY_PROPS_VALUES_KEY=VALUE`, the `values` `Map` contains a `{"key"="VALUE"}` entry.
+
+
+
 [[features.external-config.typesafe-configuration-properties.relaxed-binding.caching]]
 ===== Caching
 Relaxed binding uses a cache to improve performance. By default, this caching is only applied to immutable property sources.

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/logging.adoc

@@ -218,7 +218,7 @@ It is also possible to set logging levels using environment variables.
 For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springframework.web` to `DEBUG`.
 
 NOTE: The above approach will only work for package level logging.
-Since relaxed binding always converts environment variables to lowercase, it is not possible to configure logging for an individual class in this way.
+Since relaxed binding <<features#features.external-config.typesafe-configuration-properties.relaxed-binding.maps-from-environment-variables, always converts environment variables to lowercase>>, it is not possible to configure logging for an individual class in this way.
 If you need to configure logging for a class, you can use <<features#features.external-config.application-json, the `SPRING_APPLICATION_JSON`>> variable.
 
 

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc

@@ -43,6 +43,8 @@ When used to secure a client-side connection, a `truststore` is typically config
 
 See {spring-boot-autoconfigure-module-code}/ssl/JksSslBundleProperties.java[JksSslBundleProperties] for the full set of supported properties.
 
+NOTE: If you're using environment variables to configure the bundle, the name of the bundle is <<features#features.external-config.typesafe-configuration-properties.relaxed-binding.maps-from-environment-variables, always converted to lowercase>>.
+
 
 
 [[features.ssl.pem]]
@@ -106,6 +108,8 @@ The following example shows how a truststore certificate can be defined:
 
 See {spring-boot-autoconfigure-module-code}/ssl/PemSslBundleProperties.java[PemSslBundleProperties] for the full set of supported properties.
 
+NOTE: If you're using environment variables to configure the bundle, the name of the bundle is <<features#features.external-config.typesafe-configuration-properties.relaxed-binding.maps-from-environment-variables, always converted to lowercase>>.
+
 
 
 [[features.ssl.applying]]

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/externalconfig/typesafeconfigurationproperties/relaxedbinding/mapsfromenvironmentvariables/MyMapsProperties.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2012-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.features.externalconfig.typesafeconfigurationproperties.relaxedbinding.mapsfromenvironmentvariables;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = "my.props")
+public class MyMapsProperties {
+
+	private final Map<String, String> values = new HashMap<>();
+
+	public Map<String, String> getValues() {
+		return this.values;
+	}
+
+}

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/externalconfig/typesafeconfigurationproperties/relaxedbinding/mapsfromenvironmentvariables/MyMapsProperties.kt

@@ -0,0 +1,10 @@
+package org.springframework.boot.docs.features.externalconfig.typesafeconfigurationproperties.relaxedbinding.mapsfromenvironmentvariables
+
+import org.springframework.boot.context.properties.ConfigurationProperties
+
+@ConfigurationProperties(prefix = "my.props")
+class MyMapsProperties {
+
+	val values: Map<String, String> = HashMap()
+
+}