Spring Boot buildpack image: separate build settings from deployed secrets

Two configuration moments

The receipt service image build chooses a JVM version and builder policy. The running container later receives a database address, credentials and pool limits for its deployment. Passing a secret as a build setting risks leaving it in build logs, layers or cached metadata. Treat the image as the reusable artifact and keep deployment-specific values outside it. Config-tree binding] can read a mounted secret at runtime.

Pin the artifact

Record the builder image, run image, JDK version and resulting image digest with each release. A mutable tag may change the base image without a source change. Spring Boot’s image task delegates to buildpacks, so an application property does not set a buildpack parameter, and a buildpack JVM setting does not replace a Spring property at runtime. Layered jar behavior] affects how unchanged bytes may be reused.

Test both environments

Build the image with a controlled JVM version, then run that exact digest with a disposable database and injected runtime configuration. Assert the process starts and binds a known non-secret property. Rebuild after changing only a runtime value: the image digest should remain the same because no rebuild is needed. A deployment test should also confirm missing credentials fail before accepting traffic.

Implementation contract

tasks.named<BootBuildImage>("bootBuildImage") {
    environment.put("BP_JVM_VERSION", "21")
}
// Supply receipt database credentials when the image is run, not here.

Cost and verification

Building images consumes CPU, network and registry storage. Keeping runtime configuration out of the image permits one digest to serve several environments and avoids needless rebuilds.

Common Mistakes

• Do not place database passwords in buildpack environment settings.
• Do not assume a mutable builder tag reproduces the same image later.
• Do not rebuild an image just to change one runtime property.

Read next

Spring Boot layered jar: keep dependency changes out of the application layer, Spring Boot configtree: bind one file per property in a child JVM, Spring Boot config validation: separate valid syntax from a safe relay setting, Spring Boot executable jar: load resources through the classpath, not a file path, Spring Boot configuration validation: reject an unusable relay before work starts.

Related Boot contract

Spring Boot executable jar: load resources through the classpath, not a file path.