Managing IBM Cloud Object Storage (COS) buckets

Buckets are a way to organize your data in an IBM Cloud Object Storage instance.

To manage buckets, your user must be granted permissions to work with buckets on the IBM Cloud Object Storage instance. For more information about roles, see Identity and Access Management roles.

Creating a bucket

Choose 1 of the following options to create a bucket:

Table 1. Create bucket requests
Action	More info
Create a bucket through the IBM Cloud UI	Learn more
Create a bucket through the IBM Cloud CLI	Learn more
Create a bucket by using cURL	Learn more
Create a bucket by using the REST API	Learn more
Create a bucket with a different storage class by using the REST API	Learn more
Create a bucket with Key Protect or Hyper Protect Crypto Services managed encryption keys (SSE-KP) by using the REST API	Learn more
Create a bucket by using Terraform	Learn more

To create a bucket, your user must have manager or writer permissions for the IBM Cloud Object Storage instance where you plan to create the bucket.

Creating a bucket through the IBM Cloud UI

Complete the following steps to create a bucket through the IBM Cloud UI:

From the Navigation menu, select Resource List.
Select the IBM Cloud Object Storage instance where you plan to create the bucket.
Select Buckets. Then, click Create Bucket.

If you are configuring archiving in an EU-managed location, you must configure a bucket that complies with the EU-managed and GDPR regulations. For more information, see European Union support.
Enter a bucket name for the Unique bucket name field.

Note: All buckets in all regions across the globe share a single namespace.
Choose the type of resiliency and a location where you would like your data to be physically stored.

Resiliency refers to the scope and scale of the geographic area across which your data is distributed.

Cross Region resiliency will spread your data across several metropolitan areas.

Regional resiliency will spread data across a single metropolitan area.

A Single Data Center will only distribute data across devices within a single site.

For more information, see Select regions and endpoints.
Choose the type of Storage class.

You can create buckets with different storage classes. Choose the storage class for your bucket based on your requirements to retrieve data. For more information, see Use storage classes.

It is not possible to change the storage class of a bucket once the bucket is created. If objects need to be reclassified, it is necessary to move the data to another bucket with the wanted storage class.
Optionally, add additional encryption to your bucket. For example, configure Key Protect Key in your bucket to encrypt data at rest.

You can only add additional encryption when you create the bucket.

All objects are encrypted by default using randomly generated keys and an all-or-nothing-transform. While this default encryption model provides at-rest security, some workloads need to be in possession of the encryption keys used. For more information, see Manage encryption.

Getting the bucket configuration details through the IBM Cloud UI

When you configure a target, you need the bucket name and the private endpoint.

Complete the following steps to get the bucket configuration details through the IBM Cloud UI:

From the Navigation menu, select Resource List.
Select the IBM Cloud Object Storage instance where you plan to create the bucket.
Select Buckets. Then, select the bucket that you want to use to collect auditing events.
Select Configuration. Look for the bucket name and the private endpoint.

Generating an API key to access a bucket

When Activity Tracking collects auditing events in your account, it uses an API key to upload data into a bucket. Therefore, you must define credentials in your account to work with the IBM Cloud Object Storage service.

To configure a region in your account to collect auditing events and store them in a bucket, you need a service credential with permissions to upload objects into the bucket.

For more information on how to grant access to a service ID, see Granting access to a service ID.

Collecting auditing events for a bucket

You can use the IBM Cloud Activity Tracker service to track how users and applications interact with IBM Cloud Object Storage (COS). For more information about the auditing events that are generated for a bucket and its objects, see Activity Tracker events.

To collect auditing events for a bucket, consider the following information:

Collection of auditing events in your account is optional.
You must configure each bucket to enable management events, or management and data events. Notice that you cannot enable data events only for a bucket.
To monitor management events, you must configure a bucket and specify the Activity Tracker instance where those events will be collected and forwarded.
To monitor data events, you must select the option Track data events. Then, select read, write, or read & write to collect events when an object is uploaded or downloaded from a bucket.

Enable collection of auditing events after you have configured Activity Tracking in the region where the bucket is located.

Listing objects in a bucket

You can choose any of the following methods to list objects in a bucket:

List objects in a given bucket by using the CLI.
List objects in a given bucket by using the API
List objects in a given bucket through the IBM Cloud UI.

List objects in a given bucket through the IBM Cloud UI

Complete the following steps to list the objects in a bucket through the IBM Cloud UI:

From the Navigation menu, select Resource List.
Select the IBM Cloud Object Storage instance where the bucket is available.
Select Buckets.
Select a bucket. The list of objects is displayed.

Managing access to a bucket

Access to work with the Object Storage service is controlled by IBM Cloud Identity and Access Management (IAM).

Every user or service ID that accesses the Object Storage service in your account must be assigned an access policy with an IAM role defined. That policy determines what actions the user or service ID can perform within the context of the service or instance you select. The allowable actions are customized and defined by the IBM Cloud service as operations that are allowed to be performed on the service. The actions are then mapped to IAM roles.

To define a policy, first you must set the scope. You can define a policy to grant access in any of the following contexts:

Across all instances of the service in your account
For an individual service instance in your account
For a specific bucket within an instance
For all IAM-enabled services in your account

After you define the scope of the access policy, you must assign a role.

For more information about what actions are allowed per role within the Object Storage service, see COS Identity and Access Management roles.
For more information about bucket permissions per role, see Bucket permissions.
For information about assigning roles, see Managing IAM access.

IAM policies are enforced hierarchically, from greatest level of access to most restricted. Conflicts are resolved to the more permissive policy. For example, if a user has both the Writer and Reader service access role on a bucket, the policy granting the Reader role is ignored. This is also applicable to service instance and bucket level policies, for example:

If a user has a policy granting the Writer role on a service instance and the Reader role on a single bucket, the bucket-level policy is ignored.
If a user has a policy granting the Reader role on a service instance and the Writer role on a single bucket, both policies are enforced and the more permissive Writer role will take precedence for the individual bucket.

To restrict access to a single bucket, ensure that the user or Service ID doesn't have any instance level policies.

Monitoring the health of a bucket

You can use the IBM Cloud® Monitoring service to monitor Object Storage (COS) in the IBM Cloud. Learn more.

CLI commands to manage buckets

The following commands might be useful when you work with buckets:

Check if a bucket exists in your account through the CLI

Run the following command to determine if a bucket exists in an IBM Cloud Object Storage instance in your account:

ibmcloud cos bucket-head --bucket BUCKET_NAME

Where BUCKET_NAME is the name of the bucket.