Managing Buckets

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. The compartment has policies  that indicate what actions you can perform on a bucket and all the objects in the bucket.

You cannot nest buckets—a bucket cannot contain other buckets.

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  to work in.

If you are new to policies, see Getting Started with Policies and Common Policies.

For administrators:

Security Zones

Security Zones ensure that your cloud resources comply with Oracle security principles. If any operation on a resource in a security zone compartment violates a policy for that security zone, then the operation is denied.

The following security zone policies affect your ability to manage buckets:

  • You can't move a bucket from a security zone to a standard compartment because it might be less secure. For details, see Restrict Resource Movement.
  • Buckets in a security zone must be private.
  • Buckets in a security zone must use customer-managed master encryption keys in the Vault service.

Pre-Authenticated Requests

Pre-authenticated requests provide a way to let you access a bucket or an object without having your own credentials. For example, you can create a request that lets you upload backups to a bucket without owning API keys. See Using Pre-Authenticated Requests for details.

Object Versioning

You can enable object versioning to retain previous versions of objects. Object versioning lets you view, retrieve, and recover previous versions of objects and provides protection against accidental or malicious object overwrite or deletion. For information about this feature, see Using Object Versioning.

Object Lifecycle Policies

Using object lifecycle policies applied at the bucket level, you can automatically manage the archiving and deletion of objects according to a pre-defined schedule. For information about this feature, see Using Object Lifecycle Management.

Retention Rules

You can apply retention rules at the bucket level to provide immutable object storage options for data written to Object Storage for governance, regulatory compliance, and legal requirements. For information about this feature, see Using Retention Rules to Preserve Data.

Replication Policy

Using a replication policy for a bucket, you can automatically replicate the objects in one Object Storage bucket to another bucket in the same region or a different region. For information about this feature, see Using Replication.

Tagging Resources

You can add tags to your resources to help you organize them according to your business needs. You can add tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.

Object Storage currently supports adding tags to buckets.

Monitoring Resources

You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure resources by using metrics, alarms, and notifications. For more information, see Monitoring and Notifications Overview.

For information about monitoring buckets, see Object Storage Metrics.

Usage Reports

A usage report is a comma-separated value (CSV) file that can be used to get a detailed breakdown of resources in Oracle Cloud Infrastructure for audit or invoice reconciliation. A usage report is generated daily and stored in an Object Storage bucket. For more information, see Cost and Usage Reports Overview and Accessing Cost and Usage Reports.

Creating Automation for Buckets and Objects Using the Events Service

You can create automation based on state changes for your Oracle Cloud Infrastructure resources by using event types, rules, and actions. For more information, see Overview of Events.

Buckets emit events for bucket state changes by default. Events for objects are handled differently than other resources. Objects do not emit events by default. Use the Console, CLI, or API to enable a bucket to emit events for object state changes. You can enable events for object state changes during or after bucket creation.

Bucket Names

Bucket names are system generated by default, but you can overwrite the default with a name you specify.

System-Generated Bucket Names

When a bucket is created, the system generates a default name for that bucket, for example bucket-20190306-1359. This bucket name identifies the current year, month, and day that the bucket was created. You can use that system-generated name for your new bucket or you can specify a different name.

User-Specified Bucket Names

If you change this default bucket name or the name of any bucket, observe the following:

  • Make the name unique within your tenancy's Object Storage namespace.
  • Use from 1 to 256 characters.
  • Valid characters are letters (upper or lower case), numbers, hyphens, underscores, and periods.
    Important

    Bucket names and object names are case-sensitive. Object Storage handles accounts-payable and Accounts-Payable as separate buckets.
  • Avoid entering confidential information.

Default Storage Tiers

When you create a bucket, you decide which default storage tier is appropriate for storing the objects:

  • Use the Standard tier for data to which you need fast, immediate, and frequent access.
  • Use the Archive tier for data to which you seldom or rarely access, but that must be retained and preserved for long periods of time.

The storage tier property is then assigned to each object that you upload to a bucket.

