Managing Block Storage for VPC volumes

Detaching a Block Storage for VPC volume from a virtual server instance

You can detach a Block Storage for VPC volume that is attached to a virtual server instance. Detaching frees the volume for use by another instance.

To detach a volume, complete the following steps.

1. Go to the list of all Block Storage for VPC volumes. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.
2. Locate the volume and click the Actions icon to open a list of options.
3. From the options menu, click Detach from instance.
4. Confirm by clicking Detach instance in the open window.

Alternatively, you can click an individual volume in the list of all Block Storage for VPCand go to the Volume Details page for that volume. Under Attached instances, click the minus sign next to the virtual server instance to detach the volume from that instance.

When you use a Hyper Protect Virtual Servers for IBM Cloud® Virtual Private Cloud instance, detaching the data volume that is attached to a running instance causes the workload that's running on the instance to fail. Therefore, it is recommended that you do not detach the data volume.

Transferring a Block Storage for VPC volume from one virtual server instance to another

To transfer a Block Storage for VPC volume to another virtual server instance, complete the following steps.

1. Detach the volume from its virtual server instance.
2. Go to the virtual server instance to which you want to transfer the volume. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Compute > Virtual server instances.
3. Select a virtual server instance from the list.
4. Under Attached Storage volumes, click the plus sign to add a volume. All Block Storage for VPCare displayed.
5. From the list of volumes, select the volume that you previously detached.

Attaching a previously attached Block Storage for VPC data volume

A Block Storage for VPC data volume is attached by default when you provision the volume during virtual server instance creation. When you detach a volume from an instance, it exists as an unattached volume and is displayed in the list of all Block Storage for VPC volumes. You can attach it to another instance from the list of Block Storage for VPC volumes.

1. Go to the list of all Block Storage for VPC volumes. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.
2. Locate the volume and then click the Actions icon to open a list of options.
3. From the options menu, click Attach to instance.
4. Select an available virtual server instance.
5. Confirm your selection.

Updating the name of a Block Storage for VPC volume

You can change the name of an existing volume to make it more meaningful.

1. Go to the list of all Block Storage for VPC volumes. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.

2. Locate the volume and then click the name of the volume to go to the Volume Details page.

3. Click the Edit icon after the name of the volume to edit the name. Provide a valid volume name. 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.

4. Confirm your edit.

Adding user tags to a Block Storage for VPC volume in the console

Add user tags to Block Storage for VPC from the list of volumes or the volumes details page.

1. Go to the list of Block Storage for VPC volumes. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.

2. Locate the volume from the list that you want to add user tags.

3. In the tags column, click Add tags.

4. Enter the user tags that you want to apply to this volume. Tags display as you type.

   You can also add access management tags to a volume. For more information about creating and adding access management tags, see Apply access management tags to a volume.

5. When you're done adding tags, click Save. When you refresh the screen, the list of Block Storage for VPC shows the number of tags that are added in the Tags column.

You can also add tags from the volume details page. To do so, follow these steps.

1. Go to the list of Block Storage for VPC volumes.
2. On the volume details, click Add tags next to the volume name.
3. Enter the user tags that you want to apply to this volume. When finished, click Save.

Adding user tags that are associated with a backup policy to a volume in the console

You can add user tags that are associated with a backup policy to a Block Storage for VPC volume. Backup policies schedule automatic creation of backup snapshots. When one volume tag matches a backup policy tag for target resources, it triggers a backup of the volume contents. A backup policy defines a backup plan that schedules when backup snapshots are taken.

From the volume details page, you can view the backup policies that are applied to the volume and add user tags that are associated with a backup policy.

1. Go to the list of Block Storage for VPC volumes. In the IBM Cloud console, click the Navigation menu icon > Infrastructure > Storage > Block Storage volumes.
2. Locate the volume that you want and click the name link.
3. From the Block Storage for VPCdetails page, click the Backup policies tab.
4. Click Attach.
5. In the side panel, select a backup policy from the list of available policies, and then select the policy tags to apply to the volume. You can also view the plan details that can help you decide whether to use that policy.
6. Click Apply policy and tags. The backup policy shows in the list of backup policies that are associated with the volume.

When you go to the backup policy page, the volume for which you added tags shows up in the list of volumes.

For more information about creating backups, see Creating a backup policy. For more information about user tags, see Working with tags.

Updating a volume name

To change a volume name, specify either the volume name or ID and then indicate the new name. The volume name can be up to 63 alpha-numeric characters and include special characters, and must begin with a lowercase letter. The volume name must be unique across the VPC infrastructure.

ibmcloud is volume-update VOLUME_ID [--name NEW_NAME] [--json]

See the following example.

$ ibmcloud is volume-update r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac --name demo-volume-update
Updating volume 933c8781-f7f5-4a8f-8a2d-3bfc711788ee under account Test Account as test.user@ibm.com...
ID                                     r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac
Name                                   demo-volume-update
CRN                                    crn:v1:bluemix:public:is:us-east-1:a/a1234567::volume:r014-dee9736d-08ee-4992-ba8d-3b64a4f0baac
Status                                 available
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                           ok
Volume Attachment Instance Reference   -
Active                                 false
Adjustable Capacity States             attached 
Adjustable IOPS States                 
Busy                                   false
Tags                                   -

