Creating Block Storage volumes with customer-managed encryption

By default, Block Storage for VPC boot and data volumes are encrypted with IBM-managed encryption. You can also use a supported key management service to create or import your customer root key, and use that to create an envelop encryption.

Before you begin

To create Block Storage volumes with customer-managed encryption, you must first provision a key management service (KMS), and create or import your customer root key (CRK). You can choose between Key Protect and Hyper Protect Crypto Services.

You must also create a service-to-service authorization between Block Storage for VPC and the KMS instance that you created.

Creating data volumes with customer-managed encryption in the UI

This procedure explains how to specify customer-managed encryption when you create a stand-alone Block Storage volume.

In the IBM Cloud console, click the Navigation menu icon > VPC Infrastructure > Storage > Block Storage volumes to view a list of your Block Storage volumes.
Select New volume.

Enter the information in Table 1 to define your new Block Storage volume.

Table 1. Values for provisioning Block Storage volumes with customer-managed encryption
Field	Value
Location	The geography, region, and zone are inherited from the VPC (for example, North America, Dallas, Dallas-1). You can select a different zone in your location from the menu by clicking the pencil icon.
Details	In the Details section, you must specify the name of the volume and the resource group that the volume is to be added to. Optionally, you can add user and access management tags.
Name	Specify a meaningful name for your volume. For example, provide a name that describes your compute or workload function. The volume name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-), and must begin with a lowercase letter. Volume names must be unique across the entire VPC infrastructure. You can later edit the name.
Resource Group	Specify a Resource group.
Tags	Specify user tags to organize your resources and for use by backup policies.
Access management tags	Specify access management tags that were created in IAM to help you manage access to your volumes.
Optional configurations	In the Optional configuration section, you can specify whether you want to create the volume with data from a snapshot. Also, you can choose to apply a backup policy.
Import from snapshot	Click Select snapshot to create the volume with data from the selected snapshot. You can create data volumes with Nonbootable snapshots, and boot volumes with Bootable snapshots.
Apply backup policy
Profile	In the Profile section, you can specify the performance profile of your volume, its IOPS, and capacity.
	For IOPS tiers, select the tile with the performance level that you require and specify the volume size in GBs. Volume sizes can be 10 - 16,000 GB.
	For Custom IOPS, specify the size of your volume and IOPS range based on the size of the volume. As you type the IOPS value, the UI shows the acceptable range. You can also click the storage size link to see a table of size and IOPS ranges. For more information, see Custom IOPS profile.
Encryption at rest	Encryption with IBM-managed keys is enabled by default on all volumes. You can also choose to use your own encryption key by selecting your key management service: (Key Protect or Hyper Protect Crypto Services).
Encryption service instance	Select the data encryption instance from the list. If you don't have an instance yet, you can click the link to create one.
Key name	Select the data encryption key within the Key Protect instance that you want to use for encrypting the volume.

If you created your Key Protect or Hyper Protect Crypto Services instance by using a private endpoint, the root keys that were created by using that instance are not shown in the UI. You must use the CLI or API to access and use these root keys.

When your changes are complete, click Create Volume.
Optionally, attach the volume to an instance.

When you refresh the list of Block Storage volumes in the UI, the new volume appears at the beginning of the list of volumes with "customer managed" as the encryption type. When the volume is created, it shows a status of Available. For stand-alone volumes, the Attachment Type column is blank (-). The Action menu (...) at the end of a table row provides a link for attaching a Block Storage volume to an instance.

Creating data volumes with customer-managed encryption from the CLI

Prerequisites

Before you can use the CLI, you must install the IBM Cloud CLI and the VPC CLI plug-in. For more information, see the CLI prerequisites.

Log in to the IBM Cloud.
```
ibmcloud login --sso -a cloud.ibm.com
```
This command returns a URL and prompts for a passcode. Go to that URL in your browser and log in. If successful, you get a one-time passcode. Copy this passcode and paste it as a response on the prompt. After successful authentication, you are prompted to choose your account. If you have access to multiple accounts, select the account that you want to log in as. Respond to any remaining prompts to finish logging in.
Select the current generation of VPC.
```
ibmcloud is target --gen 2
```

Gather required information, such as the CRN of the root key that you want to use to encrypt your block storage volume.

Use the ibmcloud resource service-instances command to locate your KMS instances.

$ ibmcloud resource service-instances
Retrieving all instances of all services in resource group Default and all locations under account Test Account as test.user@ibm.com...
OK
Name             Location   State    Type
Key Protect-17   us-south   active   service_instance
HS-Crypto-60     us-south   active   service_instance

Retrieve the instance ID for the KMS instance with the ibmcloud resource service-instance command.

