Spring Boot S3 Workshop
Latest stable Based on AWS release 0.4.0
A runnable workshop grounded in the 0.4.0 release source.
Learning goal
Section titled “Learning goal”Expose S3 object operations through a small Spring Boot WebFlux controller while auto-configured operations own SDK details. The workshop adds listing, deletion, presigning, and optional client-side encryption to a basic upload/download path.
When to use this workshop
Section titled “When to use this workshop”Use it when a Spring service needs S3 templates, presigned URLs, or envelope encryption and must understand which SDK modules and beans activate each feature.
Project coordinates
Section titled “Project coordinates”This example is not published. Run ./gradlew :aws-spring-boot-s3-examples:test. Applications import the central BOM, bluetape4k-aws-spring-boot, and software.amazon.awssdk:s3; encrypted routes also need KMS support.
Concepts to learn
Section titled “Concepts to learn”S3DocumentController delegates to S3Operations/S3CoroutinesTemplate. Optional S3ClientSideEncryptionOperations stores encrypted data with envelope metadata. Auto-configuration creates and closes service clients.
Staged walkthrough
Section titled “Staged walkthrough”- Upload and download one object.
- List by prefix and delete the object.
- Generate presigned GET and PUT URLs and inspect their expiry.
- Enable the encrypted route with a deterministic test KMS implementation.
- Run AOT tasks after changing configuration or controller types.
Entry points and expected behavior
Section titled “Entry points and expected behavior”SpringBootS3ExampleApplication starts the service and S3DocumentController exposes /s3/documents. It supports plain/encrypted upload and download, object listing, presigned URLs, and delete.
Recommended exercise order
Section titled “Recommended exercise order”Keep bucket/key validation at the HTTP boundary and stream payloads when size is unbounded. Separate object naming, retention, encryption context, and authorization from the transport helper.
Integration boundary
Section titled “Integration boundary”Spring creates the S3 client, presigner, templates, and optional encryption operations when their classes and properties are present. The controller does not own or close them.
Configuration checkpoints
Section titled “Configuration checkpoints”Set region and optional endpoint override/path-style access for emulators. Configure presign duration. Encryption needs a key ID, stable encryption context, KmsOperations, and the AWS KMS runtime module.
Failure modes
Section titled “Failure modes”Missing bucket, wrong addressing style, expired presigned URL, partial upload, absent KMS bean, mismatched encryption context, and oversized buffering are likely failures.
Operations
Section titled “Operations”Measure latency, bytes, failures, retries, and presign counts without logging object content or signed query strings. Define multipart, retention, versioning, and partial-failure policy outside the controller.
Testing the boundary
Section titled “Testing the boundary”S3DocumentControllerLocalStackTest selects the emulator, creates a bucket, and verifies upload, download, listing, presigned URLs, delete, and encryption using a deterministic KMS test double.
Next learning path
Section titled “Next learning path”Compare the Ktor S3 workshop for direct SigV4 HTTP behavior, then add service-specific IAM, large-object transfer, and real KMS smoke tests.
Limitations
Section titled “Limitations”The deterministic KMS helper does not prove AWS KMS permissions or ciphertext behavior. The example does not benchmark large transfers, multipart recovery, versioned deletion, or bucket policy.
Release diagrams
Section titled “Release diagrams”These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.
aws spring boot s3 examples Architecture diagram
Section titled “aws spring boot s3 examples Architecture diagram”
Release README: examples/aws-spring-boot-s3-examples/README.md