IBM Cloud Docs
Using a Dedicated Hardware plan instance

Using a Dedicated Hardware plan instance

This tutorial shows you how to create an IBM® Cloudant® for IBM Cloud® Dedicated Hardware plan instance that uses the IBM Cloud® Dashboard.

After that exercise, you learn how to provision one or more Standard plan instances to run on the IBM Cloudant Dedicated Hardware plan instance by using either the IBM Cloud catalog or the IBM Cloud CLI.

When you create an IBM Cloudant Dedicated Hardware plan instance, an IBM Cloudant environment on dedicated hardware is created for your sole use. A service instance for the Dedicated Hardware plan environment is also created in the IBM Cloud Dashboard. You can't access the Dedicated Hardware plan instance directly, or have any Service Credentials for it. Instead, you use your IBM Cloudant Dedicated Hardware plan instance by creating one or more Standard plan instances on it, and managing the Standard plan instances directly.

Objectives

  1. Create a Dedicated Hardware plan instance.
  2. Provision a Standard plan instance on a Dedicated Hardware environment.
  3. Provision a Dedicated Hardware plan instance with the IBM Cloud CLI.
  4. Provision a Standard plan instance on a Dedicated Hardware environment with the IBM Cloud CLI.
  5. Create the credentials for your IBM Cloudant service.
  6. List the service credentials for your IBM Cloudant service.

Creating an IBM Cloudant Dedicated Hardware plan instance

  1. Log in to your IBM Cloud account.

    The IBM Cloud Dashboard can be found by using the following website: https://cloud.ibm.com/. After you authenticate with your username and password, the IBM Cloud Dashboard opens.

  2. Click Create resource.

  3. Type Cloudant in the Search bar and open it.

  4. Select the Cloudant offering.

  5. Select an environment.

    For Dedicated Hardware provisioned instances, you can select from the major IBM Cloud regions in the IBM Cloud Dashboard. However, the actual physical location of the Dedicated Hardware instance is dictated by the location parameter in a later step.

    1. Click Dedicated.

    2. Click Create Host.

      Create a host by clicking the Create host button.
      Figure 1. Host selection

    3. Select from the IBM Cloud regions.

  6. Configure the Host.

    1. Select a location for deployment.

      This location is the physical location of the instance, which can be in any IBM Cloud location, including locations outside the major regions. For more information, see IBM® global data centers.

    2. Select Yes or No to answer whether HIPAA is required.

      HIPAA is only valid for US locations. IBM® can provision a Dedicated Hardware plan environment to implement HIPAA controls. An environment is only created upon confirmation of a Business Associate Agreement (BAA) that is established with IBM. For more information, see Enabling the HIPAA Supported setting and the Service Description terms for more details. Provisioning a cluster to manage HIPAA data can take longer than the estimated 5-day period.

    3. Select a key management service instance.

      All IBM Cloudant environments are encrypted. If you would like to use bring-your-own-key (BYOK) encryption with Key Protect, select the Key Protect instance that holds the encryption key from the drop-down menu. Otherwise, choose the Automatic disk encryption key (default) option, which means the environment is encrypted with an IBM Cloudant-managed key. In order to BYOK with Key Protect, you must ensure that IBM Cloudant is authorized to access the selected key management service instance. You can manage service-to-service authorizations at any time. Visit Manage > Access (IAM) and choose Authorizations.

      When you configure service-to-service authorizations, remember the authorization works at the account level, not the resource group level.

    4. Select a disk encryption key.

      Choose the disk encryption key from the drop-down menu that resides in the Key Protect instance that is chosen in the key management service instance parameter. If you use the default IBM Cloudant-managed key option, then this parameter is set to Automatic disk encryption key (default).

    Configure the host by specifying the location for deployment, HIPAA compliance, Key Management Service instance, and disk encryption key.
    Figure 2. Host configuration

  7. Click Create to start the provisioning process.

    Billing is calculated and prorated every day. Make sure that you want to provision and pay for an environment before you click Create.

    Do not click Create unless you want to provision and pay for an environment.
    Figure 3. Provision dedicated hardware

Provisioning a Standard plan instance on a Dedicated Hardware environment