For more information, see Understanding Storage Tiers. To automate the movement of data to the most cost effective tier, see Enabling Auto-Tiering.

Important

You cannot change the default storage tier of a bucket after creation.

Public Buckets

When you create a bucket, the bucket is considered a private bucket and the access to the bucket and bucket contents requires authentication and authorization. However, Object Storage supports anonymous, unauthenticated access to a bucket that is not in a security zone. You make a bucket public by enabling read access to the bucket.

Important

Carefully assess the business requirement for public access to a bucket. When you enable anonymous access to a bucket, any user can obtain object metadata, download bucket objects, and optionally list bucket contents. We recommend using pre-authenticated requests instead of public buckets. Pre-authenticated requests support more authorization, expiry, and scoping capabilities not possible with public buckets. See Using Pre-Authenticated Requests for details.

Required Permissions

The following permissions are required to configure a public bucket:

  • To enable public access when creating a bucket, use permission BUCKET_CREATE.
  • To enable public access for an existing bucket, use permission BUCKET_UPDATE.

Options

When creating a public bucket, you have the following options:

  • You can configure the access to allow listing and downloading objects. List and download access is the default.
  • You can configure the access to allow downloading objects only. A user would not be able to list bucket contents.

Scope and Constraints

Understand the following scope and constraints regarding public access:

  • Buckets in a security zone can't be public.
  • Changing the type of access is bi-directional. You can change a bucket's access from public to private or from private to public.
  • Changing the type of access doesn't affect existing pre-authenticated requests. Existing pre-authenticated requests still work.

You can enable anonymous public access for new or existing buckets using the Console, CLI, or an SDK to access the API.

Using the Console

To get a list of buckets

Open the navigation menu and click Storage. Under Object Storage, click Buckets.

A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

To create a bucket
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

  2. Select a compartment from the Compartment list on the left side of the page.

    A list of existing buckets is displayed.

  3. Click Create Bucket.
  4. In the Create Bucket dialog box, specify the attributes of the bucket:

    • Bucket Name: The system generates a default bucket name that reflects the current year, month, day, and time, for example bucket-20190306-1359. If you change this default to any other bucket name, use letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.
    • Default Storage Tier: Select the default tier in which you want to store your data. When you upload objects, the objects are automatically assigned to and uploaded to this tier by default. Available default storage tiers include:

      • Standard is the primary, default storage tier used for Object Storage service data. Use the Standard tier for storing data that requires fast and immediate access. Standard buckets do, however, provide an option to assign and upload objects to different storage tiers (Infrequent Access and Archive), while remaining in the Standard bucket.
      • Archive is the default storage tier used for Archive Storage service data. Use the Archive tier for storing data that does not require immediate access, but requires long retention periods. Access to data in the Archive tier is not immediate. Archived data must be restored before the data is accessible.

      See Understanding Storage Tiers for more information.

    • Select Enable Auto-Tiering if you want Object Storage to monitor and automatically move infrequently accessed objects from the Standard tier to the less expensive Infrequent Access storage tier. For more information, see Enabling Auto-Tiering.
    • Select Enable Object Versioning if you want Object Storage to create an object version each time the content changes or the object is deleted. For more information, see Using Object Versioning.
    • Select Emit Object Events if you want to enable the bucket to emit events for object state changes. For more information about events, see Overview of Events.
    • Encryption: Buckets are encrypted with keys managed by Oracle by default, but you can optionally encrypt the data in this bucket using your own Vault encryption key. To use Vault for your encryption needs, select Encrypt Using Customer-Managed Keys. Then, select the Vault Compartment and Vault that contain the master encryption key you want to use. Also select the Master Encryption Key Compartment and Master Encryption Key. For more information about encryption, see Overview of Vault. For details on how to create a vault, see Managing Vaults.
    • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.
  5. Click Create Bucket.

The bucket is created immediately and you can start uploading objects. Objects added to archive buckets are immediately archived and must be restored before they are available for download.

To view bucket details
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.

To change the visibility of a bucket

