Taxonomy Icon

Object Storage

As a consumer, you know that having a choice is a good thing. Can you imagine having only one flavor of ice cream to choose from, or only one brand of tires available for your car? When it comes to object storage, IBM Cloud now provides another option for cloud storage. With IBM Cloud Object Storage, you can store, manage, and access your data through a self-service portal and RESTful APIs. You can connect applications directly to object storage and integrate IBM Cloud services.

Learning objectives

To show how quickly you can port an app to Cloud Object Storage, this tutorial takes an application that is already set to use Amazon S3 and converts it to store data with IBM Cloud Object Storage.

Prerequisites

To complete the following steps, you need a service instance of IBM Cloud Object Storage, and Node.js installed locally.

Estimated time

It should take you about 15 minutes to complete these steps.

Steps

This tutorial has five steps:

  1. Download an application.
  2. Swap out the SDK.
  3. Create a credential.
  4. Add an endpoint.
  5. Run the app.

After that, you can review a brief discussion of alternative authentication methods.

Download an application

Start with a repository from the aws-samples organization in GitHub:

git clone https://github.com/aws-samples/aws-nodejs-sample

The aws-nodsjs-sample is a very simple Node.js app. When you run the sample, it creates a bucket in object storage and populates that bucket with a small file.

Swap out the SDK

The next step is to modify the application to use the IBM Cloud Object Storage Node.js software development kit (SDK). In the package.json file, change line 3 from "aws-sdk": ">= 2.0.9" to "ibm-cos-sdk": ">= 1.2.1". Then, in the sample.js file, change line 18 from var AWS = require('aws-sdk'); to var AWS = require('ibm-cos-sdk');.

The IBM Cloud Object Storage SDK is a fork of the AWS SDK and is essentially identical in terms of functionality. There is a difference in the Cloud Object Storage service itself that requires making a small change so the sample app works. The function call to create a bucket in IBM Cloud Object Storage requires an extra parameter, LocationConstraint: 'us-standard'. Add that parameter into sample.js on line 28 as shown in the following example:

s3.createBucket({Bucket: bucketName, CreateBucketConfiguration: {LocationConstraint: 'us-standard'},}, function () {

Create a credential

Of course, for the application to talk to IBM Cloud Object Storage, it needs credentials. Go to the Cloud Object Storage console and select your instance. Then click Service credentials on the menu, as shown in the following screen capture:

There are several authentication methods available for you to use. Because you are migrating from S3, start with what the app is natively expecting: HMAC keys. To create a pair of access and secret keys, click New Credential, and then specify {"HMAC":true} in the Add Inline Configuration Parameters (Optional) box:

After your new credential is created, view it. An S3 app looks for the fields listed under cos_hmac_keys to be in a file named ~/.aws/credentials, so create that file and populate it with your values, as shown in this example:

[default]
aws_access_key_id = {access_key_id}
aws_secret_access_key = {secret_access_key}

Add an endpoint

There is one more step before you can run the app. Near the top of the sample.js file, you need to create a variable to hold some endpoint information. Around line 20, add the following example:

var config = {
        endpoint: 's3-api.us-geo.objectstorage.softlayer.net',
        ibmAuthEndpoint: 'https://iam.ngbluemix.net/oidc/token'
};

The endpoint in the previous code snippet specifies the region where you want your bucket created. In this example, the US Cross Region endpoint is used. To specifiy a particular datacenter, region, or even a different continent, replace the endpoint listed with the endpoint that you want to use from the list at Select regions and endpoints.

Finally, in the line following your varible declaration, pass the variable to the client by changing var s3 = new AWS.S3(); to var s3 = new AWS.S3(config);.

Run the app

Now that youe swapped out the SDK and configured a credential, you can run your sample app (following the directions in its README):

npm install
node sample.js

You should see a response that looks like this example:

Successfully uploaded data to node-sdk-sample-1ec9247c-1055-47af-b53c-108f085898d7/hello_world.txt

To check, go back to the Cloud Object Storage console and select Buckets, as shown in the following screen capture. You should see your bucket listed.

If you click on the bucket name, you should see your hello_world.txt file in it. Now you are up and running with IBM Cloud Object Storage!

Additional authentication options

To show how quickly you can migrate an app from AWS to IBM Cloud Object Storage, the previous steps use the authentication method native to AWS apps. Now that the app is migrated, you can use simpler methods to authenticate with API keys. Select Service credentials and click New credential, but don’t ask for HMAC keys as you did in the previous steps. Instead, you can copy the entire credential into a file named ~/.bluemix/cos_credentials. If this file is present, it overrides anything from the file in ~/.aws/credentials that you created in the previous steps.

Yet another option is to add the credentials into the app itself. You can elaborate on the config variable you created in the previous steps to include additional values from the credential, like the following example:

var config = {
    endpoint: '<endpoint>',
    apiKeyId: '<api-key>',
    ibmAuthEndpoint: 'https://iam.ng.bluemix.net/oidc/token',
    serviceInstanceId: '<resource-instance-id>',
};

Summary

In this tutorial, you learned how quickly you can migrate an application from using AWS S3 to IBM Cloud Object Storage. The SDK is nearly identical, and after you port it to Cloud Object Storage, you have several additional authentication options.