Creating Block Storage for VPC volumes

Creating and attaching a Block Storage for VPC volume when you create an instance

1. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Compute > Virtual server instances.
2. From the list of virtual server instances, click Create.
3. In the Virtual server for VPC provisioning page, select Server type, Location, OS, Profile, Placement Group, and so on. For more information about provisioning the instance, see Creating a virtual server instance with the UI.
4. The details of the boot volume that is to be created are displayed on the page. You can edit the boot volume by clicking the Edit icon to change the size, specify encryption, and add any user tags to identify this resource.
5. To create a data volume and attach it to the instance, in the Data volumes section of the instance provisioning page, click Create. In the side panel, specify the volume details.
   1. You have the option to import data from a snaphot by clicking the Import from snapshot toggle. Select an available snapshot from the list, or locate the snapshot by its CRN.
   2. Specify a unique, meaningful name for your volume. For example, it can be a name that describes your compute or workload function. The volume name must begin with a lowercase letter. The name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-). Volume names must be unique the entire VPC infrastructure. You can edit the name later if you want.
   3. Auto-delete feature is disabled by default. If you want the volume to be deleted when the attached virtual server instance is deleted, click the toggle to enable the feature.
   4. Resource group and location are inherited from the instance. These values can't be changed.
   5. You can specify optional user tags to associate with this volume. For more information about organizing resources with user tags, see Working with tags.
   6. Select the encryption type. Provider-managed encryption is enabled by default on all volumes. You can also choose to create an envelop encryption with your own root keys. Encryption keys are created and maintained in Key Management Services (Key Protect or Hyper Protect Crypto Services). For more information, see Prerequisites for setting up customer-managed encryption.
   7. Click Next.
   8. Select the storage profile.
      • For IOPS tiers, select the tile with the performance level that you require and specify the volume size in GBs. Volume size 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. Volume size 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 table that contains the size and IOPS ranges of the custom volume profile.
   9. Click Save.
6. You return to the virtual instance provisioning page to finish defining the remaining attributes of your virtual server instance.
7. When you are satisfied with your choices, click Create virtual server.

A Block Storage for VPC volume can be attached to only one virtual server at a time. On the Block Storage for VPC volume summary page, you can view details about the virtual server instance by selecting the instance name under Attached instances.

Creating and attaching a Block Storage for VPC volume from an existing instance

You can create a Block Storage for VPC volume from an existing instance.

1. Go to the list of virtual server instances. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Compute > Virtual server instances.
2. Select an instance from the list.
3. On the instance details page, scroll to Storage volumes and click Attach.
4. In the side panel, click the down arrow under Block volumes and select Create a data volume. The side panel expands with fields to define the volume.
   1. If you created volume snapshots previously, the option to import one becomes available. Click the toggle to Import from snapshot, and select a snapshot from the list or locate the snapshot by its CRN.
   2. Specify a unique, meaningful name for your volume. For example, it can be a name that describes your compute or workload function. The volume name must begin with a lowercase letter. The name can be up to 63 lowercase alpha-numeric characters and include the hyphen (-). Volume names must be unique the entire VPC infrastructure. You can edit the name later if you want.
   3. Auto-delete feature is disabled by default. If you want the volume to be deleted when the attached virtual server instance is deleted, click the toggle to enable the feature.
   4. Resource group and location are inherited from the instance. These values can't be changed.
   5. You can specify optional user tags to associate with this volume. For more information about organizing resources with user tags, see Working with tags.
   6. Select the encryption type. Provider-managed encryption is enabled by default on all volumes. You can also choose to create an envelop encryption with your own root keys. Encryption keys are created and maintained in Key Management Services (Key Protect or Hyper Protect Crypto Services).
   7. Click Next.
   8. Select the storage profile.
      • For IOPS tiers, select the tile with the performance level that you require and specify the volume size in GBs. Volume size 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 the table that contains the size and IOPS ranges of the custom volume profile.
   9. Click Save.
5. When you're finished defining the volume, click Save. The volume is created and attached to the instance. You're returned to the instance details page. The new volume is shown in the list of storage volumes.

Creating a stand-alone Block Storage for VPC volume

You can create a Block Storage for VPC volume independent of virtual server provisioning and attach the volume to an instance later.

1. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.
2. Click Create.
3. On the Block Storage for VPC provisioning page, 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 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.

   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. For more information, see Create a stand-alone Block Storage for VPC volume from a snapshot. Also, you can choose to apply a 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.
   • For IOPS tiers, select the tile with the performance level that you require and specify the volume size in GBs. Volume size 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 the table that contains 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 by selecting your key management service: Key Protect or Hyper Protect Crypto Services. To locate your encryption key, select one of the following options:
   • Locate by Instance:
     1. Select the data encryption instance from the list. If you don't have an instance yet, you can click the link to create one.
     2. Select the data encryption key that is stored within the Key Protect instance to use for encrypting the volume.
   • Locate by CRN: enter the CRN of the customer root key to be used for encrypting the volume.
8. When you're finished, click Create block storage volume.
   • If you're not ready to order yet or just looking for pricing information, you can add the information that you see in the side panel to an Estimate. For more information about how this feature works, see Estimating your costs.
9. You're returned to the Block Storage for VPC volumes page, where a message indicates that the volume is being created (volume status is pending). A second message displays when the volume is created (volume status is available).
10. To see details of the new volume, select the View resource link in the second message to go to the Volume details page.

When you refresh the list of Block Storage volumes in the console, the new volume appears at the beginning of the list of volumes. 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 a stand-alone Block Storage for VPC volume from a snapshot in the console

When you create a Block Storage for VPC volume, you can select a snapshot and use its data to create the new volume. The snapshots that are presented are in a stable state. The data volume that is created from the snapshot is not attached to an instance and appears in the list of Block Storage for VPC volumes. You can later attach the volume to an instance.

You can restore a boot volume from a "bootable" snapshot. The boot volume is restored when you create a virtual server instance.

1. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.
2. Select Create.
3. Specify the location of the volume, volume name, optional resource group and tags.
4. In the Optional configurations section, click Import from snapshot. Select one of the following options
   • Click Import existing snapshot to see the list of available snapshots. All snapshots that are presented are in a stable state. By default, the Nonbootable tab is selected that lists all data volume snapshots. To restore a boot volume, click the Bootable tab. Attach volume to new virtual server instance is selected by default. The boot volume is restored when the instance is created.
   • Click Import snapshot by CRN and provide the CRN of the snapshot that you want to use.
5. Click Save. Information about the snapshot is shown on the volume provisioning page, including the name, its size, the date when it was created, its source volume, and whether it is a bootable snapshot. Bootable snapshot information includes the operating system and image. The encryption is inherited from the snapshot and shown in the encryption section.
6. Click Create block storage volume.

Before you begin

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.

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

Creating a Block Storage for VPC volume from the CLI

Run the following command to create a Block Storage for VPC volume. Provide a volume name, profile name, and the name of the availability zone in your region. For more information about Block Storage for VPC profiles, see Profiles. Extra options are shown in brackets.

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. For example, if you create two volumes with the same name in the same account and region, a volume name duplicate error is triggered.

ibmcloud is volume-create VOLUME_NAME PROFILE_NAME ZONE_NAME [--capacity CAPACITY] [--iops IOPS] [--resource-group-id RESOURCE_GROUP_ID | --resource-group-name RESOURCE_GROUP_NAME] [--tags  TAG_NAME1,TAG_NAME2,...] [--json]

See the following example.

$ ibmcloud is volume-create demovolume1 custom us-east-1 --capacity 500 --iops 3000 --tags env:test,env:prod
Creating volume demovolume1 in resource group Default under account VPC 01 as user rtuser1@mycompany.com...

ID                                     r014-e45f9c8c-4655-4a3e-9d90-70c2d64d1746   
Name                                   demovolume1   
CRN                                    crn:v1:bluemix:public:is:us-east-1:a/a1234567::volume:r014-e45f9c8c-4655-4a3e-9d90-70c2d64d1746   
Status                                 pending   
Attachment state                       unattached   
Capacity                               500   
IOPS                                   3000   
Bandwidth(Mbps)                        6291   
Profile                                custom   
Encryption key                         -   
Encryption                             provider_managed   
Resource group                         defaults   
Created                                2023-07-24T16:20:52+00:00   
Zone                                   us-east-1   
Health State                           inapplicable   
Volume Attachment Instance Reference   -   
Active                                 false   
Busy                                   false   
Tags                                   env:test,env:prod 

