Bulk attach and detach volume APIs

Edit online

The bulk attach volume API attaches bulk volumes to a virtual machine. The bulk detach volume API detaches bulk volumes from a virtual machine.

Bulk volume attach option

Starting PowerVC 2.2.1, a new primaryBoot parameter is introduced in the bulk volume attach API. If the parameter is passed, it assigns the volume as rootvg and sets the boot_index as 0 to an empty VM. If the parameter is not passed, it assigns the first boot volume as rootvg to an empty VM.

Table 1. Option for bulk volume attach API
Method	URI	Description
POST	`/v2.1/{tenant_id}/servers/{server_id}/action`	Creates or attaches bulk volumes to a virtual machine. Specify the `bulkVolumeAttach` action in the request body.

Request parameters

Table 2. Parameters in the request for bulk volume attach
Name	Type	Description
`volumeAttachment`	List	List of all volume IDs to attach.
`volumeId`	String	ID of the volume to be attached.
`primaryBoot`	Boolean	Assigns a particular volume ID as rootvg and sets the `boot_index` as 0.

Example of request body

{
  "bulkVolumeAttach": {
    "volumeAttachment": [
      {
        "volumeId": "26630011-1fc2-47a9-89df-ac70ccf4ecc3",
      },
      {
        "volumeId": "26630011-1fc2-47a9-89df-ac70ccf4ecc3"
      },
      {
        "volumeId": "26630011-1fc2-47a9-89df-ac70ccf4ecc3"
      }
    ]
  }
}

Example of request body with the primaryBoot parameter

{
    "bulkVolumeAttach": {
        "volumeAttachment": [
            {
                "volumeId": "22ea0080-e765-4042-94ed-7a80db09c788",
                "primaryBoot": true
            },
            {
                "volumeId": "22ea0080-e765-4042-94ed-7a80db09c788"
            }
        ]
    }
}

Response code

Normal: Accepted (202)
Failure: Partial Content (206), Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Internal Server Error (500)

Bulk volume detach option

Table 3. Option for bulk volume detach API
Method	URI	Description
POST	`/v2.1/{tenant_id}/servers/{server_id}/action`	Detaches bulk volumes from a virtual machine. Specify the `bulkVolumeDetach` action in the request body.

Request parameters

Table 4. Parameters in the request for bulk volume detach
Name	Type	Description
`volume_ids`	List	List of volume IDs to detach. Mutually exclusive to `detach_all_volumes`.
`allow_rootvg`	Boolean	Pass `allow_rootvg = true` if you want to detach root volume.
`detach_all_volumes`	Boolean	Detaches all volumes except the root volume if passed 'true'. Pass `allow_rootvg = true` to detach root volume. Mutually exclusive to `volume_ids`.

Example of request body for volume detach

{
  "bulkVolumeDetach": {
    "volume_ids": [
      "ae6a35cc-ab78-40f5-be44-b7f6c655786c",
      "61fa8501-d69c-4458-99b0-09a27c808b72"
    ],
    "allow_rootvg": true 
  }
}

Example of request body to detach all volumes

{
  "bulkVolumeDetach": {
       “detach_all_volumes”: true 
       "allow_rootvg": true
  }
}

Example of request body to detach all volumes except root volume

{
  "bulkVolumeDetach": {
       “detach_all_volumes”: true   
  }
}

Response code

Normal: Accepted (202)
Failure: Bad Request (400), Forbidden (403)

Bulk attach or detach limitations

A maximum of 500 volumes can be attached or detached by using a single bulk operation. This limitation applies to both single VM and multiple VM scenarios.

Single VM: For a single VM, a maximum of 500 volumes can be attached or detached by using a single bulk operation. For example, if you have one VM with 500 volumes, you can attach or detach all 500 volumes by using a single bulk operation.
Multiple VMs: For multiple VMs as well a maximum of 500 volumes can be attached or detached by using a single bulk operation. However, the 500 volumes can be distributed across multiple VMs. For example, if you have five VMs, each with 100 volumes, you can attach or detach all 500 volumes (100 volumes x 5 VMs) by using a single bulk operation. The total number of volumes that are attached or detached must not exceed 500 in a single bulk operation.

Notes:

Bulk attach

Primary boot can only be set for a VM with no volumes attached.
Only one primaryBoot parameter can be set for a VM.
If primaryBoot parameter is not passed, then the API assigns the first boot volume as rootvg. If there are no boot volumes, then the API picks the first data volume as rootvg.
When a bulk attach operation is in progress, do not trigger single volume attach or detach community APIs in the same virtual machine.

Bulk detach

VM must be in “stopped” state when you pass the allow_rootvg parameter as "true" to detach the rootvg volume. In such an instance, make sure to attach another volume as the primary boot to avoid the VM failing on power on.
If you pass rootvg volume_ids, then make sure to pass the allow_rootvg parameter as "true", otherwise the volume detach action for that volume will be skipped.
You cannot pass detach_all_volumes and volume_ids together.
When a bulk detach operation is in progress, do not trigger single volume attach or detach community APIs in the same virtual machine.