3.0.0-M1

[maciejwalkowiak]

Spring Cloud AWS 3.0 is a rewrite of the project using AWS SDK v2 for Java. Since this has required a major refactoring, we took it as an opportunity to revisit all the assumptions and integrations modules. As a result, we've produced a library that is lightweight, flexible, causes less headache, provides simple to use abstractions and also works much better with Kotlin.

Only a subset of integrations have been migrated in M1:

• S3
• SES
• SNS
• Secrets Manager
• Parameter Store

We strongly recommend checking out completely rewritten reference documentation for a deep dive into each integration including code samples:

📗 https://docs.awspring.io/spring-cloud-aws/docs/3.0.0-M1/reference/html/index.html

Core

Dropped support for XML configuration and @EnableXXX annotations. Spring Cloud AWS can be used either with Spring Boot auto-configurations, or beans have to be created manually.

New properties prefix

All Spring Cloud AWS related properties have moved from cloud.aws to spring.cloud.aws prefix.

Endpoint configuration

Endpoint used by all integrations can be configured through a property:

spring.cloud.aws.endpoint=http://localhost:4566

Endpoint used by an individual integration can be also defined per integration:

spring.cloud.aws.s3.endpoint=http://localhost:4566

This is especially useful when Localstack is used instead of real AWS.

Credentials and region configuration

Credentials and region are resolved through the new interfaces from AWS SDK v2 for Java: software.amazon.awssdk.auth.credentials.AwsCredentialsProvider and software.amazon.awssdk.regions.providers.AwsRegionProvider.

It is possible to configure both through properties. In special cases, users can provide custom implementations of these interfaces to opt-out from ones that are auto-configured. Check the reference documentation for more details.

Nullability annotations

Every class field, method parameter and return value is annotated with @NonNull or @Nullable annotation, making it easier to use with null safe languages like Kotlin.

AWS Client Builder Configurers

AwsClientBuilderConfigurer simplifies applying same configuration for endpoint, region and credentials to user defined AWS clients beans:

import io.awspring.cloud.autoconfigure.core.AwsClientBuilderConfigurer;
...

@Bean
TextractClient textractClient(AwsClientBuilderConfigurer configurer) {
    return configurer.configure(TextractClient.builder()).build();
}

AWS Client Customizers

AwsClientCustomizer simplifies customizing AWS clients created by integrations without overwriting complete beans:

import io.awspring.cloud.autoconfigure.core.AwsClientCustomizer;
...

@Component
class S3AwsClientClientConfigurer implements AwsClientCustomizer<S3ClientBuilder> {
	@Override
	public ClientOverrideConfiguration overrideConfiguration() {
		...
	}

	@Override
	public SdkHttpClient httpClient() {
		...
	}
}

Note that AwsClientCustomizer is a parameterized type, and the type determines to which client customization gets applied.

S3

• all S3 related classes have moved to io.awspring.cloud.s3 package.
• SimpleStorageResource has been renamed to S3Resource
• S3 client can be configured with spring.cloud.aws.s3 properties
• dropped support for ResourcePatternResolver.

Cross-Region S3 client

S3Client implementation provided by Spring Cloud AWS can access buckets in any region. When accessed bucket is in other region than the one provided for S3 auto-configuration, the CrossRegionS3Clients handles redirects sent by S3 transparently.

Output Streams

S3 integration comes with three implementations of the OutputStream used under the hood by S3Resource for writing data to S3.

• InMemoryBufferingS3OutputStream (default) - buffers content of the uploaded file in memory and uploads to S3 using multipart upload
• DiskBufferingS3OutputStream - saves uploaded file to temporary folder on disk and uploads to S3 in single chunk
• TransferManagerS3OutputStream - uses experimental Transfer Manager to upload files to S3. Requires adding a dependency to software.amazon.awssdk:s3-transfer-manager

To use different output stream than one provided by auto-configuration, define a bean of type S3OutputStreamProvider - either with custom implementation or one of: DiskBufferingS3OutputStreamProvider, TransferManagerS3OutputStreamProvider, InMemoryBufferingS3OutputStreamProvider.

S3Template

S3Template is a new class that simplifies performing common operations on S3 buckets and S3 objects. It also supports reading and persisting Java objects to S3. Spring Cloud AWS provides Jackson based Jackson2JsonS3ObjectConverter which serialized persisted objects into JSON files. Custom object converted can be provided by defining a bean of type S3ObjectConverter.

Object Metadata Support

Both S3Resource and S3Template support setting object metadata through a builder-like object ObjectMetadata.

Content-Type Resolution

If uploaded file to S3 does not have contentType metadata property set, both S3Resource and S3Template will resolve content type through S3ObjectContentTypeResolver. The default implementation resolves content type by file extension. The framework provides a comprehensive support for 817 file extensions.

SES

SES integration does not bring any new features in comparison to what's offered in version 2.4.1.
SES integration can be configured using properties with spring.cloud.aws.ses prefix.

SNS

On top of what's been offered in 2.4.1, SNS integration provides a simple interfaces for sending notifications with custom payload and headers using SnsOperations#sendNotification method and SnsNotification object.

Because SNS Message Manager has not been migrated to AWS SDK v2, we had to drop support for message signature validation. We hope AWS finishes migration before Spring Cloud AWS reaches 3.0 GA.

SNS integration can be configured using properties with spring.cloud.aws.sns prefix.

Secrets Manager

• dropped support for loading properties from Secrets Manager using Spring Cloud Bootstrap - only loading through spring.config.import=aws-secretsmanager is now possible
• added support for loading both secrets containing JSON and plain text
• simplified using custom SecretsManagerClient

Secrets Manager integration can be configured using properties with spring.cloud.aws.secretsmanager prefix.

Parameter Store

• dropped support for loading properties from Parameter Store using Spring Cloud Bootstrap - only loading through spring.config.import=aws-parameterstore is now possible
• simplified using custom SsmClient

Parameter Store integration can be configured using properties with spring.cloud.aws.parameterstore prefix.

Reference Documentation

Reference documentation has been rewritten with simplicity and "straight to the point" attitude.

📗 https://docs.awspring.io/spring-cloud-aws/docs/3.0.0-M1/reference/html/index.html

Feedback

We are aware that this release breaks existing code but this was the only sensible way we could evolve the framework and meet the demand in constrained time we have. We are very open for your feedback and appreciate any shoutout on social media and Github ⭐️.

This release would not happen without our wonderful community. Big thanks for your bug reports, ideas and pull requests!

New Contributors

• @mcruzdev made their first contribution in Auto-configure region with InstanceProfileRegionProvider #76
• @zeldigas made their first contribution in Added scm section to spring-cloud-aws-dependencies module #310
• @anthonyfoulfoin made their first contribution in Allow plain text in AWS Secrets #338
• @willome made their first contribution in Exclude Slash from Encode, when calling getURL() on S3 Resource #353
• @anugrahsinghal made their first contribution in Gitpod mvnd #360
• @krimsz made their first contribution in Auto-configure S3 TransferManager. #361
• @sgarfinkel made their first contribution in Add InMemoryBufferingS3OutputStream #400

Full Changelog: v2.4.1...v3.0.0-M1

---

This discussion was created from the release 3.0.0-M1.