| copyright | lastupdated | keywords | subcollection | ||
|---|---|---|---|---|---|
|
2024-09-25 |
IBM cloud object storage, cloud object storage, object storage, storage, cross origin resource sharing, cors, special characters |
cloud-object-storage |
{{site.data.keyword.attribute-definition-list}}
{: #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}
{: #getting-started}
You need the following to get started with {{site.data.keyword.cos_full_notm}}:
- An {{site.data.keyword.cloud}} Platform account
- An instance of {{site.data.keyword.cos_full_notm}}
- Some files on your local computer to upload to {{site.data.keyword.cos_short}}.
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.
{: #gs-create-buckets}
-
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 will be 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}
-
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. {: tip}
Bucket names are required to be DNS addressable and are not case-sensitive. {: tip}
-
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.
-
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.
-
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.
{: caption="Figure 1. 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 {{site.data.keyword.cos_short}} API. {: tip}
{: #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}
If an object with a special character is uploaded to a bucket, it may cause problems with displaying and accessing it in the UI. In these cases, the object should be deleted and re-uploaded with a more standard name. You may 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}
{: #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.
- 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.
{: caption="Figure 2: IAM invite users"} - 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.
{: caption="Figure 3: IAM Services"} - 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.
{: caption="Figure 4: IAM identifiers for services and resources"} - 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 {{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.
{: caption="Figure 5: IAM select roles"}
{: #gs-bucket-policy}
-
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.
{: caption="Figure 6: IAM Service Ids"} -
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.
-
Now the service ID can access that particular bucket, and no others.
{: #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.