A bucket is either private (the default) or public. See Public Buckets for more information.

Important

You can't change the visibility of a bucket from private to public if that bucket is in a security zone.

We recommend using pre-authenticated requests instead of public buckets. Pre-authenticated requests support more authorization, expiry, and scoping capabilities not possible with public buckets. See Using Pre-Authenticated Requests for details.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Click the bucket name to see the bucket details.

    Visibility: shows the current bucket setting, which is Private by default.

  3. Click Edit Visibility.
  4. In the Edit Visibility dialog box, edit the visibility settings:

    • Visibility

      • Public
      • Private
    • If you select Public to enable public access, decide whether you want to let users list the bucket contents. To set the visibility of bucket object lists, click Allow users to list objects from this bucket .
  5. Click Save Changes.
To move a bucket to a different compartment
Important

You can't move a bucket from a security zone to a standard compartment. You also need to ensure that the resource users have sufficient access permissions for the compartment to which the resource is being moved.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. In the Scope section, select a compartment.
  3. Find the bucket in the list, click the Actions icon (three dots), and then click Move Resource.

    Alternatively, you can choose a bucket, and then click Move Resource on the bucket details page.

  4. Choose the destination compartment from the list.
  5. Click Move Resource.
To manage tags for a bucket
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Click the bucket name.
  3. You can manage tags in the following ways:

    • To view the tags associated with the bucket, click the Tags tab, located to the right of the Bucket Information tab.
    • To add one or more tags, click Add Tags.
    • To rename a tag, click the pencil icon to the left of a tag name, edit the name, and save.
    • To delete a tag, click the pencil icon to the left of a tag name and click Remove Tag.

For more information, see Resource Tags.

To delete a bucket
Caution

You cannot recover a deleted bucket.

You cannot delete a bucket that contains any of the following resources:

  • Objects and object versions
  • Pre-authenticated requests
  • Replication policy
  • Uncommitted multipart uploads

The Console collects and provides a count of each resource that would prevent bucket deletion. Upon your confirmation, the resources are deleted and the bucket is deleted in a single action.

Important

You can also cancel a deletion in progress. Understand, however, resources deleted before the cancellation cannot be recovered.
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Find the bucket that you want to delete.

  3. Click the Actions icon (three dots), and then click Delete.

    Alternatively, you can choose a bucket and click Delete on the bucket details page.

  4. Review the summary of resources that will be deleted.

  5. Type the name of the bucket to confirm resource and bucket deletion and click Delete.

    The deletion stops if you navigate away from the page or you close the browser. When possible, guidance is provided to help you investigate and resolve any errors before attempting the bucket deletion again.

To assign a Vault master encryption key to a bucket

Buckets are encrypted with keys managed by Oracle by default. Optionally, you can encrypt the data encryption keys that encrypt the objects in a bucket using your own Vault master encryption key.

Important

Buckets in a security zone can't use the default encryption key managed by Oracle. You must use your own Vault master encryption key.
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Click the name of the bucket that you want to encrypt.

  3. Next to Encryption Key, do one of the following:

    • If the bucket is encrypted with a key managed by Oracle, click the Assign link.
    • If the bucket already has a Vault master encryption key assigned, to assign a different key, click the Edit link.
  4. In the dialog box, provide or edit the following information:

    • Vault Compartment and Vault that contain the master encryption key you want to use. The current compartment is displayed by default.
    • Master Encryption Key Compartment and Master Encryption Key. The current compartment is displayed by default.
  5. When you are finished, click Assign or Edit.

See Overview of Vault for more details.

To remove a Vault master encryption key from a bucket
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Click the name of the bucket for which you want to remove a Vault key assignment.

  3. Next to Encryption Key, click the Unassign link.

  4. In the Confirm dialog box, click OK to remove the key assignment from the bucket.

To re-encrypt a bucket's data encryption keys

