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  you should 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 recovery 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.

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.
  • Do not include confidential information.

Storage Tiers

When you create a bucket, you also decide which tier is appropriate for storing objects:

  • Use the standard Object Storage tier for data to which you need fast, immediate, and frequent access. For more information, see Overview of Object Storage.
  • Use the Archive Storage tier for data to which you seldom or rarely access, but that must be retained and preserved for long periods of time. For more information, see Overview of Archive Storage.
Important

You cannot change the storage tier in which a bucket resides.

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.

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. Under Core Infrastructure, click Object Storage.

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. Under Core Infrastructure, click Object Storage.

    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. 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.
    • Storage Tier: Select the tier in which you want to store your data. Available tiers include:

      • Standard is the primary, default Object Storage tier for storing frequently accessed data that requires fast and immediate access.
      • Archive is a special tier for storing infrequently accessed data that requires long retention periods. Access to data in the Archive tier is not immediate. Archived data must be restored before the data is accessible. For more information, see Overview of Archive Storage.
    • Object Events: 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.
    • Object Versioning: 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.
    • 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 if you should apply tags, then 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. Under Core Infrastructure, click Object Storage.
  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.
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.

    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 or not you want to let users list the bucket contents. Click Allow users to list objects from this bucket to set the visibility of bucket object lists.
  5. Click Save Changes.
To move a bucket to a different compartment
Important

When moving bucket resources between compartments, ensure that the resource users have sufficient access permissions for the compartment to which the resource is being moved.

You can't move a bucket from a security zone to a standard compartment.

  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. In the Scope section, select a compartment.
  3. Find the bucket in the list, click the 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. Under Core Infrastructure, click Object Storage.

    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 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 Using Object Versioning.
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.

    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, click More Actions on the bucket details page, and then click Delete.

  4. Confirm deletion when prompted.

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. Under Core Infrastructure, click Object Storage.

    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. Under Core Infrastructure, click Object Storage.

    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. Under Core Infrastructure, click Object Storage.

    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 view the approximate bucket size and number of objects in the bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  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. Under Core Infrastructure, click Object Storage.
  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 view or copy the Oracle Cloud Identifier (OCID) for a bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  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": "MyBucket1",
      "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": "MyBucket2",
      "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 freeform 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": "MyBucket",
	  "namespace": "MyNamespace",
	  "time-created": "2020-05-27T18:52:16.951000+00:00"
	}
  ]
}				
To create a standard Object Storage tier 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 MyBucket --compartment-id ocid.compartment.oc1..exampleuniqueID
{
  "data": {
    "approximate-count": null,
    "approximate-size": 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-05-27T18:52:16.951000+00:00",
    "versioning": "Disabled"
  },
  "etag": "7b7c3dc1-713f-4996-b176-a938345cae8e"
}

By default, a bucket is created in the standard Object Storage tier. You do not need to explicitly set --storage-tier.

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

To create an Archive tier bucket

To create an Archive tier bucket, you must explicitly set --storage-tier Archive.

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,
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "created-by": "ocid1.user.oc1..exampleuniqueID",
    "defined-tags": {},
    "etag": "c8889cd1-8414-41fb-84b7-3738c39e62c5",
    "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-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 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,
    "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,
    "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,
    "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,
    "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,
    "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,
    "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,
    "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,
    "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,
    "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 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
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,
    "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,
    "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,
    "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,
    "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 example_namespace --name MyBucket --object-events-enabled true
{
  "data": {
    "approximate-count": null,
    "approximate-size": 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.