Managing Object Storage Buckets

A bucket is a container for storing objects in a compartment within an Object Storage namespace.

A bucket is associated with a single compartment. The compartment has policies that indicate what actions you can perform on a bucket and all objects in the bucket.

A bucket cannot contain other buckets.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Listing Buckets

Using the Compute Web UI

1. In the navigation menu, under Object Storage, click Object Storage.

   A list of the buckets in the compartment you're viewing is displayed.

2. If you don’t see the bucket you're looking for, ensure that you’re viewing the correct compartment (select from the list at the top of the page).

   The page shows only the resources in that compartment.

Using the OCI CLI

1. Gather the information you need to run the command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Compartment OCID (oci iam compartment list)

2. Run this command.

   Syntax (entered on a single line):

   oci os bucket list 
   --namespace-name <object_storage_namespace>
   --compartment-id <compartment_OCID>

   Example:

   oci os bucket list  \
   --namespace-name examplenamespace  \
   --compartment-id ocid.compartment.….….….uniqueID
   
   {
     "data": [
       {
         "compartment-id": "ocid.compartment.….….….uniqueID",
         "created-by": "ocid1.user.….….….uniqueID",
         "defined-tags": null,
         "etag": "cdb5bc11561e476cb0d8aa5b8f8668f6",
         "freeform-tags": null,
         "name": "MyBucket",
         "namespace": "export/examplenamespace",
         "time-created": "2021-05-04T18:56:39+00:00"
       },
       {
         "compartment-id": "ocid.compartment.….….….uniqueID",
         "created-by": "ocid1.user.….….….uniqueID",
         "defined-tags": null,
         "etag": "aa7642fec45729ce7cb8b321d3ee1463",
         "freeform-tags": null,
         "name": "JoesBucket",
         "namespace": "export/examplenamespace",
         "time-created": "2021-05-04T20:26:33+00:00"
       }
     ]
   }

Viewing Bucket Details

Use this task to view bucket details.

Using the Compute Web UI

1. In the navigation menu, under Object Storage, click Object Storage.

   A list of the buckets in the compartment you are viewing is displayed.

2. From the list at the top of the page, select the compartment where the bucket resides.

3. Click the bucket name to display the details.

4. Click View or Copy.

Using the OCI CLI

1. Gather the information you need to run the command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Bucket name (oci os bucket list), see Listing Buckets

2. Run this command.

   Syntax (entered on a single line):

   oci os bucket get 
   --namespace-name <object_storage_namespace>
   --bucket-name <bucket_name>

   The OCID is identified as id in the output.

   Example:

   oci os bucket get  \
   --namespace-name examplenamespace  \
   --bucket-name MyBucket  
   
   {
     "data": {
       "approximate-count": null,
       "approximate-size": null,
       "compartment-id": "ocid.compartment.….….….uniqueID",
       "created-by": "ocid1.user.….….….uniqueID",
       "defined-tags": null,
       "etag": "cdb5bc11561e476cb0d8aa5b8f8668f6",
       "freeform-tags": null,
       "id": ocid.bucket.….….….uniqueID,
       "is-read-only": null,
       "kms-key-id": null,
       "metadata": null,
       "name": "MyBucket",
       "namespace": "export/examplenamespace",
       "object-events-enabled": null,
       "object-lifecycle-policy-etag": null,
       "public-access-type": "NoPublicAccess",
       "replication-enabled": null,
       "storage-tier": "Standard",
       "time-created": "2021-05-04T18:56:39+00:00",
       "versioning": null
     },
     "etag": "cdb5bc11561e476cb0d8aa5b8f8668f6"
   }

Creating a Bucket

Use this procedure to create an Object Storage bucket.

When you create a bucket, the bucket does not provide public access. To make the bucket publicly available, see Using Pre-Authenticated Requests.

Using the Compute Web UI

1. In the navigation menu, click Object Storage, then click Object Storage.

2. Click Create Bucket.

3. Enter the following details:

   • Name: Enter a name for the bucket.

     Specify a name that is unique within your tenancy Object Storage namespace.

   • Create in Compartment: Select the compartment in which to create this bucket.

   • Enable Object Versioning: Optionally, you can enable object versioning.

     For more information, refer to Managing Object Versioning.

   • Tagging: Optionally, add one or more tags to this resource.

     If you are not sure whether to apply tags, skip this option (you can apply tags later).

     For more information about tagging resources, see Working with Resource Tags.

4. Click Create Bucket.

   The bucket is created immediately and you can start uploading objects. See Uploading an Object.

Using the OCI CLI

1. Gather the information you need to run the next command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Compartment OCID (oci iam compartment list)

   • Bucket name: The name you want for this bucket.