If you've rotated a master encryption key since the time you assigned it to a bucket, you might want to re-encrypt the bucket. Until you explicitly re-encrypt a bucket, the key version associated with the bucket when an object was inserted into the bucket continues to decrypt all data encryption keys. To encrypt and decrypt all data encryption keys with the same, most recent version of the assigned master encryption key, re-encrypt the bucket.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Click the name of the bucket for which you want to re-encrypt all data encryption keys.

  3. Click Re-encrypt. (If the button is not enabled, that's because the bucket is using a master encryption key managed by Oracle rather than a Vault master encryption. Or, the bucket does not contain any objects.)

  4. In the confirmation dialog box, click Re-encrypt to generate a work request to re-encrypt all data encryption keys associated with the bucket.

The Work Requests Details dialog box that displays tells you about the work request, including the percentage completed and the work request ID. You can copy the work request ID to monitor the request status later.

To enable or disable Auto-Tiering

You can enable or disable Auto-Tiering for any Standard storage tier bucket.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.
  4. Next to Auto-Tiering, click Edit.
  5. In the dialog box, select (to enable) or deselect (to disable) Enable Auto-Tiering.
  6. Click Save Changes.
To view the approximate bucket size and number of objects in the bucket
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.

    • Approximate Count is the approximate number of objects in the bucket. Count statistics are reported periodically. A lag can occur between what is displayed and the actual object count.
    • Approximate Size is the approximate total size of all objects in the bucket. Size statistics are reported periodically. A lag can occur between what is displayed and the actual size of the bucket.
To enable or disable emitting events for object state changes

You can create automation based on state changes for your Oracle Cloud Infrastructure resources by using event types, rules, and actions. For more information, see Overview of Events.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.
  4. Next to Emit Object Events, click Edit.
  5. In the dialog box, select (to enable) or deselect (to disable) Emit Object Events.
  6. Click Save Changes.
To enable or suspend object versioning

You can enable or suspend object versioning on any bucket.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.
  4. Next to Object Versioning, click Edit.
  5. In the dialog box, select Enable Versioning (if not yet enabled) or Suspend Versioning (if previously enabled).
To enable or disable virtual folders

Virtual folders is enabled by default. You can disable or re-enable virtual folders on any bucket.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.
  4. Next to Virtual Folders, click Edit.
  5. In the dialog box, select Enabled or Disabled.
  6. Click Save Changes.
To view or copy the Oracle Cloud Identifier (OCID) for a bucket
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment that contains your buckets.

    A list of buckets is displayed.

  3. Click the Actions icon (three dots) to the right of the bucket name, and then click View Bucket Details.

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.

Note

The examples in this section use the full syntax for all parameters, for example --namespace and --compartment-id. For some parameters, there are shortened versions that you can use instead, like -ns and -c. See the CLI online help for instances of a shortened parameter associated with a command.
To get a list of buckets
oci os bucket list --namespace <object_storage_namespace> --compartment-id <target_compartment_id>

For example:


oci os bucket list --namespace MyNamespace --compartment-id ocid.compartment.oc1..exampleuniqueID
					
{
  "data": [
    {
      "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
      "created-by": "ocid1.user.oc1..exampleuniqueID",
      "defined-tags": null,
      "etag": "c8889cd1-8414-41fb-84b7-3738c39e62c5",
      "freeform-tags": null,
      "name": "MyStandardBucket",
      "namespace": "MyNamespace",
      "time-created": "2020-05-22T19:22:25.032000+00:00"
    },
    {
      "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
      "created-by": "ocid1.user.oc1..exampleuniqueID",
      "defined-tags": null,
      "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
      "freeform-tags": null,
      "name": "MyArchiveBucket",
      "namespace": "MyNamespace",
      "time-created": "2020-06-22T13:04:05.879000+00:00"
    }
  ]
}				

By default, getting a list of buckets returns up to the first 1,000 buckets in the compartment.

Note

If you do not specify the --fields tags option when listing buckets, null is returned as the value for both free form and defined tags.

For example:

To include resource tag data, use the --fields tags option:

oci os bucket list --namespace <object_storage_namespace> --compartment-id <target_compartment_id> --fields tags

For example:


oci os bucket list --namespace MyNamespace --compartment-id ocid.compartment.oc1..exampleuniqueID --fields tags
					
{
  "data": [
	{
	  "compartment-id": "ocid1.compartment.oc1..exampleuniqueID",
	  "created-by": "ocid1.user.oc1..exampleuniqueID",
	  "defined-tags": {
		"example_tag_namespace_Financials": {
		  "production": "Unit 5"
		},
		"example_tag_namespace_Operations": {
		  "costcenter": "85"
		}		
	  },
	  "etag": "48af18cf-1edd-4b05-9f36-a629d5032260",
	  "freeform-tags": {
	    "Project": "prototype 3"
	  },
	  "name": "MyStandardBucket",
	  "namespace": "MyNamespace",
	  "time-created": "2020-05-27T18:52:16.951000+00:00"
	}
  ]
}				
To create a bucket

Creating a Standard default storage tier bucket

By default, a bucket is created in the Standard Object Storage tier. You do not need to explicitly set --storage-tier. Standard is the primary, default storage tier used for Object Storage service data. Use the Standard tier for storing data that requires fast and immediate access. Standard buckets do, however, provide an option to assign and upload objects to different storage tiers (Infrequent Access and Archive), while remaining in the Standard bucket.

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

For example:

oci os bucket create --namespace MyNamespace --name MyStandardBucket --compartment-id ocid.compartment.oc1..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}
You can also enable Auto-Tiering on a Standard bucket at creation time by specifying the optional --auto-tiering InfrequentAccess parameter. See Enabling Auto-Tiering for details. For example:
oci os bucket create --namespace MyNamespace --name MyStandardBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --auto-tiering Infrequent Access
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": "InfrequentAccess",
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}

