Creating an instance
You can create an instance of IBM® Key Protect for IBM Cloud® by using the IBM Cloud console or the IBM Cloud CLI.
This topic covers the process for deploying an instance of Key Protect inside IBM Cloud. For more information about deploying Key Protect on Satellite, check out About Key Protect on Satellite.
Overview
In Key Protect, an instance (sometimes referred to as a service instance) is a namespace.
A namespace organizes keys into logical groups and provides isolation and protection between namespaces.
- For example, you may choose to have two Key Protect instances - one for the finance department and one for manufacturing. Two instances provides isolation so keys in one business unit are not accessible from other business units.
The term instance is sometimes used to describe compute resources, such as
virtual servers or
virtual server instances for VPC. An instance, in Key Protect should not be equated with compute resources. A Key Protect instance
is a namespace.
Provisioning Key Protect from the IBM Cloud console
To provision an instance of Key Protect from the IBM Cloud console, complete the following steps.
-
Click Catalog to view the list of services that are available on IBM Cloud.
-
Search for "Key Protect" in the Search the catalog... field and click
Key Protect. -
Select a service plan, and click Create to provision an instance of Key Protect in the account, region, and resource group where you are logged in.
Provisioning Key Protect from the IBM Cloud CLI
You can also provision an instance of Key Protect by using the IBM Cloud CLI.
Login using the CLI
Login to IBM Cloud through the IBM Cloud CLI. This is the account used for this instance of Key Protect.
Login
Login with the login command. If this fails you should try the --sso option to login with a federated ID (see the next section).
This example fails because the email address belongs to a federated ID.
ibmcloud login
Example
$ ibmcloud login
API endpoint: https://cloud.ibm.com
Region: us-south
Email> <email address>
Password>
Authenticating...
You are using a federated user ID, please use one time passcode ( ibmcloud login --sso ), or use API key ( ibmcloud --apikey key or @key_file ) to authenticate.
API endpoint: https://cloud.ibm.com
Region: us-south
Not logged in.
FAILED
Login with a federated ID
Logging in with the --sso option opens a browser window (requires a login) and creates a one-time passcode. The passcode is used to complete the login process.
ibmcloud login --sso
Example
$ ibmcloud login --sso
API endpoint: https://cloud.ibm.com
Region: us-south
Get One Time Code from https://identity-2.us-south.iam.cloud.ibm.com/identity/passcode to proceed.
Open the URL in the default browser? [Y/n] > Y
One Time Code > <paste the one-time passcode from your browser>
Authenticating...
OK
Select an account:
1. Account name (ea988d3289c24739a0977651b46fb145)
Enter a number> 1
Targeted account Account name (ea988d3289c24739a0977651b46fb145)
API endpoint: https://cloud.ibm.com
Region: us-south
User: <email address>
Account: Account name (ea988d3289c24739a0977651b46fb145)
Resource group: No resource group targeted, use 'ibmcloud target -g RESOURCE_GROUP'
CF API endpoint:
Org:
Space:
Select a region and resource group
Select the region and resource group where you would like to create a Key Protect instance.
The <resource_group_name> can be Default (case-sensitive).
ibmcloud target -r <region_name> -g <resource_group_name>
Example
$ ibmcloud target -r us-south -g Default
Targeted resource group Default
Switched to region us-south
API endpoint: https://cloud.ibm.com
Region: us-south
User: <email address>
Account: Account name (ea988d3289c24739a0977651b46fb145)
Resource group: Default
CF API endpoint:
Org:
Space:
Provision a public instance
Provision a public Key Protect instance. The next section has an example of provisioning a private instance.
-
Public endpoints are outside the IBM Cloud.
-
Private endpoints are inside the IBM Cloud.
A public instance accepts API requests from both public and private endpoints. Public network access is the default setting and is used if a policy is not set.
A private instance accepts API requests from only private endpoints.
See Managing network access policies for learn more about public and private access.
Note the GUID is the instance ID. In this example, the instance ID is
ea557753-a15b-4570-a9a3-1efefbd2d382.
ibmcloud resource service-instance-create <instance_name> kms tiered-pricing <region>
Example
# create a public service instance
$ ibmcloud resource service-instance-create <instance_name> kms tiered-pricing us-south
Creating service instance <instance_name> in resource group Default of account <account name> as <email address>...
OK
Service instance <instance_name> was created.
Name: <instance_name>
ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:ea557753-a15b-4570-a9a3-1efefbd2d382::
GUID: ea557753-a15b-4570-a9a3-1efefbd2d382
Location: us-south
State: active
Type: service_instance
Sub Type: kms
Allow Cleanup: false
Locked: false
Created at: 2020-05-31T15:04:50Z
Updated at: 2020-05-31T15:04:50Z
Last Operation:
Status create succeeded
Message Completed create instance operation
# list the service instances
$ ibmcloud resource service-instances
Retrieving instances with type service_instance in resource group Default in all locations under account <account name> as <email address>...
OK
Name Location State Type
<instance_name> us-south active service_instance
# delete the public service instance
$ ibmcloud resource service-instance-delete <instance_name>
Deleting service instance <instance_name> in resource group Default under account <account name> as <email address>...
Really delete the service instance <instance_name> with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:ea557753-a15b-4570-a9a3-1efefbd2d382::? [y/N] > y
OK
Service instance <instance_name> with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:ea557753-a15b-4570-a9a3-1efefbd2d382:: is deleted successfully
Provision a private instance
Provision a private Key Protect instance.
Remember that a private instance accepts API requests from only private endpoints, which are inside the IBM Cloud. You cannot use the CLI with a private instance if you are outside the IBM Cloud.
ibmcloud resource service-instance-create <instance_name> kms tiered-pricing <region> -p '{"allowed_network": "private-only"}'
Example
After the private instance is created, a request is made to create a key. The request fails because the user does not have access to the private instance from outside the IBM Cloud.
The -p option specifies a JSON file or JSON string of parameters used to create the service instance.
# create a private service instance
$ ibmcloud resource service-instance-create <service-name> kms tiered-pricing us-south -p '{"allowed_network": "private-only"}'
Creating service instance <service-name> in resource group Default of account <account name> as <email address>...
OK
Service instance <service-name> was created.
Name: <service-name>
ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::
GUID: a152eee4-262e-4a39-ae13-a71b9882dcb6
Location: us-south
State: active
Type: service_instance
Sub Type: kms
Allow Cleanup: false
Locked: false
Created at: 2020-05-31T15:10:23Z
Updated at: 2020-05-31T15:10:23Z
Last Operation:
Status create succeeded
Message Completed create instance operation
# list the service instances
$ ibmcloud resource service-instances
Retrieving instances with type service_instance in resource group Default in all locations under account <account name> as <email address>...
OK
Name Location State Type
<service-name> us-south active service_instance
# list the private service instance
$ ibmcloud resource service-instance <service-name>
Retrieving service instance <service-name> in resource group Default under account <account name> as <email address>...
OK
Name: <service-name>
ID: crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::
GUID: a152eee4-262e-4a39-ae13-a71b9882dcb6
Location: us-south
Service Name: kms
Service Plan Name: tiered-pricing
Resource Group Name: Default
State: active
Type: service_instance
Sub Type: kms
Created at: 2020-05-31T15:10:23Z
Created by: <email address>
Updated at: 2020-05-31T15:10:23Z
Last Operation:
Status create succeeded
Message Completed create instance operation
# list keys in the private service instance
$ ibmcloud kp keys -i a152eee4-262e-4a39-ae13-a71b9882dcb6
Retrieving keys...
FAILED
kp.Error: correlation_id='59578794-2b5b-48ca-9074-bbe23760d94a', msg='Unauthorized: The user does not have access to the specified resource'
# delete the private service instance
$ ibmcloud resource service-instance-delete <service-name>
Deleting service instance <service-name> in resource group Default under account <account name> as <email address>...
Really delete the service instance <service-name> with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::? [y/N] > y
OK
Service instance <service-name> with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6:: is deleted successfully
Deleting an instance with existing keys
You cannot delete a service instance that contains keys.
Example
$ ibmcloud resource service-instance-delete <instance_name>
Deleting service instance <instance_name> in resource group Default under account <account name> as <email address>...
Really delete the service instance <instance_name> with ID crn:v1:bluemix:public:kms:us-south:a/ea988d3289c24739a0977651b46fb145:a152eee4-262e-4a39-ae13-a71b9882dcb6::? [y/N] > y
FAILED
Error Code: RC-ServiceBrokerErrorResponse
Message: [409, Conflict] Conflict: Instance contains 2 active keys. Remove all keys before de-provisioning
What's next
To find out more about programmatically managing your keys, check out the Key Protect API reference doc.