Capacity, indicated in megabytes, can range from 10 - 16,000 GBs. If not specified, the default capacity is 100 GBs. IOPS values can be 100 - 48,000 IOPS, depending on the profile and volume size. If not specified, the IOPS value defaults to the valid configuration per volume profile. For more information, see the table of custom IOPS.

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.

Note the volume ID. You need to specify the ID when you attach Block Storage for VPC to a virtual server instance, view Block Storage for VPC volume details, or delete volumes.

The volume health state shows inapplicable while the volume status is pending. After the volume is created, the health state shows OK, unless the creation failed. For more information, see Block Storage for VPC volume health states.

User tags are added to identify the volume resource. When these tags are matched with the tags in a backup policy, the volume is backed up according to the schedule in the backup plan. For more information, see Creating a backup policy.

Creating a stand-alone Block Storage for VPC volume with customer-managed encryption from the CLI

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

ibmcloud is volume-create VOLUME_NAME PROFILE_NAME ZONE_NAME [--encryption-key ENCRYPTION_KEY] [--capacity CAPACITY] [--iops IOPS] [--resource-group-id RESOURCE_GROUP_ID | --resource-group-name RESOURCE_GROUP_NAME] [--output JSON]

The following example shows a volume with custom IOPS and capacity 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
Busy                                   false   
Tags                                   - 

Creating a stand-alone Block Storage for VPC volume from a snapshot from the CLI

Run the ibmcloud is volume-create command and specify the --snapshot option with the name, ID, or CRN of the snapshot you're using to create the new volume. The volume is unattached, as indicated by the attachment state in the response.

This example creates the new volume from a snapshot that is specified by name.

$ ibmcloud is volume-create volume-4 general-purpose us-east-1 --snapshot snapshot-3
Creating volume volume-4 under account Test Account as user test.user@ibm.com...

ID                                     r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac
Name                                   volume-4
CRN                                    crn:v1:bluemix:public:is:us-east-1:a/a1234567::volume:r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac
Status                                 pending
Attachment state                       unattached
Capacity                               100
IOPS                                   3000
Bandwidth(Mbps)                        393
Profile                                general-purpose
Encryption key                         -
Encryption                             provider_managed
Resource group                         defaults
Created                                2023-06-29T16:14:59+00:00
Zone                                   us-east-1
Health State                           inapplicable
Volume Attachment Instance Reference   -
Active                                 false
Busy                                   false
Tags                                   -

For more information, see ibmcloud is volume-create in the CLI reference.

Before you begin

Define variables for the IAM token, API endpoint, and API version. For instructions, see Setting up your API and CLI environment.

Creating a data volume as part of instance provisioning with the API

Make a POST /instances request to create an instance, and define the volume by using the volume_attachments parameter. Specify a volume name, capacity, and profile. Also, specify generation=2 in the request.

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. For example, if you create two volumes with the same name in the same account and region, a volume name duplicate error is triggered.

This example specifies customer-managed encryption and user tags for the boot and data volumes.

curl -X POST "$vpc_api_endpoint/v1/instances?version=2022-06-14&generation=2" -H "Authorization: $iam_token" -d '{
  "boot_volume_attachment": {
    "volume": {
      "encryption_key": {"crn": "crn:[...]"},
      "name": "my-boot-volume",
      "profile": {"name": "general-purpose"},
      "user_tags": {"env:test","env:prod"}}},
  "image": {"id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366"},
  "keys": [{"id": "363f6d70-0000-0001-0000-00000013b96c"}],
  "name": "my-instance",
  "placement_target": {"id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221"},
  "primary_network_interface": {
    "name": "my-network-interface",
    "subnet": {"id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4"}},
  "profile": {"name": "bx2-2x8"},
  "volume_attachments": [
    {"volume": {
        "capacity": 1000,
        "encryption_key": {"crn": "crn:[...]"},
        "name": "my-data-volume",
        "profile": {"name": "5iops-tier"},
        "user_tags": {"env:test","env:prod"}}
    }],
  "vpc": {"id": "f0aae929-7047-46d1-92e1-9102b07a7f6f"},
  "zone": {"name": "us-south-1"}
}'