A Standard tier bucket is created immediately and you can start uploading objects.

Creating an Archive default storage tier bucket

To create an Archive tier bucket, you must explicitly set --storage-tier Archive. Archive is the default storage tier used for Archive Storage service data. Use the Archive tier for storing data that does not require immediate access, but requires long retention periods. Access to data in the Archive tier is not immediate. Archived data must be restored before the data is accessible.

oci os bucket create --namespace <object_storage_namespace> --name <archivebucket_name> --compartment-id <target_compartment_id> --storage-tier Archive

For example:

oci os bucket create --namespace MyNamespace --name MyArchiveBucket --compartment-id ocid.compartment.oc1..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyArchiveBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Archive",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "c8889cd1-8414-41fb-84b7-3738c39e62c5"
}

An Archive Storage bucket is created and you can start uploading objects. Objects uploaded to Archive Storage buckets are immediately archived and must be restored before they are available for download.

To enable or disable Auto-Tiering
You can enable Auto-Tiering on a Standard during bucket creation or at a later time using the update action. See Enabling Auto-Tiering for details. For example:
oci os bucket update --namespace MyNamespace --name MyStandardBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --auto-tiering InfrequentAccess
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": "InfrequentAccess",
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}

You can also disable Auto-Tiering at any time using the update action. For example:

oci os bucket update --namespace MyNamespace --name MyStandardBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --auto-tiering Disabled
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": "Disabled",
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-12T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}
To create a public bucket that allows listing and downloading bucket objects

To create a public bucket that allows listing and downloading bucket objects, you must explicitly set --public-access-type ObjectRead.

oci os bucket create --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --public-access-type ObjectRead

For example:

oci os bucket create --namespace MyNamespace --name MyBucket --compartment-id ocid.compartment.oc1..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "01096e0b-659a-4d9d-a806-d57568cf1b22",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyPublicObjectReadBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectRead",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "01096e0b-659a-4d9d-a806-d57568cf1b22"
}
To create a public bucket that allows downloading bucket objects only
oci os bucket create --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --public-access-type ObjectReadWithoutList

For example:

