# Container Native Deployment

> 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.

- Skill: `rrezartprebreza/container-native-deployment` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add rrezartprebreza/container-native-deployment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rrezartprebreza/container-native-deployment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: rrezartprebreza (https://skillmd.com/u/rrezartprebreza)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rrezartprebreza/container-native-deployment

---


# 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.