Document Buildpacks CDS and Spring AOT support

[sdeleuze]

trafficstars

As discussed with @philwebb today, it would be nice if Spring Boot 3.3 documentation could make CDS and Spring AOT Buildpacks support, which has just been deployed to production, more discoverable. The various configurations are now documented in https://github.com/paketo-buildpacks/spring-boot README, but from a Spring Boot POV my proposal would be to:

• Document that (at least) in the efficient deployment section
• Link the official CDS documentation
• Mention that CDS can be enabled via BP_JVM_CDS_ENABLED=true. In practice, that means Buildpacks will perform a training run, create a related .jsa file with the application classes cached, and use it by default when running the container.
• Document that CDS_TRAINING_JAVA_TOOL_OPTIONS can be used to fine tune the training run configuration (typical use case is to avoid early DB interactions, related documentation will be available in https://github.com/spring-projects/spring-lifecycle-smoke-tests, I plan to work on that).
• Mention that Spring AOT can also be enabled via BP_SPRING_AOT_ENABLED=true. That requires AOT processing upfront (already documented) and will enable the AOT mode when running the container.
• Link https://github.com/paketo-buildpacks/spring-boot for more details (especially about the BPL* configs we don't have to document on Spring Boot side).

If you do tests to ensure it works as expected, be aware that for now it is expected to work only on x86. aarch64 support should be fixed (when leveraging the beta multi arch support) before Spring Boot 3.3.0 release (ongoing related work is happening).

[anthonydahanne]

just a (arm64) note : spring-boot Maven and Gradle plugins use, by default,

• the builders named paketobuildpacks/builder-jammy-base:latest or paketobuildpacks/builder-jammy-tiny:latest when native is activated - none of them support dual arch (yet) ❌
• the (composite )buildpacks named paketobuildpacks/java:latest or, when native is enabled, paketobuildpacks/java-native-image:latest both of them are published as dual arch now ✅

To benefit from dual arch support, the users have to specify an alternative builder: paketobuildpacks/builder-jammy-buildpackless-tiny:latest which is dual arch - otherwise, the arm64 path is not complete and won't allow users to use Java buildpacks arm64 flavor.

Since this builder is buildpackless users have to manually specify the buildpacks they need.

Maven:

<plugin>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-maven-plugin</artifactId>
	<executions> <!-- not necessary for arm64, but better take good habits now-->
		<execution> 
			<id>process-aot</id>
			<goals>
				<goal>process-aot</goal>
			</goals>
		</execution>
	</executions>
	<configuration>
		<image>
			<env> <!-- not necessary for arm64, but better take good habits now-->
				<BP_JVM_CDS_ENABLED>true</BP_JVM_CDS_ENABLED>
				<BP_SPRING_AOT_ENABLED>true</BP_SPRING_AOT_ENABLED>
			</env>
			<buildpacks>
				<buildpack>paketobuildpacks/java</buildpack>
			</buildpacks>
			<builder>paketobuildpacks/builder-jammy-buildpackless-tiny</builder>
		</image>
	</configuration>
</plugin>

Gradle:

plugins {
[...]
	id("org.graalvm.buildtools.native") version "0.10.1" // not necessary for arm64, but better take good habits now
}
[...]
tasks.bootBuildImage {
	builder.set("paketobuildpacks/builder-jammy-buildpackless-tiny")
	buildpacks.add("gcr.io/paketo-buildpacks/java")
	environment.put("BP_SPRING_AOT_ENABLED","true") // not necessary for arm64, but better take good habits now
	environment.put("BP_JVM_CDS_ENABLED","true") // not necessary for arm64, but better take good habits now
}

There is no scheduled date when the default builders paketobuildpacks/builder-jammy-base:latest and paketobuildpacks/builder-jammy-tiny:latest will be published as dual arch(the best bet is to wait for the Ubuntu Noble based builders that will all be dual arch from day one and should arrive soon, but not for SB 3.3)

[sdeleuze]

I have began to document the configuration customizations required to avoid early DB interactions cc @christophstrobl:

• data-jpa
• data-jdbc
• data-r2dbc
• data-mongodb
• data-mongodb-reactive
• data-redis
• batch
• flyway
• liquibase

I am now working on adding CDS automated tests to https://github.com/spring-projects/spring-lifecycle-smoke-tests, so maybe the current CDS documentation can link https://github.com/spring-projects/spring-lifecycle-smoke-tests/blob/main/STATUS.adoc like what is done for CRaC.

[scottfrederick]

This is available at https://docs.spring.io/spring-boot/3.3-SNAPSHOT/how-to/class-data-sharing.html.

@sdeleuze I think we should add additional sections to this "How-to Guides" page with specific guidance on CDS-related customizations.

[sdeleuze]

@scottfrederick Indeed, should I submit a related PR?

[scottfrederick]

@sdeleuze Yes, please do.