A successful response looks like this:

{
  "bandwidth": 4000,
  "boot_volume_attachment": {
    "device": {
      "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",
    "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
    "name": "my-boot-volume-attachment",
    "volume": {
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/49c5d61b-41e7-4c01-9b7a-1a97366c6916",
      "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
      "name": "my-boot-volume"
    }
  },
  "created_at": "2022-06-15T16:11:57Z",
  "crn": "crn:[...]",
  "dedicated_host": {
    "crn": "crn:[...]",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221",
    "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221",
    "name": "test-new",
    "resource_type": "dedicated_host"
  },
  "disks": [],
  "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/eb1b7391-2ca2-4ab5-84a8-b92157a633b0",
  "id": "eb1b7391-2ca2-4ab5-84a8-b92157a633b0",
  "image": {
    "crn": "crn:[...]",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/images/9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
    "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
    "name": "my-image"
  },
  "memory": 8,
  "name": "my-instance",
  "network_interfaces": [
    {
      "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-4aa2-a8d7-703aac843651/network_interfaces/7ca88dfb-8962-469d-b1de-1dd56f4c3275",
      "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
      "name": "my-network-interface",
      "primary_ipv4_address": "10.0.0.32",
      "resource_type": "network_interface",
      "subnet": {
        "crn": "crn:[...]",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7389-bea6a632-5e13-42a4-b4b8-31dc877abfe4",
        "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
        "name": "my-subnet"
      }
    }
  ],
  "placement_target": {
    "crn": "crn:[...]",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221",
    "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221",
    "name": "test-new",
    "resource_type": "dedicated_host"
  },
  "primary_network_interface": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-4aa2-a8d7-703aac843651/network_interfaces/7ca88dfb-8962-469d-b1de-1dd56f4c3275",
    "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
    "name": "my-network-interface",
    "primary_ipv4_address": "10.0.0.32",
    "resource_type": "network_interface",
    "subnet": {
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/bea6a632-5e13-42a4-b4b8-31dc877abfe4",
      "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
      "name": "my-subnet"
    }
  },
  "profile": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8",
    "name": "bx2-2x8"
  },
  "resource_group": {
    "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21",
    "id": "4bbce614c13444cd8fc5e7e878ef8e21",
    "name": "Default"
  },
  "status": "running",
  "status_reasons": [],
  "vcpu": {
    "architecture": "amd64",
    "count": 2
  },
  "volume_attachments": [
    {
      "device": {
        "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",
      "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
      "name": "my-boot-volume-attachment",
      "volume": {
        "crn": "crn:[...]",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/49c5d61b-41e7-4c01-9b7a-1a97366c6916",
        "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
        "name": "my-boot-volume"
      }
    },
    {
      "device": {
        "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",
      "id": "e77125cb-4df0-4988-a878-531ae0ae0b70",
      "name": "my-volume-attachment-1",
      "volume": {
        "crn": "crn:[...]",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/2cc091f5-4d46-48f3-99b7-3527ae3f4392",
        "id": "2cc091f5-4d46-48f3-99b7-3527ae3f4392",
        "name": "my-data-volume"
      }
    }
  ],
  "vpc": {
    "crn": "crn:[...]",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f",
    "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f",
    "name": "my-vpc"
  },
  "zone": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
    "name": "us-south-1"
  }
}

Creating a stand-alone Block Storage for VPC volume with the API

Make a POST /volumes request to create a volume. Specify a name, IOPS, capacity, the profile, and zone. Also, specify generation=2 in the request.

The following example created a custom volume with 50 MB capacity and 100 IOPS in the us-south region. The request also specifies a customer root key for customer-managed encryption and a resource group.

curl -X POST "$vpc_api_endpoint/v1/volumes?version=2022-06-14&generation=2" \
-H "Authorization: $iam_token" \
-d '{
      "name": "my-volume-4",
      "iops": 100,
      "capacity": 50,
      "zone": {"name": "us-south-2"},
      "profile": {"name": "custom"},
      "encryption_key":{"crn":"crn:[...]"},
      "resource_group": {"id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054"}
    }'

A successful response looks like the following example.

