Spring Boot SSL bundle rotation: replace certificate files with a verified handoff

Name the trust boundary

A receipt API serves TLS using a named PEM bundle and points server.ssl.bundle to that name. The certificate and private key live in mounted files controlled by deployment tooling, not in a repository or tutorial example. A bundle can also describe client trust material, but server identity and outbound trust have different owners. Configuration precedence determines which file locations reach the process, and HTTP authorization remains necessary after a successful TLS handshake.

Rotate both halves safely

For a compatible embedded server, reload-on-update can notice changed PEM files and refresh its TLS connector. The deployment must publish a matching certificate and key without leaving a partial pair visible to the watcher. Do not assume every client or third-party component that consumes an SslBundle reloads itself; confirm the particular consumer. Retain an overlap window when clients cache trust material, and keep a rollback pair available if the new certificate fails validation.

Verify the handshake, not just startup

Start with one test certificate, connect as a client that validates the expected issuer and name, rotate the mounted pair, then make a new connection and inspect the served certificate. Existing connections may continue under the old handshake until they close; test the new connection explicitly. A file timestamp change or successful application log entry is not proof the connector accepted the new identity. Record expiry monitoring and a failed-rotation alarm before relying on unattended renewal.

Implementation contract

spring.ssl.bundle.pem.receipt-server.keystore.certificate=file:/run/receipt-tls/tls.crt
spring.ssl.bundle.pem.receipt-server.keystore.private-key=file:/run/receipt-tls/tls.key
spring.ssl.bundle.pem.receipt-server.reload-on-update=true
server.ssl.bundle=receipt-server

Cost and verification

A reload avoids a full process restart for compatible consumers, but file watching, controlled writes and handshake tests add deployment work. A failed pair can interrupt new TLS connections until rollback or correction.

Common Mistakes

• Do not store the private key in source control or print it during troubleshooting.
• Do not assume every SSL bundle consumer supports live reload.
• Do not declare rotation successful from a changed file without testing a fresh TLS handshake.

Read next

Spring Security filter chain: authentication, CSRF and request order, Spring Boot config source priority: a builder default may lose to a packaged file, Spring Actuator management port: separate listener, explicit access rule, Spring Boot readiness health group: withdraw traffic on a required dependency failure, Spring Boot graceful shutdown: finish accepted requests within a deadline.