Adding user tags to a Block Storage for VPC volume in from the CLI

Issue the ibmcloud is volume-update VOLUME command with the --tags option to update the user tags of a volume. The volume argument can be defined by either the volume ID or the volume name.

Use the same option to add tags to a volume when you create a volume by using ibmcloud is volume-create.

The following example adds user tags env:test and bkp:test to a volume identified by ID. The output shows information such as name, status, capacity, performance profile, and location. The updated tags appear at the end of the response.

cloudshell:~$ ibmcloud is volume-update r010-bdb8fc70-8afb-4622-826a-d65a9fc477a4 --tags env:test,bkp:test,bcp:test
Updating volume r010-bdb8fc70-8afb-4622-826a-d65a9fc477a4 under account Test Account as user test.user@ibm.com...
                                          
ID                                     r010-bdb8fc70-8afb-4622-826a-d65a9fc477a4   
Name                                   my-bootable-snapshot-restore-21   
CRN                                    crn:v1:bluemix:public:is:eu-de-2:a/a1234567::volume:r010-bdb8fc70-8afb-4622-826a-d65a9fc477a4   
Status                                 available   
Capacity                               100   
IOPS                                   3000   
Bandwidth(Mbps)                        393   
Profile                                general-purpose   
Encryption key                         -   
Encryption                             provider_managed   
Resource group                         defaults   
Created                                2023-02-23T18:52:00+00:00   
Zone                                   eu-de-2   
Health State                           ok   
Volume Attachment Instance Reference   -   
Source snapshot                        ID                                          Name      
                                       r138-92c3efcb-4588-4c9c-828b-c52836629954   my-bootable-snapshot      
                                          
Operating system                       CentOS 7.x - Minimal Install (amd64)   
Source image                           ID                                          Name      
                                       r010-067bd38b-7ddd-49d9-a7f3-6e0a798e0554   ibm-centos-7-9-minimal-amd64-5      
                                          
Active                                 false   
Busy                                   false   
Tags                                   env:test,bkp:test,bcp:test

Updating a volume attachment from the CLI

You can update the volume attachment name and change the default auto delete setting with the instance-volume-attachment-update command.

ibmcloud is instance-volume-attachment-update INSTANCE_ID VOLUME_ATTACHMENT_ID [--name NEW_NAME] [--auto-delete true | false] [--json]

Use the --name option and specify a new name for the volume attachment. Specify --auto-delete true to automatically delete a volume that is attached to an instance, when you delete the instance. Specify --auto-delete false, if you want to keep the volume as a stand-alone volume after the instance is deleted.

$ ibmcloud is instance-volume-attachment-update kj-test-ro otp1 --name one-true-pairing --auto-delete false
Updating 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              one-true-pairing
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       false
Created           2023-06-29T18:14:57+00:00

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

Detaching a volume from the CLI

Use the instance-volume-attachment-detach command to detach a volume from an instance and delete the volume attachment. The Block Storage for VPC volume is not deleted; you can later attach it to another instance.

In the syntax for this command, INSTANCE is the ID or name of the instance. VOLUME_ATTACHMENT is the ID or name of the volume attachment. You can specify multiple volume attachments. For more information about volume attachments, see the CLI reference for creating a volume attachment.

ibmcloud is instance-volume-attachment-detach INSTANCE (VOLUME_ATTACHMENT1 VOLUME_ATTACHMENT2 ...) [--output JSON] [-f, --force] [-q, --quiet]

$ ibmcloud is instance-volume-attachment-detach kj-test-ro one-true-pairing
This will delete volume attachment one-true-pairing and cannot be undone. Continue [y/N] ?> y
Deleting volume attachment one-true-pairing from instance kj-test-ro under account Test Account as user test.user@ibm.com...
OK
Volume attachment one-true-pairing is deleted.

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

Updating the name of a volume with the API

Make a PATCH /volumes/{id} call and specify a new name for the volume.

curl -X PATCH "$vpc_api_endpoint/v1/volumes?version=2022-04-22&generation=2" \
-H "Authorization: $iam_token" \
-d '{
      "name": "my-volume-4-update"
    }'

A successful response looks like the following example.

{
  "capacity": 50,
  "created_at": "2022-04-22T23:16:53.000Z",
  "crn": "crn:[...]",
  "encryption": "user_managed",
  "encryption_key": {
    "crn": "crn:[...]"
  },
  "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-update",
  "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"
  }
}

Adding user tags to a Block Storage for VPC volume with the API

To add user tags to a volume, you first make a GET /volumes/{volume_id} call and copy the hash string from Etag property in the response header. You then use the hash string when you specify If-Match in a PATCH /volumes/{volume_id} request to create new user tags.

To apply tags to a Block Storage for VPC volume, follow these steps:

1. Make a GET /volumes/{volume_id} call and copy the hash string from the Etag property in the response header. You need to use the hash string when you specify If-Match in the PATCH /volumes/{volume_id} request to create user tags for the volume in step 2. To generate the response header information, make an API call similar to the following example:

   curl -sSL -D GET\
   "https://us-south.iaas.cloud.ibm.com/v1/volumes/{volume_id}?version=2022-04-25&generation=2"\
   -H "Authorization: Bearer $TOKEN" -o /dev/null
   

   In the response header, you see something like this:

   HTTP/2 200
   date: Tue, 28 Apr 2022 17:48:03 GMT
   content-type: application/json; charset=utf-8
   content-length: 1049
   cf-ray: 69903d250c4966ef-DFW
   cache-control: max-age=0, no-cache, no-store, must-revalidate
   expires: -1
   strict-transport-security: max-age=31536000; includeSubDomains
   cf-cache-status: DYNAMIC
   expect-ct: max-age=604800, report-uri="[uri...]"
   pragma: no-cache
   x-content-type-options: nosniff
   x-request-id: 1fbe2384-6828-4503-ae7d-050426d1b11b
   x-xss-protection: 1; mode=block
   server: cloudflare
   etag: W/xxxyyyzzz123
   

2. Make a PATCH /volumes/{volume_id} request. Specify the Etag-hash-string for the If-Match property in the header. Specify the user tag in the user_tags property.

   You can also add tags when you make a POST /volumes call to create a volume and specify the user_tags property.

   This example updates the volume by specifying user tags env:test and env:prod. The value that you obtained from the Etag parameter is specified in the If-Match header in the call.

   curl -X PATCH\
   "$vpc_api_endpoint/v1/volumes/50fda9c3-eecd-4152-b473-a98018ccfb10?version=2022-04-25&generation=2"\
      -H "Authorization: Bearer"\
      -H "If-Match: <_Etag-hash-string_>"\
      -d `{
         "user_tags": [
            "env:test",
            "env:prod"
         ]
      }'
   

   The response shows the tags that were added to the volume:

   {
      "id":"50fda9c3-eecd-4152-b473-a98018ccfb10",
        "crn": "crn:[...]",
      "name":"my-volume-update1",
      "href":"https://us-south.iaas.cloud.ibm/v1/volumes/50fda9c3-eecd-4152-b473-a98018ccfb10",
      "capacity":50,
      "iops":100,
      "encryption":"provider_managed",
      "status":"pending",
      "zone":{
         "name":"us-south-1",
         "href":"https://us-south.iaas.cloud.ibm/v1/regions/us-south/zones/us-south-1"
      },
         "profile":{
         "name":"custom",
         "href":"https://us-south.iaas.cloud.ibm/v1/volume/profiles/custom"
      },
      "resource_group":{
         "id":"4bbce614c13444cd8fc5e7e878ef8e21",
         "href":"https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21",
         "name":"Default"
      },
      "volume_attachments":[],
      "created_at":"2022-04-28T17:46:17.000Z",
      "status_reasons":[],
      "active":false,
      "busy":false,
      "bandwidth":128,
      "user_tags":[
        "env:test",
         "env:prod"
      ]
   }
   

Updating a volume attachment with the API

Make a PATCH /instances call and specify the ID of the new volume attachment.

PATCH /instances/{instance_id}/volume_attachments/{id}

curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments/$volume_attachment_id?version=2022-04-22&generation=2" \
-H "Authorization: $iam_token" \
-d '{
      "delete_volume_on_instance_delete": false,
      "name": "my-volume-attachment-data-5iops-updated"
    }'

A successful response looks like the following example.

{
  "created_at": "2022-04-22T16:35:47.000Z",
  "delete_volume_on_instance_delete": false,
  "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-updated",
  "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"
  }
}

Detaching a volume with the API

Make a DELETE /instances request and specify the volume attachment ID to delete a volume attachment. Deleting a volume attachment detaches a volume from an instance.

DELETE /instances/{instance_id}/volume_attachments/{id}

curl -X DELETE "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments/$volume_attachment_id?version=2022-04-22&generation=2" \
-H "Authorization: $iam_token"

Verify that the volume is detached from the instance by making a GET /instances/{instance_id} call.

Updating the name of a volume with Terraform

To change the name of a volume, use the ibm_is_volume resource. The following example specifies the volume r010-bdb8fc70-8afb-4622-826a-d65a9fc477a4 and its new name as my-new-name-volume. When applied, the volume is renamed.

resource "ibm_is_volume" "example" {
  name    = "my-new-name-volume"
  id      = "r010-bdb8fc70-8afb-4622-826a-d65a9fc477a4"
  profile = "10iops-tier"
  zone    = "us-south-1"
}

Applying tags to volumes with Terraform

To apply user tags to a volume, use the ibm_is_volume resource. The following example specifies the volume my-new-volume and the tag dev:test to be attached to the volume. When applied, the tag is added to the volume.

resource "ibm_is_volume" "example" {
  name    = "my-new-volume"
  profile = "10iops-tier"
  zone    = "us-south-1"
  tags    = ["dev:test"]
}