ibmcloud resource service-instance "Key Protect-17" --id
Retrieving service instance Key Protect-17 in resource group Default under account Test Account as test.user@ibm.com...
crn:v1:bluemix:public:kms:us-south:a/a1234567-3jkl4xxxx567::7mnxxxo8-91xx-23px-q4rs-xxtuv5w6xxx7

The instance ID is the string that follows the final :: in the CRN. In this example, it's 7mnxxxo8-91xx-23px-q4rs-xxtuv5w6xxx7.

List the available keys and their associated CRNs for the Key Protect service instance by specifying the instance ID.

$ ibmcloud kp keys -c --instance-id 7mnxxxo8-91xx-23px-q4rs-xxtuv5w6xxx7
Retrieving keys...
       
SUCCESS
            
Key ID                                 Key Name               CRN
ef1gxxxh-ijxx-234x-56k7-xxxxlmnoxxp8   test-key               crn:v1:bluemix:public:kms:us-south:a/a1234567:key:ef1gxxxh-ijxx-234x-56k7-xxxxlmnoxxp8
cdex12ef-xxxg-3hxx-i456-7xxx8jk9xl12   vsi_encrypt_root_key   crn:v1:bluemix:public:kms:us-south:a/a1234567:key:cdex12ef-xxxg-3hxx-i456-7xxx8jk9xl12
c12xxxx3-45d6-7efg-xxx8-9xxx12345x6h   vsi_encrypt_key        crn:v1:bluemix:public:kms:us-south:a/a1234567:key:c12xxxx3-45d6-7efg-xxx8-9xxx12345x6h

Create data volumes with customer-managed encryption from the CLI

To create a Block Storage volume with customer-managed encryption from the CLI, first gather the use the ibmcloud is volume-create command with the --encryption-key option. The encryption_key option specifies a valid CRN for the root key in the key management service.

The following example shows a volume that is created with customer-managed encryption.

$ ibmcloud is volume-create demo-cli-volume custom us-east-1 --capacity 300 --iops 1500 --encryption-key crn:v1:bluemix:public:kms:us-east:a/a1234567:3b05b403-8f51-4dac-9114-c777d0a760d4:key:7a8a2761-08e3-455f-a348-144ed604bba9
Creating volume demo-cli-volume under account Test Account as user test.user@ibm.com...
                                          
ID                                     r014-3984600c-6f4d-4940-82de-519a867fa3c0   
Name                                   demo-cli-volume   
CRN                                    crn:v1:bluemix:public:is:us-east-1:a/a1234567::volume:r014-3984600c-6f4d-4940-82de-519a867fa3c0   
Status                                 pending   
Attachment state                       unattached   
Capacity                               300   
IOPS                                   1500   
Bandwidth(Mbps)                        3145   
Profile                                custom   
Encryption key                         crn:v1:bluemix:public:kms:us-east:a/a1234567:3b05b403-8f51-4dac-9114-c777d0a760d4:key:7a8a2761-08e3-455f-a348-144ed604bba9   
Encryption                             user_managed   
Resource group                         defaults   
Created                                2023-06-29T20:10:52+00:00   
Zone                                   us-east-1   
Health State                           inapplicable   
Volume Attachment Instance Reference   -   
Active                                 false   
Unattached capacity update supported   false   
Unattached iops update supported       false   
Busy                                   false   
Tags                                   -

You can also create volumes with customer-managed encryption during instance provisioning.

Creating data volumes with customer-managed encryption with the API

You can create data volumes with customer-managed encryption programmatically by calling the /volumes method in the VPC API as shown in the following sample request. Use the encryption_key property to specify your customer root key (CRK), shown in the example as crn:[...key:...].

The following example creates a general-purpose data volume with customer-managed encryption.

curl -X POST \
"$vpc_api_endpoint/v1/volumes?version=2022-06-22&generation=2" \
-H "Authorization: $iam_token" \
-d '{
      "name": "my-volume-1",
      "iops": 100,
      "capacity": 20,
      "zone": {"name": "us-south-3"},
      "profile": {"name": "general-purpose"},
      "encryption_key":{"crn":"crn:[...key:...]"},
      "resource_group": {"id": "a342dbfb-3ea7-48d1-96e8-2825ec5feab4"}
    }

A successful response looks like the following example.

{
    "id": "8948ad59-bc0f-7510-812f-5dc64f59fab8",
    "crn": "crn:[...]",
    "name": "my-volume-1",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/8948ad59-bc0f-7510-812f-5dc64f59fab8",
    "capacity": 20,
    "iops": 100,
    "encryption_key": {"crn": "crn:[...key:...]"},
    "encryption": "user_managed",
    "status": "available",
    "zone": {
        "name": "us-south-3",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/
         us-south-3"
    },
    "profile": {
        "name": "general-purpose",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose"
    },
    "resource_group": {
        "id": "a342dbfb-3ea7-48d1-96e8-2825ec5feab4",
        "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/
         a342dbfb-3ea7-48d1-96e8-2825ec5feab4",
        "name": "Default"
    },
    "volume_attachments": [],
    "created_at": "2022-06-26T16:03:22.000Z"
}