2. Run this command.

   Syntax (entered on a single line):

   oci os bucket create
   --namespace-name <object_storage_namespace> 
   --compartment-id <compartment_OCID>
   --name <bucket_name>

   The bucket is created immediately and you can start uploading objects. See Uploading an Object.

   Example:

   oci os bucket create \
   --namespace-name examplenamespace  \
   --compartment-id ocid.compartment.….….….uniqueID    \
   --name MyBucket
   
   {
     "data": {
       "approximate-count": null,
       "approximate-size": null,
       "compartment-id": "ocid1.compartment.….….….uniqueID",
       "created-by": "ocid1.user.….….….uniqueID",
       "defined-tags": null,
       "etag": "b78d4193ab3eb2270b1373aa52b443a1",
       "freeform-tags": null,
       "id": null,
       "is-read-only": null,
       "kms-key-id": null,
       "metadata": null,
       "name": "MyBucket",
       "namespace": "export/examplenamespace",
       "object-events-enabled": null,
       "object-lifecycle-policy-etag": null,
       "public-access-type": "NoPublicAccess",
       "replication-enabled": null,
       "storage-tier": "Standard",
       "time-created": "2021-06-11T20:11:02+00:00",
       "versioning": null
     },
     "etag": "b78d4193ab3eb2270b1373aa52b443a1"
   }

Moving a Bucket to a Different Compartment

You can move a bucket from one compartment to another as long as both the source and target compartments are in the same tenancy. This capability includes moving a bucket from one compartment level down to a sublevel within the source compartment.

Using the OCI CLI

1. Gather the information you need for the next command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Compartment OCID of the compartment you are moving the bucket to (oci iam compartment list)

   • Bucket name (oci os bucket list), see Listing Buckets

2. Run this command to move the bucket.

   Syntax (entered on a single line):

   oci os bucket update
   --namespace-name <object_storage_namespace> 
   --compartment-id <target_compartment_id> 
   --bucket-name <bucket_name>

   Example:

   oci os bucket update \
   --namespace-name examplenamespace  \
   --compartment-id ocid1.compartment.….….….target-compartmentID   \
   --bucket-name MyBucket 
   {
     "data": {
       "approximate-count": null,
       "approximate-size": null,
       "compartment-id": "ocid1.compartment.….….….target-compartmentID",
       "created-by": "ocid1.user.….….….uniqueID",
       "defined-tags": null,
       "etag": "5d72fb7ac4385e24f42ac830bc6490ca",
       "freeform-tags": null,
       "id": null,
       "is-read-only": null,
       "kms-key-id": null,
       "metadata": null,
       "name": "MyBucket",
       "namespace": "export/examplenamespace",
       "object-events-enabled": null,
       "object-lifecycle-policy-etag": null,
       "public-access-type": "NoPublicAccess",
       "replication-enabled": null,
       "storage-tier": "Standard",
       "time-created": "2021-06-02T20:44:57+00:00",
       "versioning": null
     },
     "etag": "5d72fb7ac4385e24f42ac830bc6490ca"
   }

3. Run this command to verify that the bucket moved to the correct compartment:

   Syntax (entered on a single line):

   oci os bucket list 
   --namespace-name <object_storage_namespace>
   --compartment-id <target_compartment_OICD>
   

   Example:

   oci os bucket list  \
   --namespace-name examplenamespace  \
   --compartment-id ocid1.compartment.….….….target-compartmentID
   {
     "data": [
       {
         "compartment-id": "ocid1.compartment.….….….target-compartmentID",
         "created-by": "ocid1.user.….….….uniqueID",
         "defined-tags": null,
         "etag": "5d72fb7ac4385e24f42ac830bc6490ca",
         "freeform-tags": null,
         "name": "MyBucket",
         "namespace": "export/examplenamespace",
         "time-created": "2021-06-02T20:44:57+00:00"
       }

Deleting a Bucket

Caution:

You cannot recover a deleted bucket.

You can permanently delete an empty bucket. You cannot delete a bucket that contains any of the following:

• Any objects

• Previous versions of an object

• A multipart upload in progress

• A pre-authenticated request

Tip:

When you delete an object in a version-enabled bucket, a previous version of that object is created. Select Show Deleted Objects to display the object versions that might prevent you from deleting the bucket. For more information, see Managing Object Versioning.

Using the OCI CLI

1. Gather the information you need to run the command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Bucket name (oci os bucket list), see Listing Buckets

2. Run this command.

   Syntax (entered on a single line):

   oci os bucket delete
   --namespace-name <object_storage_namespace> 
   --bucket-name <bucket_name>

   Example:

   oci os bucket delete   \
   --namespace-name examplenamespace  \
   --bucket-name MyBucket
   Are you sure you want to delete this resource? [y/N]: y