{
  "capacity": 50,
  "created_at": "2022-06-14T23:16:53.000Z",
  "crn": "crn:[...]",
  "encryption": "user_managed",
  "encryption_key": {
    "crn": "crn:[...]"
  },
  "health_reasons": [],
  "health_state": "ok",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/2d1bb5a8-40a8-447a-acf7-0eadc8aeb054",
  "id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054",
  "iops": 100,
  "name": "my-volume-4",
  "profile": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/custom",
    "name": "custom"
  },
  "resource_group": {
    "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21",
    "id": "4bbce614c13444cd8fc5e7e878ef8e21",
    "name": "Default"
  },
  "status": "available",
  "status_reasons": [],
  "volume_attachments": [],
  "zone": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2",
    "name": "us-south-2"
  }
}

For more information about volume creation with the API, see Creating Block Storage volumes and the API reference for creating a volume.

Creating a data volume from a snapshot of an unattached volume with the API

You can specify a snapshot ID, name, or CRN in a POST /volumes call to create a stand-alone data volume.

Data is fully restored when you attach the data volume to a virtual server instance. For more information, see About restoring a volume from a snapshot. For an example API call, see Restoring a data volume from a snapshot of an unattached volume.

Creating stand-alone Block Storage for VPC volumes with Terraform

To create a Block Storage for VPC volume, use the ibm_is_volume resource. The following example creates a volume with 4 TB capacity and the 10iops-tier performance profile.

resource "ibm_is_volume" "example" {
  name     = "example-volume"
  profile  = "10iops-tier"
  zone     = "us-south-1"
  capacity = 4000
}

The following example creates a volume with a custom profile. The volume that is created has 200 MB capacity and can perform 1000 IOPS.

resource "ibm_is_volume" "example" {
  name           = "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"
}

For more information about the arguments and attributes, see ibm_is_volume.

Creating a stand-alone Block Storage for VPC volume from a snapshot with Terraform

To create a Block Storage for VPC volume from a snapshot, use the ibm_is_volume resource. The following example creates a volume based on a snapshot that is identified by its ID. You could also use the name or the CRN to identify the snapshot.

resource "ibm_is_volume" "storage" {
  name            = "example-volume"
  profile         = "general-purpose"
  zone            = "us-south-1"
  source_snapshot = ibm_is_snapshot.example.id
}

For more information about the arguments and attributes, see ibm_is_volume.

Creating a boot volume from a snapshot as part of instance provisioning with Terraform

To create a data volume from a snapshot when you create a virtual server instance, use the ibm_is_instance resource. The following example creates a virtual server instance with the name "example-vsi-restore". The boot volume is defined in the boot_volume argument with its name, its source snapshot, and user tags.

resource "ibm_is_snapshot" "example" {
  name          = "example-snapshot"
  source_volume = ibm_is_instance.example.volume_attachments[0].volume_id
}

resource "ibm_is_instance" "example" {
  name    = "example-vsi-restore"
  profile = "cx2-2x4"
  boot_volume {
    name     = "boot-restore"
    snapshot = ibm_is_snapshot.example.id
    tags     = ["tags-0"]
  }
  primary_network_interface {
    subnet = ibm_is_subnet.example.id
  }
  vpc  = ibm_is_vpc.example.id
  zone = "us-south-1"
  keys = [ibm_is_ssh_key.example.id]
  network_interfaces {
    subnet = ibm_is_subnet.example.id
    name   = "eth1"
  }
}

If you want to restore a volume from a snapshot of another account, you can use the source_snapshot_crn argument to identify the snapshot by its CRN, instead of its ID.

For more information about the arguments and attributes, see ibm_is_instance.

Creating a data volume to add to an existing instance with Terraform

To create a data volume and attach it to a virtual server instance, use the ibm_is_instance_volume_attachment resource. The following example creates a 20 MB data volume with a general-purpose volume profile and attaches it to the ibm_is_instance.example.id instance.

rresource "ibm_is_instance_volume_attachment" "example" {
  instance = ibm_is_instance.example.id

  name                               = "example-vol-att-1"
  profile                            = "general-purpose"
  capacity                           = "20"
  delete_volume_on_attachment_delete = true
  delete_volume_on_instance_delete   = true
  volume_name                        = "example-vol-1"
}

For more information about the arguments and attributes, see ibm_is_instance_volume_attachment.