oci os bucket create --namespace MyNamespace --name MyPublicObjectReadBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --public-access-type ObjectReadWithoutList{
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "ec20c59a-f5ba-4a6d-8a7e-b69bb9bb76ad",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyPublicObjectReadWithoutListBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectReadWithoutList",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T20:18:29.203000+00:00",
    "versioning": "Disabled"
  },
  "etag": "ec20c59a-f5ba-4a6d-8a7e-b69bb9bb76ad"
}
To create a bucket with resource tags

You can create standard Object Storage tier or Archive tier buckets with resource tags.

To add resource tags when creating a bucket, set one or both of the --defined-tags and --freeform-tags options.

Tip

The --defined-tags and --freeform-tags options require that the input to be a complex type formatted in valid JSON. See Passing Complex Input and Using a JSON File for Complex Input for information about JSON formatting.

The following example syntax creates a standard Object Storage tier bucket with a defined tag:

oci os bucket create --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --defined-tags '<JSON_formatted_defined_tag>'

Examples of defined tag formatting:

'{"Operations": {"CostCenter": "42"}'
'{"Logistics": {"Procurement": "Madrid Center"}},"Financials":{"Production": "Unit 5"}}'
Note

If you are running the CLI on a Windows computer, you might need to use the backslash (\) character to escape the strings containing the tag values. For example, a single defined tag is formatted '{\"Logistics\": {\"Procurement\": \"Madrid Center\"}}'

For example:

oci os bucket create --namespace MyNamespace --name MyBucketDefined --compartment-id ocid.compartment.oc1..exampleuniqueID --defined-tags {"Operations": {"CostCenter": "42"}}
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {
      "operations": {
        "costcenter": "42"				}
    },
    "etag": "ea88f444-842c-462d-965e-d3540b3b54f6",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucketDefined",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-23T19:47:51.362000+00:00",
    "versioning": "Disabled"
  },
  "etag": "ea88f444-842c-462d-965e-d3540b3b54f6"
}

The following example syntax creates a Standard tier bucket with a free-form tag:

oci os bucket create --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --freeform-tags <JSON_formatted_free-form_tag>

Examples of free-form tag formatting:

'{"Chicago_Team": "marketing_videos"}'
'{"Project": "prototype 3","Manager": "Meadows"}'
Note

If you are running the CLI on a Windows computer, you might need to use the backslash (\) character to escape the strings containing the tag values. For example, a single free-form tag is formatted as '{\"Chicago_Team\": {\"marketing_videos\"}}'

For example:

oci os bucket create --namespace MyNamespace --name MyBucketFreeform --compartment-id ocid.compartment.oc1..exampleuniqueID --freeform-tags {"Chicago_Team": "marketing_videos"}
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "6f4bda10-fc8b-462e-8563-875639fd7294",
    "freeform-tags": {
      "Chicago_Team": "marketing_videos"
    },
    "is-read-only": false,
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucketFreeform",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "storage-tier": "Standard",
    "time-created": "2020-06-23T20:51:16.260000+00:00"
  },
  "etag": "6f4bda10-fc8b-462e-8563-875639fd7294"
}
To view bucket details
oci os bucket get --name <bucket_name>
For example:
oci os bucket get --name MyBucket
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}
To add custom key-value metadata pairs to a bucket
oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --metadata <JSON-formatted_key-value_pair>

<JSON-formatted_key-value_pair> is a key-value pair input as valid formatted JSON. See Passing Complex Input and Using a JSON File for Complex Input for information about JSON formatting.

For example:

oci os bucket update --namespace MyNamespace --name MyBucket --metadata '{"Department": "Finance"}'
					
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "4b09d7b9-a8bf-42f6-8d67-bb357694f92d",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {
      "department": "Finance"
    },
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "4b09d7b9-a8bf-42f6-8d67-bb357694f92d"
}
To make a bucket private or public
oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --public-access-type [NoPublicAccess|ObjectReadWithoutList|ObjectRead]
  • NoPublicAccess: Allows only an authenticated caller to access the bucket and bucket contents. NoPublicAccess is the default value.
  • ObjectReadWithoutList: Allows public access for the GetObject, HeadObject, and ListObjects operations.
  • ObjectRead: Allows public access for the GetObject and HeadObject operations.
