IBM Cloud Docs
Getting started with IBM Cloud Object Storage

Getting started with IBM Cloud Object Storage

IBM Cloud® Object Storage stores encrypted and dispersed data across multiple geographic locations. This getting started tutorial walks through the steps that are needed to use IBM Cloud Object Storage to create buckets, upload objects, and set up access policies to allow other users to work with your data.

Before you begin

You need the following to get started with IBM Cloud Object Storage:

This tutorial takes a new user through the first steps with the IBM Cloud 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

  1. Ordering IBM Cloud Object Storage creates a service instance. IBM Cloud Object Storage is a multi-tenant system, and all instances of Object Storage share physical infrastructure. You will be automatically redirected to the service instance upon its creation. Your Object Storage 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.

  2. You will 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.

    Bucket names are required to be DNS addressable and are not case-sensitive.

  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. See the example in Figure 1 for options in creating an archive policy.

Figure 1. Create an archive policy
Create an archive policy

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 Object Storage API.

Add some objects to your buckets

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

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

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 IBM Cloud Object Storage instance.

  1. To add the new user you first need to leave the current Object Storage interface and head for the IAM console. Go to the Manage menu and follow the link at Access (IAM) > Users. Click Invite users.
    Figure 2: IAM invite users
    IAM 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.
    Figure 3: IAM Services
    IAM Services
  3. Now, three more fields appear: Service instance, Resource Type, and Resource ID. The first field defines which instance of Object Storage the user can access. It can also be set to grant the same level of access to all instances of Object Storage. We can leave the other fields blank for now.
    Figure 4: IAM identifiers for services and resources
    IAM invite users
  4. The check box 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 Object Storage instance as well as create and delete buckets and objects. These combinations of a Subject (user), Role (Manager), and Resource (Object Storage service instance) together form IAM policies. For more detailed guidance on roles and policies, see the IAM documentation.
    Figure 5: IAM select roles
    IAM roles

Give developers access to a bucket.

  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.
    Figure 6: IAM Service Ids
    IAM Service Ids
  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

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.