Designating Compartments for the Amazon S3 Compatibility and Swift APIs

In the Oracle Cloud Infrastructure Object Storage service, a bucket is a container for storing objects in a compartment  within an Object Storage namespace. A bucket is associated with a single compartment and data is stored as objects in buckets.

In addition to the native Object Storage APIs, Object Storage provides API support for both Amazon S3 Compatibility API and Swift API. However these APIs do not understand the Oracle Cloud Infrastructure concept of a compartment. By default, buckets created using the Amazon S3 Compatibility API or the Swift API are created in the root compartment of the Oracle Cloud Infrastructure tenancy. Instead, you can designate a different compartment for the Amazon S3 Compatibility API or Swift API to create buckets in.

When you designate a different compartment to use for the Amazon S3 Compatibility API or Swift API, any new buckets you create using the Amazon S3 Compatibility API or the Swift API are created in this newly designated compartment. Buckets previously created in a different compartment are not automatically moved to the newly designated compartment. See Managing Buckets if you want to move previously created buckets to this newly designated compartment.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  you should work in.

Compartments have policies  that indicate what actions a user can perform on a bucket and all the objects in the bucket.

For administrators:

  • To change the default compartments for Amazon S3 Compatibility API and Swift API, a user must belong to a group with NAMESPACE_UPDATE permissions.
  • To see the current default compartments for Amazon S3 Compatibility API and Swift API, a user must belong to a group with NAMESPACE_READ permissions.
  • To move a bucket to a different compartment, a user must belong to a group with BUCKET_UPDATE and BUCKET_CREATE permissions in the source compartment, and BUCKET_CREATE permissions in the target compartment.

If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for buckets and objects, see Details for Object Storage, Archive Storage, and Data Transfer.

Viewing and Specifying Designated Compartments

You can view the current default compartment designations for Amazon S3 Compatibility API and Swift API data. If your permissions allow, you can also change the Amazon S3 Compatibility API and Swift API compartment designations.

Designated compartment names:

  • Must be unique across all the compartments in your tenancy.
  • Can be from 1 to 100 characters in length.
  • Must not contain confidential information.
  • Valid are letters (upper or lower case), numbers, hyphens, and underscore.

Using the Console

To view your Amazon S3 Compatibility API and Swift API compartment designations

Open the Profile menu (User menu icon) and click Tenancy: <your_tenancy_name>.

Your default compartment designations for the APIs are listed under Object Storage Settings.

To edit your tenancy's Amazon S3 Compatibility API and Swift API compartment designations
  1. Open the Profile menu (User menu icon) and click Tenancy: <your_tenancy_name>.

  2. Click Edit Object Storage Settings.
  3. In the Edit Object Storage Settings dialog:

    • Select the compartment that you want for the Amazon S3 Compatibility API Designated Compartment.
    • Select the compartment that you want for the Swift API Designated Compartment.
  4. Click Save.

    The new Object Storage Settings are displayed.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To get your tenancy's Amazon S3 Compatibility API and Swift API compartment designations

Use this CLI command to display metadata associated with the Amazon S3 and Swift compartments for the specified namespace in your tenancy.

oci os ns get-metadata --namespace <object_storage_namespace>

For example:

oci os ns get-metadata --namespace MyNamespace
{
    "data": {
    "default-s3-compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "default-swift-compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "namespace": "MyNamespace"
    }
}							
To update your tenancy's Amazon S3 Compatibility API compartment designation

Use this CLI command to specify the default Amazon S3 compartment for the specified namespace in your tenancy.

oci os ns update-metadata --namespace <object_storage_namespace> --default-s3-compartment-id <your_oci_compartment_id>

<your_oci_compartment_id> specifies a compartment that is not the root compartment of your tenancy.

For example:

oci os ns update-metadata --namespace MyNamespace --default-s3-compartment-id ocid.compartment.oc1..exampleuniqueID
{
    "data": {
    "default-s3-compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "default-swift-compartment-id": null,
	"namespace": null
    }
}				
To update your tenancy's Swift API compartment designations

Use this CLI command to specify the default Swift compartment for the specified namespace in your tenancy.

oci os ns update-metadata --namespace <object_storage_namespace> --default-swift-compartment-id <your_oci_compartment_id>

<your_oci_compartment_id> specifies a compartment that is not the root compartment of your tenancy.

For example:

oci os ns update-metadata --namespace MyNamespace --default-swift-compartment-id ocid.compartment.oc1..exampleuniqueID
{
    "data": {
    "default-s3-compartment-id": null,
    "default-swift-compartment-id": "ocid.compartment.oc1..exampleuniqueID",
	"namespace": null
    }
}