Oracle Cloud Infrastructure Documentation

Amazon S3 Compatibility API

Using the Amazon S3 Compatibility API, customers can continue to use their existing Amazon S3 tools (for example, SDK clients) and partners can make minimal changes to their applications to work with Object Storage. The Amazon S3 Compatibility API and Object Storage datasets are congruent. If data is written to the Object Storage using the Amazon S3 Compatibility API, the data can be read back using the native Object Storage API and conversely.

Differences between the Object Storage API and the Amazon S3 Compatibility API

The Object Storage Service provided by Oracle Cloud Infrastructure and Amazon S3 use similar concepts and terminology. In both cases, data is stored as objects in buckets. The differences are in the implementation of features and tools for working with objects.

The following highlights the differences between the two storage technologies:

  • Compartments

    Although Amazon S3 doesn't use compartments, any buckets created using the Amazon S3 Compatibility API are created in the root compartment of the Oracle Cloud Infrastructure tenancy.

  • Global bucket namespace

    Object Storage doesn't use a global bucket namespace. Bucket names must be unique within the context of a namespace, but bucket names can be repeated across namespaces or across regions. Each tenant is associated with one default namespace that spans all compartments within a region.

  • Encryption

    The Oracle Cloud Infrastructure Object Storage service encrypts all data at rest by default. Encryption can't be turned on or off using the API.

  • Object Level Access Control Lists (ACLs)

    Oracle Cloud Infrastructure does not use ACLs for objects. Instead, IAM policies are used to manage access to compartments, buckets, and objects.

For more information, see Overview of the Object Storage service.

Amazon S3 Compatibility API Support

Amazon S3 Compatibility API support is provided at the bucket level and object level.

Bucket APIs

The following bucket APIs are supported:

Object APIs

The following object APIs are supported:

Tagging APIs

The following tagging APIs are supported:

Enabling Application Access to Object Storage

To enable application access from Amazon S3 to Object Storage, you need to set up access to Oracle Cloud Infrastructure and modify your application.

Setting up access to Oracle Cloud Infrastructure:

Modifying your application:

  • Configure a new endpoint for the application. For example: mynamespace.compat.objectstorage.us-phoenix-1.oraclecloud.com.

  • Set the target region as one of the Oracle Cloud Infrastructure regions.

    Note

    If you cannot set the target region name to the correct Oracle Cloud Infrastructure region name, you must either set the region to us-east-1 or leave it blank. Using this configuration, you can only use the Amazon S3 Compatibility API in your Oracle Cloud Infrastructure home region.

  • Configure the application to use the Amazon S3 Compatibility API key.
  • Ensure that you aren't using the virtual-hosted style URL, which is not supported.

At this point, you can start accessing Object Storage.

Supported Amazon S3 Clients

Qualified support is provided for the AWS SDK for Java client.

Here is an example of configuring the AWS SDK for Java (https://aws.amazon.com/documentation/sdk-for-java/) to talk to Object Storage's Amazon S3-compatible endpoints:

// Get S3 credentials from the console and put them here
AWSCredentialsProvider credentials = new AWSStaticCredentialsProvider(new BasicAWSCredentials(
"ocid1.credential.oc1..anEXAMPLE",
"anEXAMPLE="));

// The name of your tenancy
String tenancy = "tenancy";

// The region to connect to
String region = "us-ashburn-1";

// Create an S3 client pointing at the region
String endpoint = String.format("%s.compat.objectstorage.%s.oraclecloud.com",tenancy,region);
AwsClientBuilder.EndpointConfiguration endpointConfiguration = new AwsClientBuilder.EndpointConfiguration(endpoint, region);
AmazonS3 client = AmazonS3Client.builder()
.standard()
.withCredentials(credentials)
.withEndpointConfiguration(endpointConfiguration)
.disableChunkedEncoding()
.enablePathStyleAccess()
.build();

Amazon S3 Compatibility API Requirement

Before you can use the Amazon S3 Compatibility API, you must create an Amazon S3 Compatibility API key.

After you've generated the necessary key, you can use the Amazon S3 Compatibility API to access Object Storage in Oracle Cloud Infrastructure. For more information, see the API Reference.