Provisioning virtual server instances with storage volumes that are encrypted with customer-managed keys in the UI

When you provision a virtual server instance, you can specify customer-managed encryption for your boot volume and any data volumes that you want to add at that time. If you want, you can use a combination of provider-managed encryption and customer-managed encryption for the volumes that are associated with your instance.

Follow these steps to create an instance with a new Block Storage volume.

In IBM Cloud console, click the Navigation Menu icon > VPC Infrastructure > Compute > Virtual server instances.
Click New instance and complete the required fields. For more information about these required fields, see Table 1 - Instance provisioning selections in Creating virtual server instances.

In the Boot volume section, the default mode of encryption is Provider managed encryption. To specify customer-managed encryption, click the pencil icon in the boot volume row. On the Edit boot volume page, update the fields in the Encryption section.

Table 2. Values for specifying customer-managed encryption of volumes
Field	Value
Encryption	Provider managed is the default encryption mode. To use customer-managed encryption, select a key management service.
Encryption service instance	If you have multiple key management service instances that are provisioned in your account, select the one that contains the customer root key that you want to use.
Key name	Select the root key within the key management service instance that you want to use for encrypting the volume.
Key ID	Displays the key ID that is associated with the root key that you selected.

When your changes are complete, click Apply.
In the Attached Block Storage volume section, you can click New Block Storage volume to add a data volume and specify customer-managed encryption. On the New Block Storage volume page, update the fields in the Encryption section. See Table 1 for more information. When your changes are complete, click Attach.

Provisioning instances with customer-managed encrypted volumes from the CLI

Use the ibmcloud is instance-create command to create an instance with customer-managed encryption for your boot and data volumes. The following syntax shows that you can specify the --boot-volume and --volume-attach properties to include JSON files that define your volumes.

ibmcloud is instance-create INSTANCE_NAME VPC ZONE_NAME PROFILE_NAME SUBNET --image-id IMAGE_ID [--boot-volume @BOOT_VOLUME_JSON_FILE] [--volume-attach @VOLUME_ATTACH_JSON_FILE]...

The following BOOT_VOLUME_JSON_FILE example defines the properties of the boot volume. The encryption key property contains the root key's CRN for customer-managed encryption.

{  
   "name":"volume-attachment-1",
   "volume":{  
      "name":"boot-volume-1",
      "capacity":250,
      "profile":{"name":"general-purpose"},
      "encryption_key":{"crn":"crn:[...key:...]"}
   },
   "delete_volume_on_instance_delete":true
}

The VOLUME_ATTACH_JSON_FILE example defines a general-purpose data volume with customer-managed encryption.

   {  
      "name":"volume-attachment-1",
      "volume":{  
         "name":"data-volume-1",
         "capacity":2000,
         "profile":{"name":"general-purpose"},
         "encryption_key":{"crn":"crn:[...key:...]"}
      },
      "delete_volume_on_instance_delete":true
   }

Provisioning instances with customer-managed encryption volumes with the API

You can create virtual server instances with boot volumes that use customer-managed encryption programmatically by calling the /instances method in the VPC API as shown in the following sample request. Use the encryption_key property to specify your customer root key (CRK), shown in the example as crn:[...key:...].

The following example creates an instance with a boot volume with customer-managed encryption and two secondary volumes with customer-managed encryption.

curl -X POST \
 "$vpc_api_endpoint/v1/instances?version=version=2020-03-10&generation=2" \
 -H "Authorization: $iam_token" \
 -d '{
     "boot_volume_attachment":{
           "volume": {
              "name":"boot-volume-1",
              "profile": {"name": "general-purpose"},
              "encryption_key": {"crn": "crn:[...key:...]"}}},
     "volume_attachments": [
            {"volume": {
              "name": "my-volume-1",
              "capacity": 1500,
              "profile": {"name": "general-purpose"},
              "encryption_key": {"crn": "crn:[...key:...]"}}},
            {"volume": {
              "name": "my-volume-2",
              "capacity": 2000,
              "profile": {"name": "general-purpose"},
              "encryption_key": {"crn": "crn:[...key:...]"}}}],
     "image": {"id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366"},
     "keys": [{"id": "cf7678a3-d4fa-458b-993d-015bd4aeac80"}],
     "name": "my-test-vm2",
     "virtual_network_interface": {"subnet": {"id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4"}},
     "profile": {"name": "cx2-2x4"},
     "vpc": {"id": "f0aae929-7047-46d1-92e1-9102b07a7f6f"},
     "zone": {"name": "us-south-3"}
    }'

