Document SSL support for Docker Compose and Testcontainers

Closes gh-41137

Author: mhalbritter

spring-boot-project/spring-boot-docs/build.gradle

@@ -78,6 +78,7 @@ dependencies {
 	implementation(project(path: ":spring-boot-project:spring-boot-testcontainers"))
 	implementation(project(path: ":spring-boot-project:spring-boot-devtools"))
 	implementation("ch.qos.logback:logback-classic")
+	implementation("com.redis:testcontainers-redis")
 	implementation("com.zaxxer:HikariCP")
 	implementation("io.micrometer:micrometer-jakarta9")
 	implementation("io.micrometer:micrometer-tracing")
@@ -170,6 +171,7 @@ dependencies {
 	implementation("org.testcontainers:junit-jupiter")
 	implementation("org.testcontainers:neo4j")
 	implementation("org.testcontainers:mongodb")
+	implementation("org.testcontainers:elasticsearch")
 	implementation("org.junit.jupiter:junit-jupiter")
 	implementation("org.yaml:snakeyaml")
 

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/dev-services.adoc

@@ -137,6 +137,92 @@ The following service connections are currently supported:
 
 
 
+[[features.dev-services.docker-compose.ssl]]
+=== SSL support
+
+Some images come with SSL enabled out of the box, or maybe you want to enable SSL for the container to mirror your production setup.
+Spring Boot supports SSL configuration for supported service connections.
+Please note that you still have to enable SSL on the service which is running inside the container yourself, this feature only configures SSL on the client side in your application.
+
+SSL is supported for the following service connections:
+
+* Cassandra
+* Couchbase
+* Elasticsearch
+* Kafka
+* MongoDB
+* RabbitMQ
+* Redis
+
+To enable SSL support for a service, you can use https://docs.docker.com/reference/compose-file/services/#labels[service labels].
+
+For JKS based keystores and truststores, you can use the following container labels:
+
+* `org.springframework.boot.sslbundle.jks.key.alias`
+* `org.springframework.boot.sslbundle.jks.key.password`
+* `org.springframework.boot.sslbundle.jks.options.ciphers`
+* `org.springframework.boot.sslbundle.jks.options.enabled-protocols`
+* `org.springframework.boot.sslbundle.jks.protocol`
+
+* `org.springframework.boot.sslbundle.jks.keystore.type`
+* `org.springframework.boot.sslbundle.jks.keystore.provider`
+* `org.springframework.boot.sslbundle.jks.keystore.location`
+* `org.springframework.boot.sslbundle.jks.keystore.password`
+
+* `org.springframework.boot.sslbundle.jks.truststore.type`
+* `org.springframework.boot.sslbundle.jks.truststore.provider`
+* `org.springframework.boot.sslbundle.jks.truststore.location`
+* `org.springframework.boot.sslbundle.jks.truststore.password`
+
+These labels mirror the properties available for xref:reference:features/ssl.adoc#features.ssl.jks[SSL bundles].
+
+For PEM based keystores and truststores, you can use the following container labels:
+
+* `org.springframework.boot.sslbundle.pem.key.alias`
+* `org.springframework.boot.sslbundle.pem.key.password`
+* `org.springframework.boot.sslbundle.pem.options.ciphers`
+* `org.springframework.boot.sslbundle.pem.options.enabled-protocols`
+* `org.springframework.boot.sslbundle.pem.protocol`
+
+* `org.springframework.boot.sslbundle.pem.keystore.type`
+* `org.springframework.boot.sslbundle.pem.keystore.certificate`
+* `org.springframework.boot.sslbundle.pem.keystore.private-key`
+* `org.springframework.boot.sslbundle.pem.keystore.private-key-password`
+
+* `org.springframework.boot.sslbundle.pem.truststore.type`
+* `org.springframework.boot.sslbundle.pem.truststore.certificate`
+* `org.springframework.boot.sslbundle.pem.truststore.private-key`
+* `org.springframework.boot.sslbundle.pem.truststore.private-key-password`
+
+These labels mirror the properties available for xref:reference:features/ssl.adoc#features.ssl.pem[SSL bundles].
+
+The following example enables SSL for a redis container:
+
+[source,yaml,]
+----
+services:
+  redis:
+    image: 'redis:latest'
+    ports:
+      - '6379'
+    secrets:
+      - ssl-ca
+      - ssl-key
+      - ssl-cert
+    command: 'redis-server --tls-port 6379 --port 0 --tls-cert-file /run/secrets/ssl-cert --tls-key-file /run/secrets/ssl-key --tls-ca-cert-file /run/secrets/ssl-ca'
+    labels:
+      - 'org.springframework.boot.sslbundle.pem.keystore.certificate=client.crt'
+      - 'org.springframework.boot.sslbundle.pem.keystore.private-key=client.key'
+      - 'org.springframework.boot.sslbundle.pem.truststore.certificate=ca.crt'
+secrets:
+  ssl-ca:
+    file: 'ca.crt'
+  ssl-key:
+    file: 'server.key'
+  ssl-cert:
+    file: 'server.crt'
+----
+
 [[features.dev-services.docker-compose.custom-images]]
 === Custom Images
 

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc

@@ -122,6 +122,36 @@ If you are using the Docker image `registry.mycompany.com/mirror/myredis`, you'd
 
 
 
+[[testing.testcontainers.service-connections.ssl]]
+=== SSL with Service Connections
+
+You can use the javadoc:org.springframework.boot.testcontainers.service.connection.Ssl[format=annotation], javadoc:org.springframework.boot.testcontainers.service.connection.JksKeyStore[format=annotation], javadoc:org.springframework.boot.testcontainers.service.connection.JksTrustStore[format=annotation], javadoc:org.springframework.boot.testcontainers.service.connection.PemKeyStore[format=annotation] and javadoc:org.springframework.boot.testcontainers.service.connection.PemTrustStore[format=annotation] annotations on a supported container to enable SSL support for that service connection.
+Please note that you still have to enable SSL on the service which is running inside the Testcontainer yourself, the annotations only configure SSL on the client side in your application.
+
+include-code::MyRedisWithSslIntegrationTests[]
+
+The above code uses the javadoc:org.springframework.boot.testcontainers.service.connection.PemKeyStore[format=annotation] annotation to load the client certificate and key into the keystore and the and javadoc:org.springframework.boot.testcontainers.service.connection.PemTrustStore[format=annotation] annotation to load the CA certificate into the truststore.
+This will authenticate the client against the server, and the CA certificate in the truststore makes sure that the server certificate is valid and trusted.
+
+The `SecureRedisContainer` in this example is a custom subclass of `RedisContainer` which copies certificates to the correct places and invokes `redis-server` with commandline parameters enabling SSL.
+
+The SSL annotations are supported for the following service connections:
+
+* Cassandra
+* Couchbase
+* Elasticsearch
+* Kafka
+* MongoDB
+* RabbitMQ
+* Redis
+
+The `ElasticsearchContainer` additionally supports automatic detection of server side SSL.
+To use this feature, annotate the container with javadoc:org.springframework.boot.testcontainers.service.connection.Ssl[format=annotation], as seen in the following example, and Spring Boot takes care of the client side SSL configuration for you:
+
+include-code::MyElasticsearchWithSslIntegrationTests[]
+
+
+
 [[testing.testcontainers.dynamic-properties]]
 == Dynamic Properties
 

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/serviceconnections/ssl/MyElasticsearchWithSslIntegrationTests.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2012-2025 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.testing.testcontainers.serviceconnections.ssl;
+
+import org.junit.jupiter.api.Test;
+import org.testcontainers.elasticsearch.ElasticsearchContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.data.elasticsearch.DataElasticsearchTest;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.boot.testcontainers.service.connection.Ssl;
+import org.springframework.data.elasticsearch.client.elc.ElasticsearchTemplate;
+
+@Testcontainers
+@DataElasticsearchTest
+class MyElasticsearchWithSslIntegrationTests {
+
+	@Ssl
+	@Container
+	@ServiceConnection
+	static ElasticsearchContainer elasticsearch = new ElasticsearchContainer(
+			"docker.elastic.co/elasticsearch/elasticsearch:8.17.2");
+
+	@Autowired
+	private ElasticsearchTemplate elasticsearchTemplate;
+
+	@Test
+	void testElasticsearch() {
+		// ...
+	}
+
+}

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/serviceconnections/ssl/MyRedisWithSslIntegrationTests.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2012-2025 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.testing.testcontainers.serviceconnections.ssl;
+
+import com.redis.testcontainers.RedisContainer;
+import org.junit.jupiter.api.Test;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.testcontainers.service.connection.PemKeyStore;
+import org.springframework.boot.testcontainers.service.connection.PemTrustStore;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.data.redis.core.RedisOperations;
+
+@Testcontainers
+@SpringBootTest
+class MyRedisWithSslIntegrationTests {
+
+	@Container
+	@ServiceConnection
+	@PemKeyStore(certificate = "classpath:client.crt", privateKey = "classpath:client.key")
+	@PemTrustStore("classpath:ca.crt")
+	static RedisContainer redis = new SecureRedisContainer("redis:latest");
+
+	@Autowired
+	private RedisOperations<Object, Object> operations;
+
+	@Test
+	void testRedis() {
+		// ...
+	}
+
+}

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/serviceconnections/ssl/SecureRedisContainer.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2012-2025 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.testing.testcontainers.serviceconnections.ssl;
+
+import com.redis.testcontainers.RedisContainer;
+
+class SecureRedisContainer extends RedisContainer {
+
+	SecureRedisContainer(String dockerImageName) {
+		super(dockerImageName);
+	}
+
+}