Creating data volumes with customer-managed encryption in the console

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

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

2. Click Create.

3. Review the Location information. 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 Edit icon .

4. In the Details, 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.

   1. Specify a meaningful name for your volume. For example, provide a name that describes your compute or workload function.

      The volume name must begin with a lowercase letter. The volume name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-). Volume names must be unique across the entire VPC infrastructure. You can edit the name later.

   2. Specify a Resource group.

   3. Specify user tags to organize your resources and for use by backup policies.

   4. Specify access management tags that were created in IAM to help you manage access to your volumes.

5. In the Optional configurations 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: select Import existing snapshot to see the list of available snapshots, or Import snapshot by CRN and provide the CRN of the snapshot that you want to use. You can create data volumes with Nonbootable snapshots, and boot volumes with Bootable snapshots. The new block storage volume inherits its storage generation value from the snapshot and only volume profiles of the same generation can be applied to it.
   • Apply backup policy: click Apply to see available policies and plans.

6. In the Profile section, you can specify the performance profile of your volume, its IOPS, and capacity.

   • You can select the sdp profile. Then, specify the capacity of your volume and the required IOPS. Volume size can range from 1 - 32,000 GB. You can specify IOPS in the range of 100 - 64,000. You can also specify a custom throughput limit.
   • You can select one of the tiered profiles. After you select general-purpose, 5iops-tier, or 10iops-tier, the next step is to specify the volume capacity. Volume sizes can be 10 - 16,000 GB.
   • You can select the custom profile if your application performance requirements don't fall within any of the IOPS tiers. Then, specify the size of your volume and the IOPS in the appropriate range for the volume capacity. Volume sizes can be 10 - 16,000 GB. As you type the IOPS value, the UI shows the acceptable range. You can also click the storage size link to see the size and IOPS ranges of the custom volume profile.

7. In the Encryption at rest section, you can choose to keep the encryption with IBM-managed keys that is enabled by default on all volumes. Or you can choose to use your own encryption key. To change the key or instance, click the Edit icon to open the Configure encryption side panel. Select one of the following options to locate your encryption key:

   • Locate by Instance: The panel has three steps:
     1. Select KMS instance: The list shows the name, ID, type (Standard or Dedicated), and location of each available Key Protect instance. Select an instance and click Select. If you don't have an instance yet, click Create to provision one.
     2. Associate key: The list shows the name, ID, last updated date, aliases, and key ring of each available root key. Select a key and click Select. If you don't have a key yet, click Create new key.
     3. Review: Confirm your selections, including the key management service, instance type, instance name, and key name. The Service authorization section shows whether the required authorization between Block Storage for VPC and the KMS instance is already in place. If it is not, you can allow Key Protect to create the authorization automatically, or create one manually. For more information, see Establishing service-to-service authorizations for Block Storage for VPC. Click Confirm to apply your selection and return to the volume provisioning page.
   • Locate by CRN: Enter the CRN of the customer root key to be used for encrypting the volume. Choose this option if you're using the CRK of another account. Click Select to proceed to the Review step described in the Locate by Instance option.

8. When your changes are complete, click Create block storage volume.

When you refresh the list of Block Storage volumes in the console, the new volume appears at the beginning of the list of volumes with the customer-managed encryption type. When the volume is created, it shows a status of Available. For stand-alone volumes, the Attachment Type column is blank (-). The Actions 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

ibmcloud is volume-create my-customer-key-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 my-customer-key-volume under account Test Account as user test.user@ibm.com...

ID                                     r014-3984600c-6f4d-4940-82de-519a867fa3c0
Name                                   my-customer-key-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                                2024-09-24T20:10:52+00:00
Zone                                   us-east-1
Health State                           inapplicable
Volume Attachment Instance Reference   -
Active                                 false
Adjustable Capacity States             attached
Adjustable IOPS State                  attached
Busy                                   false
Tags                                   -
Storage Generation                     1

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:...].

Valid volume names can include a combination of lowercase alpha-numeric characters (a-z, 0-9) and the hyphen (-), up to 63 characters. Volume names must begin with a lowercase letter. Volume names must be unique across the entire VPC infrastructure.

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

curl -X POST \
"$vpc_api_endpoint/v1/volumes?version=2025-02-18&generation=2" \
-H "Authorization: Bearer $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"
    },
    "storage_generation": 1,
    "volume_attachments": [],
    "created_at": "2025-02-18T16:03:22.000Z"
}

Provisioning an instance with a boot volume that is encrypted with a customer-managed key in the console

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

1. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Compute > Virtual server instances.

2. Click New instance and complete the required fields. For more information, see Creating virtual server instances.

3. In the Boot volume section, four capacity tiles are shown. For most compute profiles, 100 GB is preselected. Click the Edit icon on the Custom tile to open the Edit boot volume side panel.

   If you selected a second-generation snapshot to create the volume, your volume's encryption type must match the snapshot's encryption type. If the snapshot has provider-managed keys, do not specify a key from a key management service.

   1. In the Edit boot volume side panel, you can update the volume name and configure the following settings. The resource group and zone are shown for reference and cannot be changed.
      • Auto-delete: Enabled by default. Toggle to disable if you want the volume to persist after the instance is deleted.
      • Tags: Optionally add user tags to the volume.
   2. In the Encryption card, provider-managed encryption is enabled by default. To use your own encryption key, click the toggle to enable customer-managed encryption. If you already have a KMS instance and root key, the system autoselects it for you, showing the key management service instance name and key name. To change the selection, click Edit to open the Configure encryption side panel. Select one of the following options to locate your encryption key:
      • Locate by Instance: The panel has three steps:
        1. Select KMS instance: The list shows the name, ID, type (Standard or Dedicated), and location of each available Key Protect instance. Select an instance and click Select. If you don't have an instance yet, click Create to provision one.
        2. Associate key: The list shows the name, ID, last updated date, aliases, and key ring of each available root key. Select a key and click Select. If you don't have a key yet, click Create new key.
        3. Review: Confirm your selections, including the key management service, instance type, instance name, and key name. The Service authorization section shows whether the required authorization between Block Storage for VPC and the KMS instance is already in place. If it is not, you can allow Key Protect to create the authorization automatically, or create one manually. For more information, see Establishing service-to-service authorizations for Block Storage for VPC. Click Confirm to apply your selection and return to the Edit boot volume side panel.
      • Locate by CRN: Enter the CRN of the customer root key to be used for encrypting the volume. Choose this option if you're using the CRK of another account. Click Select to proceed to the Review step described in the Locate by Instance option.
   3. When your changes are complete, click Save to return to the instance provisioning page.

4. In the Data volumes section, you can click Create to add a data volume and specify customer-managed encryption. On the Create data volume page, update the required fields and click the toggle in the Encryption section. When your changes are complete, click Attach.

Provisioning an instance with a boot volume that is encrypted with a customer-managed key 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 how 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 following VOLUME_ATTACH_JSON_FILE example defines a data volume with the 10iops-tier profile and customer-managed encryption.

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

Provisioning an instance with a boot volume that is encrypted with a customer-managed key 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: Bearer $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 the following example. 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"
    }
}

Creating data volumes with customer-managed encryption with Terraform

provider "ibm" {
  region = "eu-de"
}

resource "ibm_is_volume" "example" {
  name           = "my-example-volume"
  profile        = "custom"
  zone           = "us-south-1"
  iops           = 1000
  capacity       = 200
  encryption_key = "crn:v1:bluemix:public:kms:us-south:a/a1234567:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179"
}