For example:
oci os bucket update --namespace MyNamespace --name MyBucket --public-access-type ObjectRead
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "09ab3193-a441-43cc-a8e2-e468e94c7c60",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {
      "department": "Finance"
    },
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectRead",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "09ab3193-a441-43cc-a8e2-e468e94c7c60"
}
To move a bucket to a different compartment
oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <new_target_compartment_id>

<new_target_compartment_id> is the compartment ID associated with the compartment to which you are moving the bucket.

For example:

oci os bucket update --namespace MyNamespace --name MyBucket --compartment-id ocid.compartment.oc1..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "new_ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "fe4fb648-8ddd-42eb-9732-d431aafac354",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {
      "department": "Finance"
    },
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "fe4fb648-8ddd-42eb-9732-d431aafac354"
}
To add resource tags to a bucket

To add defined resource tags to a bucket:

oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --defined-tags <JSON_formatted_defined_tag>

For example:

oci os bucket update --namespace MyNamespace --name MyBucket --defined-tags '{"Operations": {"CostCenter": "42"}}'
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
     "defined-tags": {
      "operations": {
        "costcenter": "42"
      }
    },
    "etag": "0a26b47d-c43f-4ef8-9c26-02bb8d69fa34",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {
      "department": "Finance"
    },
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "0a26b47d-c43f-4ef8-9c26-02bb8d69fa34"
}

To add free-form resource tags to a bucket:

oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --freeform-tags <JSON_formatted_free-form_tag>

For example:

oci os bucket update --namespace MyNamespace --name MyBucket --freeform-tags '{"Chicago_Team": "marketing_videos"}'
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {
      "operations": {
        "costcenter": "42"
      }
    },
    "etag": "856a3c73-0194-4c02-8c6b-1b20be3c9a48",
    "freeform-tags": {
      "Chicago_Team": "marketing_videos"
    },
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {
    "department": "Finance"
    },
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "856a3c73-0194-4c02-8c6b-1b20be3c9a48"
}
Tip

Provide key-value pair input for --defined-tags and --freeform-tags as valid formatted JSON. For examples of JSON-formatted resource tags, see To create a Standard or Archive tier bucket with resource tags. See Passing Complex Input and Using a JSON File for Complex Input for information about JSON formatting.
To delete a bucket
Caution

You cannot recover a deleted bucket.

You cannot delete a bucket that contains any of the following resources:

  • Objects and object versions
  • Pre-authenticated requests
  • Replication policy
  • Uncommitted multipart uploads
Tip

If you are deleting a bucket that contains one or more of these resources, consider using the Console to accomplish this task. The Console summarizes the count of each resource, deletes the resources that you have permission to delete, and then deletes the empty bucket in a single action. For details, To delete a bucket in Using the Console.
oci os bucket delete --namespace <object_storage_namespace> --name <bucket_name>

For example:

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

Select y and press Enter. The bucket is deleted with no further prompting.

To assign a Vault key to a bucket
oci os bucket create --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --kms-key-id <target_key_id>

<target_key_id> is the ID of the key versions that contain the cryptographic material used to encrypt and decrypt data, protecting the data where the data is stored.

For example:


oci os bucket create --namespace MyNamespace --name MyKeyBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --kms-key-id ocid1.key.region1.sea..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "e7f29fdd-b5f5-42e5-a98b-80883f9f2f32",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": "ocid1.key.region1.sea..exampleuniqueID",
    "metadata": {},
    "name": "MyKeyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess"
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-29T23:00:35.490000+00:00",
    "versioning": "Disabled"
  },
  "etag": "e7f29fdd-b5f5-42e5-a98b-80883f9f2f32"
}

See Overview of Vault for more details.

To update the Vault key assigned to a bucket
oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --kms-key-id <target_key_id>

<target_key_id> is the ID of the key versions that contain the cryptographic material used to encrypt and decrypt data, protecting the data where the data is stored.

For example:


