Spring Boot 2 to 3 Upgrade Program Playbook

Spring Boot 3 raises the Java baseline, moves from the javax to the jakarta namespace, and overhauls observability and security configuration. This program upgrades a fleet of Spring Boot 2 services in coordinated waves, treating the namespace move and dependency upgrades as the core risk to manage.

Phase-by-Phase

Prerequisite and Dependency Audit. Raise the Java baseline to the version Spring Boot 3 requires, audit every starter and third-party library for a compatible release, and confirm each service has a usable test suite. The audit makes the namespace move's blast radius concrete.

Jakarta Namespace Migration. Migrate javax imports to jakarta across the codebase, update libraries that have not yet moved, and fix renamed or relocated configuration properties. Pre-commit hooks and CI prevent javax from creeping back in.

Observability and Security Updates. Adopt the Micrometer Observation API and OpenTelemetry-aligned tracing that replaced the older approach, migrate the rewritten security configuration, and validate Actuator endpoint changes. These are behavioral changes, not just imports.

Validation and Rollout. Run full regression, canary each service through deployment rings, and decommission Spring Boot 2. SLOs define what a healthy upgraded service looks like.

Team and Roles

An architect owns the upgrade order and observability migration strategy. Backend engineers do the namespace and config work. DevOps owns CI and base images; SRE owns canary rollout and tracing validation. QA gates each wave with regression.

Risks and Mitigations

The javax-to-jakarta move breaks anything referencing the old namespace, including reflective and library code; the audit plus automated migration tooling and CI guards contain it. Library incompatibility is resolved before code changes pile up. Security configuration changed substantially between versions and is validated explicitly. Coordinate shared-library waves so apps upgrade against a stable base.

Success Criteria

Success is full Spring Boot version compliance, steady deployment frequency, strong MTTR, and maintained test coverage through the rollout.

Tooling

Use automated namespace-migration tooling, a Git-driven CI pipeline, pre-commit hooks, hardened Docker base images, and canary deployment on Kubernetes. PostgreSQL or the existing relational store remains the data backend.