Skip to content

getting-started.md

Latest commit

 

History

History
159 lines (102 loc) · 11.4 KB

getting-started.md

File metadata and controls

159 lines (102 loc) · 11.4 KB
Raw
copyright
years
2017, 2026
lastupdated 2026-07-01
keywords IBM cloud object storage, cloud object storage, object storage, storage, cross origin resource sharing, cors, special characters
subcollection cloud-object-storage

{{site.data.keyword.attribute-definition-list}}

Getting started with {{site.data.keyword.cos_full_notm}}

{: #getting-started-cloud-object-storage}

{{site.data.keyword.cos_full}} stores encrypted and dispersed data across multiple geographic locations. This getting started tutorial walks through the steps that are needed to use {{site.data.keyword.cos_full_notm}} to create buckets, upload objects, and set up access policies to allow other users to work with your data. {: shortdesc}

Before you begin

{: #getting-started}

You need the following to get started with {{site.data.keyword.cos_full_notm}}:

This tutorial takes a new user through the first steps with the {{site.data.keyword.cloud_notm}} Platform console. Developers who want to get started with the API, see the Developer's Guide or API overview.

Create some buckets to store your data

{: #gs-create-buckets}

  1. Ordering {{site.data.keyword.cos_full_notm}} creates a service instance. {{site.data.keyword.cos_full_notm}} is a multi-tenant system, and all instances of {{site.data.keyword.cos_short}} share physical infrastructure. You are automatically redirected to the service instance upon its creation. Your {{site.data.keyword.cos_short}} instances are listed under Storage in the resource list.

    The terms 'resource instance' and 'service instance' refer to the same concept, and can be used interchangeably. {: tip}

  2. You need a bucket before you can store data in your new service instance. To Create a bucket, start by choosing a unique name. All buckets in all regions across the globe share a single namespace. Ensure that you have the correct permissions to create a bucket.

    When you name buckets or objects, be sure to avoid the use of Personally Identifiable Information (PII). PII is information that can identify any user (natural person) by name, location, or any other means. {: tip}

    Bucket names are required to be DNS addressable and are not case-sensitive. {: tip}

  3. First, choose the level of resiliency you want. Then, choose 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 spreads your data across several metropolitan areas, while Regional resiliency spreads data across a single metropolitan area. A Single Data Center distributes data across devices within a single site only.

  4. Choose the bucket's storage class to accurately reflect how often you expect to read the stored data. This is important as it determines your billing details. Follow the Create link to create and access your new bucket.

  5. Determine the advanced configurations, if any, suitable to your content. You can store data by transitioning from any of the storage tiers (Standard, Vault, Cold Vault, and Flex) to long-term offline archive or use the online Cold Vault option.

Buckets are a way to organize your data, but they're not the sole way. Object names (often referred to as object keys) can use one or more forward slashes for a directory-like organizational system. You then use the portion of the object name before a delimiter to form an object prefix, which is used to list related objects in a single bucket through the {{site.data.keyword.cos_short}} API. {: tip}

Add some objects to your buckets

{: #gs-add-objects}

Now go ahead and go to one of your buckets by selecting it from the list. Click Add Objects. New objects overwrite existing objects with the same names within the same bucket. When you use the console to upload objects the object name always matches the file name. There doesn't need to be any relationship between the file name and the object key if you're using the API to write data. Go ahead and add a handful of files to this bucket.

Objects are limited to 200 MB when uploaded through the console unless you use the Aspera high-speed transfer plug-in or use Cross-Origin Resource Sharing (CORS), by setting the CORS headers. Larger objects (up to 10 TB) can also be split into parts and uploaded in parallel using the API. Object keys can be up to 1024 characters in length, and it's best to avoid any characters that might be problematic in a web address. For example, ?, =, <, and other special characters might cause unwanted behavior if not URL-encoded. {: tip}

Search and filter objects in the UI

{: #gs-search-filter-objects}

You can use the {{site.data.keyword.cos_short}} console to quickly locate objects within a bucket by using search and filtering capabilities. The UI provides both simple search and advanced filtering options to help you efficiently find objects based on specific properties.

Search objects by prefix

{: #gs-search-by-prefix}

You can quickly find objects by searching for their names or prefixes.

  1. In the Objects tab of your bucket, select Filter by: Prefix only.
  2. Enter a keyword or prefix in the search field.
  3. The object list updates automatically based on the entered value.

The search is based on the object name (key), and results are filtered in real time as you type. {: tip}

Filter objects using advanced properties

{: #gs-filter-advanced}

You can apply advanced filters to narrow down objects based on multiple attributes.

  1. In the Objects tab, select Filter by: Advanced properties.
  2. Choose a property from the list:
    • Name contains or Prefix
    • Size (Bytes)
    • Last modified
    • Extension
  3. Enter or select the required values.
  4. (Optional) Click Add filter to include additional conditions.
  5. Select AND or OR to define how multiple filters are applied.
  6. Click Apply to view the filtered object list.

For example, you can find all objects larger than 500000 bytes with names containing "backup" by combining size and name filters.

Available filter options

{: #gs-filter-options}

You can select from the following filter types:

Filter option Description
Prefix Filters objects by the starting characters of the name.
Name contains Matches objects that include specific text.
Size (Bytes) Filters based on object size by using comparison operators.
Last modified Filters based on modification date.
Extension Filters objects by file type.
{: caption="Object filter options" caption-side="bottom"}

Combine multiple filters

{: #gs-combine-filters}

You can combine multiple filters to refine your search further:

  • Use AND to return objects that match all conditions
  • Use OR to return objects that match any condition

This helps in identifying objects more precisely in large datasets.

Filtering large buckets with many objects might affect browser performance. Results depend on the number of objects and applied filters. {: note}

If an object with a special character is uploaded to a bucket, it might cause problems with displaying and accessing it in the UI. In these cases, the object should be deleted and reuploaded with a more standard name. You might delete these objects with Expiration or Lifecycle rules if the UI and CLI deletions are not successful. Avoid special characters to prevent any difficulties with accessing or deleting the object. {: attention}

How do I invite a user to administer buckets and data?

{: #gs-invite-user} {: help} {: support}

Bringing in another user and allow them to act as an administrator for the instance and any data stored in it is an important way to distribute responsibility for administering your {{site.data.keyword.cos_full_notm}} instance.

  1. To add the new user, you first need to leave the current {{site.data.keyword.cos_short}} interface and head for the IAM console. Go to the Manage menu and follow the link at Access (IAM) > Users. Click Invite users.

  2. Enter the email address of a user you want to invite to your organization, then expand the Services section and select "Resource" from the Assign access to menu. Now choose "Cloud Object Storage" from the Services menu.

  3. Now, three more fields appear: Service instance, Resource Type, and Resource ID. The first field defines which instance of {{site.data.keyword.cos_short}} the user can access. It can also be set to grant the same level of access to all instances of {{site.data.keyword.cos_short}}. We can leave the other fields blank for now.

  4. The checkbox under Select roles determines the set of actions available to the user. Select the "Administrator" platform access role to allow the user grant other users and service IDs access to the instance. Select the "Manager" service access role to allow the user to manage the {{site.data.keyword.cos_short}} instance as well as create and delete buckets and objects. These combinations of a Subject (user), Role (Manager), and Resource ({{site.data.keyword.cos_short}} service instance) together form IAM policies. For more detailed guidance on roles and policies, see the IAM documentation.

Give developers access to a bucket.

{: #gs-bucket-policy}

  1. Navigate to the Manage menu and follow the link at Access(IAM) > Service IDs. Here you can create a service ID, which serves as an abstracted identity bound to the account. Service IDs can be assigned API keys and are used in situations where you don't want to tie a particular Developer's identity to a process or component of an application.

  2. Repeat the above process but in step 3, choose a particular service instance, and enter "bucket" as the Resource Type and the full CRN of an existing bucket as the Resource ID.

  3. Now the service ID can access that particular bucket, and no others.

Next steps

{: #gs-next-steps}

Now that you are familiar with your object storage via the web-based console, you might be interested in doing a similar workflow from the command line. Check out using the ibmcloud cos command-line utility to create a service instance and interacting with IAM. And you can further use curl for accessing COS directly. Check out the API overview to get started.