Specify SCSI disk placement using the vRealize Automation API

When attaching a disk object to a vSphere VM, you can specify the SCSI controller and the logical unit number (LUN) disk properties so that you can identify the disk when taking day 2 actions.

To attach a disk to a VM, you need the block device ID of the disk and and the ID of the VM. The following procedure includes steps to:

List all machines in your environment to find the ID of the vSphere VM that you want to attach a disk to.
List all block devices in your environment to find the disk you want to attach.
Attach the disk specifying the SCSI controller and LUN.

Prerequisites

Verify that all general prerequisites have been satisfied. See Prerequisites for working with the Cloud Assembly APIs.

Procedure

List all the machines in your environment.

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" $url/iaas/api/machines?apiVersion=$api_version | jq "."

To identify the vSphere VM where you want to attach your disk, look for the name and the region ID in the response. The self:href path includes the machine ID.

{
      "powerState": "OFF",
      "externalRegionId": "Datacenter:datacenter-2",
      "cloudAccountIds": [
        "e0f23c91d5ecca75-7f703c5265a63d87-7e3d8d60a55d1306cc791422547ead9153c3bdf1c802400819ad45a341cba1f3-b37e594a2e813475574a7c3c42b5d"
      ],
      "provisioningStatus": "READY",
      "customProperties": {
        "osType": "LINUX",
        "vcUuid": "1f9678f0-90d1-4347-82ee-f1ac2fac4216",
        "memoryGB": "1",
        "datacenter": "Datacenter:datacenter-2",
        "instanceUUID": "503a00ea-5ce5-3ae8-db3d-ebbd537eed5f",
        "softwareName": "Ubuntu Linux (64-bit)",
        "cpuCount": "2",
        "memoryInMB": "1024"
      },
      "externalId": "503a00ea-5ce5-3ae8-db3d-ebbd537eed5f",
      "name": "wordpress-mcm827-142063808276-ovf-backing",
      "id": "0355cee4-5d88-36b6-9a87-5f37b5baa6e2",
      "createdAt": "2022-04-02",
      "updatedAt": "2022-04-02",
      "organizationId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
      "orgId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
      "_links": {
        "network-interfaces": {
          "hrefs": [
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/network-interfaces/1c31ee02-c83c-3229-84ec-929f3592494a"
          ]
        },
        "cloud-accounts": {
          "hrefs": [
            "/iaas/api/cloud-accounts/e0f23c91d5ecca75-7f703c5265a63d87-7e3d8d60a55d1306cc791422547ead9153c3bdf1c802400819ad45a341cba1f3-b37e594a2e813475574a7c3c42b5d"
          ]
        },
        "operations": {
          "hrefs": [
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/operations/power-on",
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/operations/snapshots",
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/operations/resize",
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/disks",
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/disks/{id}"
          ]
        },
        "disks": {
          "hrefs": [
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/disks/effb94a6-41ad-3553-bb9a-22896785a283",
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/disks/0815ed4c-0a33-3058-a5f5-3032a426ded4",
            "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2/disks/3804a2b2-99fc-3fca-bd2f-f0cfc3845b54"
          ]
        },
        "self": {
          "href": "/iaas/api/machines/0355cee4-5d88-36b6-9a87-5f37b5baa6e2"
        }
      }
    },

In this response example, the machine ID is 0355cee4-5d88-36b6-9a87-5f37b5baa6e2.

Assign the machine ID.

machine_id='example-machineID-alphanumeric-string'

List the block devices in your environment.

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" $url/iaas/api/block-devices?apiVersion=$api_version | jq "."

Examine the response to find the block device that you want to attach. The block device must be available and in the same external region as the vSphere VM. The self:href path includes the block device ID.

...    
    {
      "capacityInGB": 30,
      "status": "AVAILABLE",
      "type": "HDD",
      "persistent": false,
      "externalRegionId": "Datacenter:datacenter-2",
      "cloudAccountIds": [
        "e0f23c91d5ecca75-7f703c5265a63d87-e78aab87e9c8d5cd4cd1da1a285403f0f4e77a5240720d093e147b830b172542-6b4f9990d36ee87558f04e6e8e0ca"
      ],
      "provisioningStatus":"READY",
      "customProperties": {
        "diskKind": "Unmanaged"
      },
      "externalId": "74213f6d-ee11-4549-996a-772c0621f7d1",
      "name": "Hard disk 1",
      "id": "02c39b60-32f5-4a7e-9317-88bf8a3fe20c",
      "createdAt": "2022-04-02",
      "updatedAt": "2022-04-02",
      "organizationId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
      "orgId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
      "_links": {
        "cloud-accounts": {
          "hrefs": [
            "/iaas/api/cloud-accounts/e0f23c91d5ecca75-7f703c5265a63d87-e78aab87e9c8d5cd4cd1da1a285403f0f4e77a5240720d093e147b830b172542-6b4f9990d36ee87558f04e6e8e0ca"
          ]
        },
        "operations": {
          "hrefs": [
            "/iaas/api/block-devices/02c39b60-32f5-4a7e-9317-88bf8a3fe20c?capacityInGB={capacityInGB}"
          ]
        },
        "self": {
          "href": "/iaas/api/block-devices/02c39b60-32f5-4a7e-9317-88bf8a3fe20c"
        }
      }
    },
...

In this response example, the block device ID is 02c39b60-32f5-4a7e-9317-88bf8a3fe20c.

Assign the block device ID variable.

block_device_id='example-blockdeviceID-alphanumeric-string'

Attach the disk to the VM, specifying both the SCSI controller number and the LUN disk properties.
- For the SCSI controller number, you can specify any of four values: SCSI_Controller_0, SCSI_Controller_1, SCSI_Controller_2, SCSI_Controller_3.
- For the LUN, you can specify any integer value from 0 through 15. Unit 0 is the boot disk. Disks with higher LUN values attach after disks with lower LUN values.
Note: If you do not specify a LUN, the disk attaches to the first available unit number. If you specify neither the SCSI controller nor the LUN, the disk attaches to the first available SCSI controller and first available unit number.

This request example uses "scsiController": "SCSI_Controller_0" and "unitNumber": "0".
```
curl -X POST \
  $url/iaas/api/machines/$machine_id/disks?apiVersion=$api_version \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" \
  -d '{
    "blockDeviceId": "'$block_device_id'",
    "scsiController": "SCSI_Controller_0",
    "name": "BootDisk ",
    "description": "Unit 0 is the boot disk",
    "unitNumber": "0"
}' | jq "."
```
The response includes a selfLink value.
```
{
  "progress": 0,
  "status": "INPROGRESS",
  "name": "Provisioning",
  "id": "example-selfLink-alphanumeric-string",
  "selfLink": "/iaas/api/request-tracker/example-selfLink-alphanumeric-string"
}
```

Assign the selfLink variable.

selfLink_id='example-selfLink-alphanumeric-string'

Use the selfLink variable to track the progress of the disk attachment.

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" $url/iaas/api/request-tracker/$selfLink_id?apiVersion=$api_version | jq "."

After the request completes successfully, the response includes a list of resources with a machine that has your machine ID in the path.

{
  "progress": 100,
  "message": "success",
  "status": "FINISHED",
  "resources": [
    "/iaas/api/machines/example-machineID-alphanumeric-string"
  ],
  ...
}

(Optional) To specify SCSI controller and LUN when attaching additional disks, repeat Step 5 to Step 7.

Results

If you deploy a cloud template that includes a VM with multiple vSphere disk objects, the disks are assigned to the SCSI controller and LUN that you specified. In this way, you can identify the disks when taking day 2 actions such as formatting or resizing a disk.