/container-native-deployment

name: container-native-deployment
description: >
  Use when packaging a Spring Boot 3 application as an OCI image or GraalVM native executable.
  Covers buildpacks, layered images, JVM containers, AOT hints, probes, security, and verification.

Container and Native Deployment

Choose JVM or native from measured startup, memory, throughput, and build constraints.

Container image

• Prefer the Spring Boot build-image task with Cloud Native Buildpacks for standard services.
• Keep dependency and application layers separate to maximize cache reuse.
• Pin builder and run-image families in reproducible release pipelines.
• Run as a non-root user on a read-only filesystem where the application permits it.
• Supply secrets at runtime; never bake credentials or environment files into an image.
• Configure graceful shutdown and align platform termination grace with application timeouts.

Runtime behavior

• Set memory and CPU limits, then verify JVM ergonomics inside those limits.
• Expose dedicated readiness and liveness probes through Actuator.
• Keep startup probes for slow initialization instead of weakening liveness.
• Write temporary files only under an explicit writable location.

Native image

• Use Spring AOT and the supported GraalVM native build tools.
• Add `RuntimeHints` for reflection, resources, serialization, or proxies that analysis cannot infer.
• Avoid runtime bean-shape changes and other closed-world violations.
• Run native integration tests; a successful JVM test suite is not sufficient.

Supply chain

• Generate an SBOM, scan the final image, and patch builder/run images regularly.
• Use immutable image digests for promotion between environments.

Examples

• See `examples/good-dockerfile` and `examples/bad-dockerfile`.

The good example targets Boot 3.3+ and uses `jarmode=tools` extraction in a builder stage. For Boot 3.0-3.2, use the older `-Djarmode=layertools ... extract` command. A normal Maven package does not create `target/dependencies/` or `target/application/` directories by itself.

Official sources

• Container images: https://docs.spring.io/spring-boot/reference/packaging/container-images/
• Dockerfiles and layer extraction: https://docs.spring.io/spring-boot/reference/packaging/container-images/dockerfiles.html
• Boot 3.3 tools jarmode: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.3-Release-Notes#cds-support

Gotchas

• Agent copies one fat jar into a mutable root container - use layers and a non-root runtime.
• Agent bakes secrets into image layers - inject secrets only at runtime.
• Agent adds broad reflection configuration to make native builds pass - register narrow runtime hints.
• Agent uses liveness to test every dependency - use readiness for traffic-affecting dependencies.
• Agent chooses native without measuring throughput and build cost - benchmark both deployment modes.
• Agent copies nonexistent `target/dependencies` directories - extract the packaged jar in a builder stage.
• Agent uses `jarmode=tools` on Boot 3.0-3.2 - use `layertools` until the project reaches Boot 3.3.