IBM Cloud Docs
Attaching a Block Storage for VPC volume

Attaching a Block Storage for VPC volume

When you create a IBM® Cloud Block Storage for Virtual Private Cloud volume for a virtual server instance, the volume is attached to the instance by default. When you detach a volume, it exists as an unattached volume that you can later reattach. These available volumes are displayed in the list of all Block Storage for VPC volumes. You can attach the volume to another instance from the list of all Block Storage for VPC volumes, or when you view details about an instance.

Volume attachment limits

You can attach only one Block Storage for VPC boot volume to a virtual server instance at a time, but you can attach up to 12 Block Storage for VPC data volumes to a single instance.

When you create a Hyper Protect Virtual Servers for IBM Cloud® Virtual Private Cloud instance, only one data volume can be added currently. Even if you attach more volumes, they are not used by the instance.

You can't use the UI to attach Block Storage for VPC volumes to IBM Cloud® Kubernetes Service Cluster worker nodes. For more information about using the CLI to attach volumes to cluster nodes, see Storing data on Block Storage for VPC.

Attaching a Block Storage for VPC volume to a virtual server instance

You can attach a volume to a virtual server instance from the list of Block Storage volumes, volume details page, or from the instance details page.

Attaching a volume to an instance from the list of volumes

From the list of all Block Storage for VPC volumes, follow these steps.

  1. In the IBM Cloud console, click the Navigation Menu icon menu icon > VPC Infrastructure VPC icon > Storage > Block Storage volumes.
  2. In the list of volumes, identify an available, unattached volume and click the ellipsis for the overflow menu at the end of a row.
  3. Select Attach to instance.
  4. Select a virtual server instance from the list of available instances, and then click Save. If the list shows no virtual server instances, click Create server to go to the instance provisioning page.
  5. Messages display on the volume details page to indicate that the volume is being attached to the image. When it completes, the image name appears under Attached instances.

When you create a Hyper Protect Virtual Servers instance and the contract mentions volumes, you have 15 minutes after the creation of the instance to attach a data volume. Failure to do so causes the instance to go into a shutdown state after the 15-minute window.

Attaching a volume to an instance from the volume details page

From the volume details page, follow these steps:

  1. Select an unattached volume from the list of Block Storage volumes.
  2. From the volume details page, in the Virtual server instances tile, click Attach.
  3. On the side panel, select a virtual server instance and click Save. If the list shows no virtual server instances, click Create server to go to the instance provisioning page. The boot or data volume is shown on the instance provisioning page in their respective fields.
  4. Messages display that the volume is being attached to the image. When it completes, the image name appears under Attached instances.

Attaching a volume to an instance from the instance details page

Attach a Block Storage for VPC volume from the virtual server instance details page.

  1. In the IBM Cloud console, go to the Navigation Menu icon menu icon > VPC Infrastructure VPC icon > Compute > Virtual server instances.
  2. Select an instance from the list of all virtual server instances. If any Block Storage for VPC volumes are attached, they are listed under Storage volumes.
  3. Select Attach volume.
  4. Select a volume from the list of available resources and click Attach. Messages display on the instance details page to indicate that the volume is being attached. When it completes, the Storage volumes list is updated to include the new volume.

Attaching a Block Storage for VPC volume from the CLI

Follow these instructions to use the CLI to attach a Block Storage for VPC volume to a virtual server instance. Each instance can have many volume attachments, but a single volume attachment connects one volume to one instance.

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.

  2. Select the current generation of VPC.

    ibmcloud is target --gen 2

Attaching a Block Storage for VPC volume from the CLI

To attach a volume to a virtual server instance in the current resource group, run this command.

ibmcloud is instance-volume-attachment-add NAME INSTANCE_ID VOLUME_ID [--auto-delete true | false] [--json]

NAME is the name that you provide for the volume attachment and INSTANCE_ID is the ID of the virtual server instance. The VOLUME_ID specifies the volume that you are attaching. If you want the volume to automatically delete when the virtual server instance is deleted, specify --auto-delete true.

To see a list of available virtual server instances, run the ibmcloud is instances command. Check out the following example.

$ ibmcloud is instances
Listing instances in all resource groups and region us-east under account Test Account as user test.user@ibm.com...
ID                                          Name                             Status    Reserved IP   Floating IP      Profile    Image                                VPC                              Zone        Resource group   
0757_506a787d-0672-4209-854b-3e280ec50b44   test-pbalak-rhel                 running   10.241.0.4    169.63.96.188    bx2-2x8    ibm-redhat-9-0-minimal-amd64-2       test-pbalak1                     us-east-1   defaults   
0757_4fc00b09-c967-46bf-9203-d17a08078d1d   test-pbalak-rhel2                running   10.241.0.5    150.239.86.22    bx2-2x8    ibm-redhat-9-0-minimal-amd64-2       test-pbalak1                     us-east-1   defaults   
0757_11f5db7f-35a1-4678-bcbd-c85204e09507   kj-test-ro                       running   10.241.0.5    -                bx2d-2x8   ibm-ubuntu-18-04-5-minimal-amd64-1   test-vpc-blu-wdc             us-east-1   defaults   
0767_7ac6da13-c16a-4f58-9981-612d6e33ec53   cbake-test-dfm-vsi-0             running   10.241.64.4   -                bx2-2x8    ibm-centos-7-9-minimal-amd64-3       test-vpc-blu-wdc             us-east-2   defaults   
0757_ff64452f-7e81-4a48-b938-7fc601597dcd   storage-csi-inst-pgb1-zwqz5elk   running   10.241.14.4   52.116.121.167   mx2-2x16   ibm-ubuntu-20-04-6-minimal-amd64-1   test-vpc-do-not-delete-default   us-east-1   Default   
0757_337977c1-f1f0-42ad-9de4-16fe0cda2ba9   storage-csi-inst-qgbi-sj9a43as   running   10.241.4.4    52.116.124.193   mx2-2x16   ibm-ubuntu-20-04-6-minimal-amd64-1   test-vpc-do-not-delete-default   us-east-1   Default   
0757_dee890d9-67da-46cb-a85b-2d064a49ca42   storage-csi-inst-txmz-zuwrddvm   running   10.241.3.4    52.116.122.116   mx2-2x16   ibm-ubuntu-20-04-6-minimal-amd64-1   test-vpc-do-not-delete-default   us-east-1   Default