After your instance is created, you must create a Standard plan on it by selecting the Dedicated tab when you create the Standard instance.

  1. Log in to your IBM Cloud account.

    The IBM Cloud Dashboard can be found at: https://cloud.ibm.com/. After you authenticate with your username and password, you're presented with the IBM Cloud Dashboard. Click Create resource.

  2. Type Cloudant in the Search bar and click to search.

  3. Select an offering.

    You can't provision a Lite plan instance on a Dedicated Hardware environment.

  4. Select an environment.

    For Dedicated Hardware provisioned instances, you can select from the major IBM Cloud regions in the IBM Cloud Dashboard. However, the actual physical location of the Dedicated Hardware instance is dictated by the location parameter in a later step.

    1. Click Dedicated.

    2. Click Select existing host.

    3. Select the dedicated environment that you created from the drop-down menu.
      The screen capture shows the example environment, Dedicated Hardware Environment (staging).

    From the Select an environment window. Select the Dedicated Hardware Environment.
    Figure 4. Dedicated environment

    1. Select the appropriate IBM Cloud region.

    From the Select an environment window, create an IBM Cloud region.
    Figure 5. IBM Cloud region

  5. Configure the IBM Cloudant instance.

    1. Enter an instance name or accept the pre-filled name.

    2. Select a resource group.

    3. (Optional) Add a tag.

    4. Select an authentication method.
      The Standard plan is the only plan you can use with the Dedicated Hardware environment.

    Configure your IBM Cloudant instance.
    Figure 6. IBM Cloudant instance

  6. Click Create.
    After a few seconds, the instance is provisioned on the environment you selected.

    Provision a standard plan by using the create button.
    Figure 7. Standard instance

  7. Take note of your Service Credentials and access the IBM Cloudant Dashboard as you do for a multi-tenant IBM Cloudant instance.

    For more information, see how to locate your service credentials.

Provisioning a Dedicated Hardware plan instance with the IBM Cloud CLI

  1. Log in to IBM Cloud to use IBM Cloud CLI.
    For more information, see log in to your IBM Cloud account to learn about how to log in and set a target resource group.

  2. Use the following basic command format to create an IBM Cloudant Dedicated Hardware plan instance by using IBM Cloud CLI.

    ibmcloud resource service-instance-create $NAME $SERVICE_NAME $PLAN_NAME $REGION [-p, --parameters @JSON_FILE | JSON_STRING ]
Table 1. Basic command format
Field Description
NAME An arbitrary name that you assign the instance.
SERVICE_NAME cloudantnosqldb
PLAN_NAME dedicated-hardware
REGION The major region where you want to deploy, for example, us-south, us-east, or eu-gb.

IBM Cloudant Dedicated Hardware plan instances take four more parameters.

Table 2. Parameters
Parameter Description
location The actual physical location of the Dedicated Hardware plan instance, which might differ from the REGION. The location can be in any IBM Cloud location, including major regions and locations outside the major regions. For more information, see IBM® global data centers.
hipaa Either true or false.
kms_instance_crn An optional parameter that must be set to the CRN of the Key Protect instance housing the encryption key for BYOK. All IBM Cloudant environments are encrypted. If you would like to BYOK with Key Protect, supply the CRN of the Key Protect instance that holds the encryption key. Otherwise, don't supply this parameter in the CLI, which means the environment is encrypted with an IBM Cloudant-managed key. In order to BYOK with Key Protect, ensure that IBM Cloudant is authorized to access the selected key management service instance. You can manage service-to-service authorizations at any time by visiting Manage > Security > Identity and Access and choosing Authorizations.
kms_key_crn This parameter is required if you use the kms_instance_crn parameter. Otherwise, it must not be supplied in the CLI command. The kms_key_crn parameter is set to the CRN of the encryption key that is stored in the Key Protect instance that is defined by the kms_instance_crn parameter.

The following example command includes the extra parameters.

ibmcloud resource service-instance-create cloudant-dedicated-with-byok cloudantnosqldb dedicated-hardware us-south -p '{"location":"dallas", "hipaa":"false", "kms_instance_crn": "crn:v1:bluemix:public:kms:us-south:a/abcdefg7df5907a4ae72ad28d9f493d6:888a5a41-543c-4ca7-af83-74da3bb8f711::", "kms_key_crn": "crn:v1:bluemix:public:kms:us-south:a/abcdefg7df5907a4ae72ad28d9f493d6:888a5a41-543c-4ca7-af83-74da3bb8f711:key:0123c653-f904-4fe7-9fdb-5097e1ed85db"}'

