Oracle Cloud Infrastructure Documentation

Managing Buckets

In the Oracle Cloud Infrastructure Object Storage service, a bucket is a container for storing objects in a A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. within an Object Storage namespace. A bucket is associated with a single compartment. The compartment has An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. that indicate what actions a user 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 given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. you should work in.

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

For administrators:

Pre-Authenticated Requests

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

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. See Using Object Lifecycle Management for information on this feature.

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 Overview and Notifications Overview.

For more 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 Usage Reports Overview and Accessing 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 for it.

User-Specified Bucket Names

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

  • 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.
  • Make the name unique within your tenancy's Object Storage namespace.

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 its contents requires authentication and authorization. However, Object Storage supports anonymous, unauthenticated access to a bucket. 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, users 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. Users would not be able to list bucket contents.

Scope and Constraints

Understand the following scope and constraints regarding public access:

  • 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
To create a bucket
To view bucket details
To change the visibility of a bucket
To move a bucket to a different compartment
To manage tags for a bucket
To delete a bucket
To assign a Key Management master encryption key to a bucket
To remove a Key Management master encryption key from a bucket
To re-encrypt a bucket's data encryption keys
To view the approximate bucket size and number of objects in the bucket
To enable or disable emitting events for object state changes

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 CLI Help.

To get a list of buckets
To create a standard Object Storage tier bucket
To create an Archive tier bucket
To create a public bucket that allows listing and downloading bucket objects
To create a public bucket that allows downloading bucket objects only
To create a bucket with resource tags
To view bucket details
To view bucket metadata
To add custom metadata key-value pairs to a bucket
To make a bucket private or public
To move a bucket to a different compartment
To add resource tags to a bucket
To delete a bucket
To assign a Key Management key to a bucket
To update the Key Management key assigned to a bucket
To remove the Key Management key assigned to a bucket
To re-encrypt a bucket's data encryption keys
To view the approximate bucket size and number of objects in the bucket
To enable or disable emitting events for object state changes

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 operations to manage buckets:

Note

There are two key properties worthy of mention in the 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 whether or not events are emitted for the objects in this bucket.