Creating an instance with CLI

This tutorial shows you how to create an IBM® Cloudant® for IBM Cloud® service instance on IBM Cloud® by using the IBM Cloud CLI.

Objectives

Use your IBM Cloud account to create your IBM Cloudant service instance and credentials.
Retrieve and use your IBM Cloudant service instance.

Before you begin

Install the IBM Cloud CLI developer tools by following the Getting started with the IBM Cloud CLI tutorial.

Logging in to your IBM Cloud account

The following example describes how to log in. If you use a federated user ID, it's important that you switch to a one-time passcode (ibmcloud login --sso), or use an API key (ibmcloud --apikey key or @key_file) to authenticate. For more information about how to log in by using the CLI, see General CLI (ibmcloud) commands under ibmcloud login.

Start the login process for your IBM Cloud account by using the following command.
```
ibmcloud login
```
IBM Cloud responds by reminding you of the current API endpoint, and asks for the email address of your account.
```
API endpoint: https://cloud.ibm.com
Region: au-syd

Email>

Password>
```

Enter the email address of your account, and then enter your password.

API endpoint: https://cloud.ibm.com

Email> J.Doe@email.com

Password>

IBM Cloud validates your details and summarizes the information about your login session.

API endpoint: https://cloud.ibm.com

Email> J.Doe@email.com

Password>
Authenticating...
OK

Targeted account J DOE's Account (707...a32)

Targeted org J.Doe@email.com

Targeted space dev

API endpoint:   https://cloud.ibm.com (API version: 2.54.0)
Region:         au-syd
User:           j.doe@email.com
Account:        J DOE's Account (707...a32)
Org:            J.Doe@email.com
Space:          dev

You're now logged in to your IBM Cloud account.

Creating the IBM Cloudant service

IBM Cloudant uses resource groups for provisioning new instances. For more information, see the Resource Groups FAQ.

In this example, you create a service instance within IBM Cloud by running the following command.

ibmcloud resource service-instance-create NAME SERVICE_NAME SERVICE_PLAN_NAME LOCATION [-p, --parameters @JSON_FILE | JSON_STRING ]

The fields in the command are described in the table that follows.

Table 1. Basic command format fields
Field	Description
`NAME`	Arbitrary name that you give to the instance.
`SERVICE_NAME`	`cloudantnosqldb`
`SERVICE_PLAN_NAME`	Lite plan (`lite`) or Standard plan (`standard`)
`LOCATION`	The location where you want to deploy includes the following cities: Sydney `au-syd`, Chennai `in-che`, Osaka `jp-osa`, Tokyo `jp-tok`, Seoul `kr-seo`, Frankfurt `eu-de`, London `eu-gb`, Dallas `us-south`, Washington DC `us-east`.
`legacyCredentials`	Defaults to `true`. This field dictates whether the instance uses both legacy and IAM credentials or IAM credentials only.

SERVICE_PLAN_NAME is the type of pricing plan you select when you create an instance. For more information, see Plans in the documentation for details on using the IBM Cloudant Lite or Standard plan.

For more information about choosing an authentication method, see the IAM guide. The IBM Cloudant team recommends that you use IAM access controls over IBM Cloudant legacy authentication whenever possible.

Now, we create a service instance that is called, cs20170517a.

Set your target resource group and region by using the following format. To run this command, you need to know the region and resource groups, which you find in the following steps.

For more information, see General CLI (ibmcloud) commands under ibmcloud target.
```
ibmcloud target [-r REGION_NAME] [-g RESOURCE_GROUP]
```
To see a list of regions, run the following command.
```
ibmcloud regions
```
To see a list of resource groups, run the following command.
```
ibmcloud resource groups
```
Create an instance of an IBM Cloudant service by using the Lite plan.
The instance name is cs20170517a in the US-South location and uses IAM credentials only.
```
ibmcloud resource service-instance-create cs20170517a cloudantnosqldb lite us-south -p '{"legacyCredentials": false}'
```

After you create the service instance, see the following example message.

Creating service instance cs20170517a in resource group default of account John Does's Account as j.doe@email.com...
OK
Service instance cs20170517a was created.
Name          Location   State        Tags
cs20170517a   au-syd   active   service_instance

Next, you create service credentials for your IBM Cloudant service instance.

Creating credentials for your IBM Cloudant service

Applications that require access to your IBM Cloudant service must have the necessary credentials.

Service credentials are valuable. If anyone or any application has access to the credentials, they can effectively do whatever they want with the service instance. For example, they might create spurious data, or delete valuable information. Protect these credentials carefully.

For more information about the fields included in the service credentials, see the IAM guide.

In the next example, you create credentials for a service instance within IBM Cloud by running the following command.

ibmcloud resource service-key-create NAME ROLE_NAME --instance-name SERVICE_INSTANCE_NAME

The fields in the command are described in the table that follows.

Table 2. Create credential fields
Field	Description
`NAME`	Arbitrary name that you give the service credentials.
`ROLE_NAME`	This field currently allows the Manager role only.
`SERVICE_INSTANCE_NAME`	The name that you give to your IBM Cloudant instance.

Now, you create credentials for the cs20170517a instance you created in the previous step.