Provisioning a Standard plan instance on a Dedicated Hardware environment with the IBM Cloud CLI

  1. Log in to use the IBM Cloud CLI. For more information about how to log in and set a target resource group, see log in to your IBM Cloud account.

  2. Create an IBM Cloudant Standard plan instance on your IBM Cloudant Dedicated Hardware plan environment by using the following basic command format.

    ibmcloud resource service-instance-create $NAME $SERVICE_NAME $PLAN_NAME $REGION [-p, --parameters @JSON_FILE | JSON_STRING ]
Table 3. Basic command format
Field Description
NAME An arbitrary name that you assign the instance.
SERVICE_NAME cloudantnosqldb
PLAN_NAME standard
REGION The region where you want to deploy, for example, us-south, us-east, or eu-gb.

IBM Cloudant instances that are deployed on Dedicated Hardware environments take two more parameters.

Table 4. Parameters
Parameter Description
environment_crn This parameter must be set to the CRN of the IBM Cloudant Dedicated Hardware plan instance. You can determine what the CRN is by looking at the example CLI command in the Manage tab of the IBM Cloudant Dedicated Hardware plan instance in the IBM Cloud Dashboard. Or you can determine what the CRN is by using the ibmcloud resource service-instance SERVICE_INSTANCE_NAME command.
legacyCredentials An optional parameter that defaults to true and dictates whether the instance uses both legacy and IAM credentials or IAM credentials only. See the IAM guide for more details on choosing an authentication method.

The following example command includes the extra parameters.

ibmcloud resource service-instance-create cloudant_on_ded_hardware_cli cloudantnosqldb standard us-south -p '{"environment_crn":"crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b43434444bb7e2abb0841ca25d28ee4c:301a3118-7678-4d99-b1b7-4d45cf5f7b29::","legacyCredentials":false}'

Creating the 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 gains 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.

The fields for the basic command format that is used in this exercise are described in the following table.

Table 5. Basic command format
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.
service-endpoints An optional parameter to populate the URL field in the Service Credentials with an internal endpoint to connect to the service over the IBM Cloud internal network. Omit this parameter to populate the URL with an external endpoint that is publicly accessible. Applies only to Standard plan instances deployed on Dedicated Hardware environments that support internal endpoints. If the environment doesn't support internal endpoints, the result is a 400 error.

The basic command format to retrieve the credentials for a service instance within IBM Cloud is shown in the following example.

ibmcloud resource service-key-create NAME ROLE_NAME --instance-name SERVICE_INSTANCE_NAME [-p '{"service-endpoints":"internal"}]

The fields for the basic command format are described in the previous table.

  1. Create credentials for the cs20170517a instance of an IBM Cloudant service, and name the credentials creds_for_cs20170517a.

    ibmcloud resource service-key-create creds_for_cs20170517a Manager --instance-name cs20170517a

  2. After you receive the request to create credentials for the service instance, review the IBM Cloud response that includes a message similar to the following (abbreviated) example with your credentials.

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

  3. Populate the URL with the internal endpoint, and create the credentials by using a command similar to the following example.

    ibmcloud resource service-key-create creds_for_cs20170517a Manager --instance-name cs20170517a -p '{"service-endpoints":"internal"}'

  4. Review the request response in a message similar to 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 Jan 02 19:58:38 UTC 2019
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://2624fed5-e53e-41de-a85b-3c7d7636886f-bluemix.private.cloudantnosqldb.appdomain.cloud
                username:                 f6cf0c55-48ea-4908-b441-a962b27d3bb6-bluemix
                apikey:                   XXXXX-XXXXXX_XXXXXXXXXXXXX-XXXXXXXXXXX
                host:                     2624fed5-e53e-41de-a85b-3c7d7636886f-bluemix.private.cloudantnosqldb.appdomain.cloud
                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-4fo0                  90-b072-bfffafb68b3e

Listing the service credentials for your IBM Cloudant service

The basic command format to retrieve the credentials for a service instance within IBM Cloud is shown in the following example.

ibmcloud resource service-key KEY_NAME

  1. Retrieve your credentials cs20170517a (where the name for the credentials is creds_for_cs20170517a) by using a command similar to the following example.

    ibmcloud resource service-key creds_for_cs20170517b

  2. Review the IBM Cloud response that includes your credentials and a message similar to 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