Introducing S3 cross-region support in the AWS SDK for Java 2.x

AWS SDK for Java team is excited to introduce the latest addition to the AWS SDK for Java 2.x: the Amazon Simple Storage Service (Amazon S3) Cross-Region Client feature. With this new feature, you can effortlessly access Amazon S3 buckets in different AWS Regions by using a single client configured for cross-region access. Join us as we explore the possibilities and convenience offered by this exciting enhancement.

Motivation

A common challenge when working with Amazon S3 buckets is the need to know the bucket’s region to interact with it. Users might not always have explicit knowledge of the bucket’s region, resulting in additional calls to determine the region. The new Amazon S3 Cross-Region client feature addresses this problem by enabling seamless access to S3 buckets across different regions. In this blog post, we explore the significance of this feature and how to use it to simplify cross-region S3 bucket access.

Getting Started

To begin, add the Amazon S3 dependency to your project for SDK versions 2.20.111 or higher:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.20.111</version>
</dependency>

By default, the cross-region feature is disabled. To enable it for an S3Client, set crossRegionAccessEnabled to true on the S3Client Builder:

S3AsyncClient client = S3AsyncClient.builder()
                                    .crossRegionAccessEnabled(true)
                                    .build();

Routing Requests to the Correct Region

When you reference an existing bucket in a request, such as with the ‘putObject’ request, the SDK initiates a request to the region configured for the client. If the bucket does not exist in that specific region, the error response includes the actual region where the bucket resides. Subsequently, the SDK makes the request to the correct region using the region information obtained from the error response. To optimize future requests to the same bucket, the SDK caches this region in the client.

Considerations for Enabling Cross-Region Bucket Access

When you enable cross-region bucket access, it’s important to keep in mind that the first API call may incur increased latency if the bucket is not in the client’s configured location. However, subsequent calls benefit from cached region information, resulting in improved performance. Please take note of the potential latency for the initial cross-region bucket access call and plan accordingly.

This feature does not affect access to the bucket; the user still needs to be authorized to access the bucket in whatever region it resides.

Conclusion

Cross-region bucket access simplifies the management of Amazon S3 buckets by allowing you to access a bucket without needing to know the bucket’s region in advance. It is important to understand the routing process, caching capabilities, and increased latency for the first API call to buckets in different Regions. The Amazon S3 Cross-Region Client feature, available in the AWS SDK for Java 2.0, provides a valuable functionality. We hope you’ll find this new feature useful. If you have any question, comments, concerns, or ideas, please open an issue or bug report on the GitHub issues page.

About the author:

AWS Developer Tools Blog