A successful response looks like this. Note that the boot volume appears under both boot_volume_attachment and volume_attachment.

{
    "id": "eb1b7391-2ca2-4ab5-84a8-b92157a633b0",
    "crn": "crn:[...]",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/eb1b7391-2ca2-4ab5-84a8-
     b92157a633b0",
    "name": "my-test-vm2",
    "bandwidth": 4000,
    "resource_group": {
        "id": "08b7af6d-41d9-435a-8b22-fd8f640863a5",
        "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/
         08b7af6d-41d9-435a-8b22-fd8f640863a5",
        "name": "Default"
    },
    "boot_volume_attachment": {
        "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/eb1b7391-2ca2-4ab5-
         84a8-b92157a633b0/volume_attachments/7389-a8a15363-a6f7-4f01-af60-
         715e85b28141",
        "name": "volume-attachment",
        "volume": {
            "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
            "crn": "crn:[...]",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/49c5d61b-41e7-
             4c01-9b7a-1a97366c6916",
            "name": "boot-volume-1"
        }
    },
    "created_at": "2020-04-20T16:11:57Z",
    "image": {
        "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
        "crn": "crn:[...]",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/images/
         9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
        "name": "ubuntu-amd64-1"
    },
    "memory": 4,
    "network_interfaces": [
        {
            "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-
             4aa2-a8d7-703aac843651/network_interfaces/7ca88dfb-8962-469d-b1de-
             1dd56f4c3275",
            "name": "helpless-profanity-unmixable-fool-hazard-staging",
            "primary_ipv4_address": "",
            "subnet": {
                "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
                "crn": "crn:[...]",
                "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7389-bea6a632-
                 5e13-42a4-b4b8-31dc877abfe4",
                "name": "my-byok-vpc-subnet"
            }
        }
    ],
    "primary_network_interface": {
        "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-4aa2-
         a8d7-703aac843651/network_interfaces/7ca88dfb-8962-469d-b1de-1dd56f4c3275",
        "name": "network-interface-1",
        "primary_ipv4_address": "10.0.0.32",
        "subnet": {
            "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
            "crn": "crn:[...]",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/bea6a632-5e13-
             42a4-b4b8-31dc877abfe4",
            "name": "my-byok-vpc-subnet"
        }
    },
    "profile": {
        "name": "cx2-2x4",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/cx2-2x4"
    },
    "status": "running",
    "vcpu": {
        "architecture": "amd64",
        "count": 2
    },
    "volume_attachments": [
        {
            "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-
             4aa2-a8d7-703aac843651/volume_attachments/7389-a8a15363-a6f7-4f01-af60-
             715e85b28141",
            "name": "volume-attachment",
            "volume": {
                "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
                "crn": "crn:[...]",
                "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/49c5d61b-41e7-
                 4c01-9b7a-1a97366c6916",
                "name": "boot-volume-1"
            }
        },
        {
            "id": "e77125cb-4df0-4988-a878-531ae0ae0b70",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-
             4aa2-a8d7-703aac843651/volume_attachments/7389-e77125cb-4df0-4988-a878-
             531ae0ae0b70",
            "name": "volume-attachment",
            "volume": {
                "id": "2cc091f5-4d46-48f3-99b7-3527ae3f4392",
                "crn": "crn:[...]",
                "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/2cc091f5-4d46-
                 48f3-99b7-3527ae3f4392",
                "name": "my-volume-2"
            }
        },
        {
            "id": "a7641494-5724-46de-9c72-c6b16971ddf4",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-
             4aa2-a8d7-703aac843651/volume_attachments/a7641494-5724-46de-9c72-
             c6b16971ddf4",
            "name": "volume-attachment",
            "volume": {
                "id": "ec419496-d79e-4fca-bce7-b4be72e77654",
                "crn": "crn:[...]",
                "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/ec419496-d79e-
                 4fca-bce7-b4be72e77654",
                "name": "my-volume-2"
            }
        }
    ],
    "vpc": {
        "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f",
        "crn": "crn:[...]",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-
         9102b07a7f6f",
        "name": "my-byok-vpc"
    },
    "zone": {
        "name": "us-south-3",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/
         us-south-3"
    }
}

Next steps

After the instance is created with the encrypted boot and data volumes, associate a floating IP address to the instance that you can use to connect to your instance. For more information, see Connecting to your Linux instance or Connecting to your Windows instance.
Prepare your data volumes for use by formatting and configuring them to meet your requirements.
- Setting up your Block Storage for VPC data volume for use (Linux)
- Setting up your Block Storage for VPC data volume for use (Windows)
Attach your stand alone volumes to a virtual server instance.
Configure Key rotation for VPC resources.