Create credentials for the cs20170517a instance of an IBM Cloudant service (where the name for the credentials is creds_for_cs20170517a) by running the following command.
```
ibmcloud resource service-key-create creds_for_cs20170517a Manager --instance-name cs20170517a
```

After you receive the request to create credentials for the service instance, review the response from IBM Cloud that contains a message similar to the one in the following example.

Creating service key in resource group default of account John Does's Account as john.doe@email.com...
OK
Service key crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b42223455bb7e2abb0841ca25d28ee4c:ee78351d-82bf-4e80-bc22-825c937fafa3:resource-key:621ffde2-ea10-4318-b297-d6d849cec48a was created.

Name:          creds_for_cs20170517a
ID:            crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b42223455bb7e2abb0841ca25d28ee4c:ee78351d-82bf-4e80-bc22-825c937fafa3:resource-key:621ffde2-ea10-4318-b297-d6d849cec48a
Created At:    Tue Sep 18 19:58:38 UTC 2018
State:         active
Credentials:
               iam_apikey_name:          auto-generated-apikey-621ffde2-ea10-4318-b297-d6d849cec48a
               iam_role_crn:             crn:v1:bluemix:public:iam::::serviceRole:Manager
               url:                      https://apikey-v2-58B528DF5397465BB6673E1B79482A8C:5811381f6daff7255b288695c3544be63f550e975bcde46799473e69c7d48d61@f6cf0c55-48ea-4908-b441-a962b27d3bb6-bluemix.cloudant.com
               username:                 apikey-v2-58B528DF5397465BB6673E1B79482A8C
               port:                     443
               apikey:                   XXXXX-XXXXXX_XXXXXXXXXXXXX-XXXXXXXXXXX
               host:                     f6cf0c55-48ea-4908-b441-a962b27d3bb6-bluemix.cloudant.com
               iam_apikey_description:   Auto generated apikey during resource-k  ey operation for Instance - crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b42116849bb7e2abb0841ca25d28ee4c:ee78351d-82bf-4e80-bc22-825c937fafa3::
               iam_serviceid_crn:        crn:v1:bluemix:public:iam-identity::a/b42116849bb7e2abb0841ca25d28ee4c::serviceid:ServiceId-53f9e2a2-cdfb-4f90-b072-bfffafb68b3e
               password:                 581138...7d48d61

Next, you learn how to retrieve your service credentials. You need your service credentials to log in to your IBM Cloudant instance.

Retrieving the service credentials for your IBM Cloudant service

Retrieve credentials for the cs20170517a instance of an IBM Cloudant service. The name for the credentials is creds_for_cs20170517a.
```
ibmcloud resource service-key creds_for_cs20170517b
```

After you receive the request to retrieve the credentials for the service instance, review the response from IBM Cloud that contains a message similar to the one in the following (abbreviated) example.

Retrieving service key in resource group default of account John Does's Account as john.doe@email.com...
OK
Service key crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b42223455bb7e2abb0841ca25d28ee4c:ee78351d-82bf-4e80-bc22-825c937fafa3:resource-key:621ffde2-ea10-4318-b297-d6d849cec48a was created.

Name:          creds_for_cs20170517a
ID:            crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b42223455bb7e2abb0841ca25d28ee4c:ee78351d-82bf-4e80-bc22-825c937fafa3:resource-key:621ffde2-ea10-4318-b297-d6d849cec48a
Created At:    Tue Sep 18 19:58:38 UTC 2018
State:         active
Credentials:
             iam_apikey_name:          auto-generated-apikey-621ffde2-ea10-4318-b297-d6d849cec48a
             iam_role_crn:             crn:v1:bluemix:public:iam::::serviceRole:Manager
             url:                      https://apikey-v2-58B528DF5397465BB6673E1B79482A8C:5811381f6daff7255b288695c3544be63f550e975bcde46799473e69c7d48d61@f6cf0c55-48ea-4908-b441-a962b27d3bb6-bluemix.cloudant.com
             username:                 apikey-v2-58B528DF5397465BB6673E1B79482A8C
             port:                     443
             apikey:                   XXXXX-XXXXXX_XXXXXXXXXXXXX-XXXXXXXXXXX
             host:                     f6cf0c55-48ea-4908-b441-a962b27d3bb6-bluemix.cloudant.com
             iam_apikey_description:   Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b42116849bb7e2abb0841ca25d28ee4c:ee78351d-82bf-4e80-bc22-825c937fafa3::
             iam_serviceid_crn:        crn:v1:bluemix:public:iam-identity::a/b42116849bb7e2abb0841ca25d28ee4c::serviceid:ServiceId-53f9e2a2-cdfb-4f90-b072-bfffafb68b3e
             password:                 581138...7d48d61

Now, the tutorial is complete. Optionally, you can delete the service credentials or service instance as shown in the steps in the next two sections.

For more information, see the Creating and populating a simple IBM Cloudant database on IBM Cloud tutorial. This tutorial shows you how to use an IBM Cloudant service instance from a Python application by using legacy credentials. Remember to substitute the credentials you created.

(Optional) Deleting service credentials

Delete the credentials called creds_for_cs20170517a by running a command like this one.

ibmcloud resource service-key-delete creds_for_cs20170517a

(Optional) Deleting a service instance

Delete the cs20170517a instance of an IBM Cloudant service by running a command like this one.

ibmcloud resource service-instance-delete cs20170517a