oci os bucket update --namespace MyNamespace --name MyKeyBucket --kms-key-id ocid1.key.region1.sea.exampleuniqueID_updated
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "e7f29fdd-b5f5-42e5-a98b-80883f9f2f32",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": "ocid1.key.region1.sea..exampleuniqueID_updated",
    "metadata": {},
    "name": "MyKeyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-29T23:00:35.490000+00:00",
    "versioning": "Disabled"
  },
  "etag": "e7f29fdd-b5f5-42e5-a98b-80883f9f2f32"
}
To remove the Vault key assigned to a bucket
oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --kms-key-id ""

For example:


oci os bucket update --namespace MyNamespace --name MyKeyBucket --kms-key-id ""
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "10a50818-e495-45a9-b1ce-cc815f7b39ad",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyKeyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,					
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-29T23:00:35.490000+00:00",
    "versioning": "Disabled"
  },
  "etag": "10a50818-e495-45a9-b1ce-cc815f7b39ad"
}
To re-encrypt a bucket's data encryption keys

If you've rotated a master encryption key since the time you assigned it to a bucket, you might want to re-encrypt the bucket. Until you explicitly re-encrypt a bucket, the key version associated with the bucket when an object was inserted into the bucket continues to decrypt all data encryption keys. To encrypt and decrypt all data encryption keys with the same, most recent version of the assigned master encryption key, re-encrypt the bucket.

oci os bucket reencrypt --name <bucket_name>

For example:


oci os bucket reencrypt --name MyBucket
To view the approximate bucket size and number of objects in the bucket
oci os bucket get --name <bucket_name> --fields approximateCount --fields approximateSize
  • approximateCount is the approximate number of objects in the bucket. Count statistics are reported periodically. You might see a lag between what is displayed and the actual object count.
  • approximateSize is the approximate total size of all objects in the bucket. Size statistics are reported periodically. You might see a lag between what is displayed and the actual size of the bucket.
For example:
oci os bucket get --name MyBucket --fields approximateCount --fields approximateSize
{
  "data": {
    "approximate-count": 25,
    "approximate-size": 8075918,
    "auto-tiering": null,
    "compartment-id": "ocid1.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1:user:oc1:phx:1458751937789:exampleuniqueID",
    "defined-tags": {},
    "etag": "218f201f-28a4-434d-9591-f05b6223c67a",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2017-10-19T04:11:32.040000+00:00",
    "versioning": "Disabled"
  },
  "etag": "218f201f-28a4-434d-9591-f05b6223c67a"
}
To enable or disable emitting events for object state changes

You can create automation based on state changes for your Oracle Cloud Infrastructure resources by using event types, rules, and actions. For more information, see Overview of Events.

oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --object-events-enabled [true|false]

For example, to enable emitting events for all objects in the bucket named MyBucket:


oci os bucket update --namespace MyNamespace --name MyBucket --object-events-enabled true
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "auto-tiering": null,
    "compartment-id": "ocid1.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1:user:oc1:phx:1458751937789:exampleuniqueID",
    "defined-tags": {
      "operations": {
        "costcenter": "42"
      }
    },
    "etag": "39d1db02-27d0-4263-b3ff-5e6450495457",
    "freeform-tags": {
      "Chicago_Team": "marketing_videos"
    },
    "id": "ocid1.bucket.oc1..exampleuniqueID",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {
      "department": "Finance"
    },
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": true,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-06-22T19:04:05.879000+00:00",
    "versioning": "Disabled"
  },
  "etag": "39d1db02-27d0-4263-b3ff-5e6450495457"
}

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

When accessing the Object Storage API, the bucket name is used with the Object Storage namespace name to form the request URL:

n/<object_storage_namespace>/b/<bucket>

Use the following API operations to manage buckets:

Note

Two key properties are worthy of mention in the payload for CreateBucket and UpdateBucket APIs:

  • publicAccessType property controls whether the bucket is private or public and limits the capability to list public bucket contents.
  • objectEventsEnabled property controls if events are emitted for the objects in this bucket.