Then, select the virtual server instance that is in the same zone as the volume that you want to attach.

$ ibmcloud is instance-volume-attachment-add otp1 0757_11f5db7f-35a1-4678-bcbd-c85204e09507 demo-volume-update --auto-delete true
Creating volume attachment otp1 for instance kj-test-ro under account Test Account as user test.user@ibm.com...
                     
ID                0757-6757e676-0bf5-4b79-9a5b-29c24e17420c   
Name              otp1   
Volume            ID                                          Name      
                  r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac   demo-volume-update      
                     
Status            attaching   
Bandwidth(Mbps)   393   
Type              data   
Device            -   
Auto delete       true   
Created           2023-06-29T18:14:57+00:00

For more information about available command options, see ibmcloud is instance-volume-attachment-add.

Show details of a volume that is attached to a virtual server instance

After you attach a volume, you can display details by specifying the instance ID or name and the volume attachment ID or name in the instance-volume-attachment command.

ibmcloud is instance-volume-attachment INSTANCE VOLUME_ATTACHMENT [--json]

$ ibmcloud is instance-volume-attachment kj-test-ro otp1
Getting volume attachment otp1 of instance kj-test-ro under account Test Account as user test.user@ibm.com...
                     
ID                0757-6757e676-0bf5-4b79-9a5b-29c24e17420c   
Name              otp1   
Volume            ID                                          Name      
                  r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac   demo-volume-update      
                     
Status            attached   
Bandwidth(Mbps)   393   
Type              data   
Device            0757-6757e676-0bf5-4b79-9a5b-29c24e17420c-bxsh7   
Auto delete       true   
Created           2023-06-29T18:14:57+00:00

For more information about available command options, see ibmcloud is instance-volume-attachment.

List all volume attachments of a server instance

Use the instance-volume-attachments command and specify the instance ID or name to see all volume attachments for an instance.

ibmcloud is instance-volume-attachments INSTANCE [--json]

See the following example.

ibmcloud is instance-volume-attachments kj-test-ro
Listing volume attachments of instance kj-test-ro under account Test Account as user test.user@ibm.com...
ID                                          Name                                 Volume                          Status     Type   Device                                            Auto delete   
0757-6757e676-0bf5-4b79-9a5b-29c24e17420c   otp1                                 demo-volume-update              attached   data   0757-6757e676-0bf5-4b79-9a5b-29c24e17420c-bxsh7   true   
0757-af470ade-9d5c-491e-97b2-f000ed4ee49b   scheming-tipper-shivering-decrease   kj-test-ro-boot-1629867631000   attached   boot   0757-af470ade-9d5c-491e-97b2-f000ed4ee49b-fc4tl   true

For more information about available command options, see ibmcloud is instance-volume-attachments.

Create a volume attachment JSON

When you provision a virtual server instance from the CLI and create a Block Storage for VPC volume as part of the process, you can specify a volume attachment JSON. The volume attachment JSON, specified in the command or as a file, contains the volume parameters.

In the CLI command that you use to create an instance, you specify the --volume-attach option and the volume JSON file. For example, --volume-attach @/Users/myname/myvolume-attachment_create.json.

The following example shows the content of a volume attachment JSON file that defines a custom volume and specifies user tags.

[
    {
        "name": "myvolume-attachment",
        "delete_volume_on_instance_delete": true,
        "volume": {
            "name": "myvolume",
            "capacity": 100,
            "iops": 1000,
            "profile": {
                "name": "custom"
            },
            "user_tags": {
                "env:test"
            }
        }
    }
]

Attaching a Block Storage for VPC volume with the API

Attaching a Block Storage for VPC volume with the API

Attach Block Storage for VPC volumes to an instance by directly calling the REST APIs.

Create a volume attachment for an instance to attach a Block Storage for VPC volume. Make a POST /instances call and specify volume_attachments.

POST/instances/{instance_id}/volume_attachments

The following example creates a volume attachment and specifies the volume by ID.

curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments?version=2021-04-20&generation=2" \
-H "Authorization: $iam_token" \
-d '{
      "delete_volume_on_instance_delete": true,
      "name": "my-volume-attachment-data-5iops",
      "volume": {"id": "d8b26921-1409-4c2f-9b46-39b5b6e0b945"}
    }'

A successful response indicates that the volume is attached.

{
  "created_at": "2021-04-21T16:35:47.000Z",
  "delete_volume_on_instance_delete": true,
  "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/8f06378c-ed0e-481e-b98c-9a6dfbee1ed5/volume_attachments/9f2a645e-19c1-4f8f-b062-46b9e0671999",
  "id": "9f2a645e-19c1-4f8f-b062-46b9e0671999",
  "name": "my-volume-attachment-data-5iops",
  "status": "attached",
  "type": "data",
  "volume": {
    "crn": "crn:[...]",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/d8b26921-1409-4c2f-9b46-39b5b6e0b945",
    "id": "d8b26921-1409-4c2f-9b46-39b5b6e0b945",
    "name": "my-volume-data-5iops"
  }
}

Next steps

Create more volumes and manage existing ones. See the following information.