15.4. Sub-Collections

⁠15.4. Sub-Collections

⁠15.4.1. Disks Sub-Collection

⁠15.4.1.1. Disks Sub-Collection

The disks sub-collection represents all virtual hard disk devices on a virtual machine. A disk representation contains the following elements:

⁠

Table 15.2. Elements for virtual machine disks

Element	Type	Description	Properties
`link rel="statistics"`	relationship	A link to the `statistics` sub-collection for a virtual machine's disk statistics.
`storage_domains`	Complex	The storage domains associated with this disk. Each `storage_domain` element contains an `id` attribute with the associated storage domain's GUID. Update this element with `POST` to perform live migration of a disk from one data storage domain to another.	⁠^[a]
`size`	integer	Size of the disk in bytes.
`provisioned_size`	integer	The provisioned size of the disk in bytes.
`actual_size`	integer	Actual size of the disk in bytes.
`status`	One of `illegal`, `invalid`, `locked` or `ok`	The status of the disk device. These states are listed in `disk_states` under `capabilities`.
`interface`	enumerated	The type of interface driver used to connect to the disk device. A list of enumerated values is available in `capabilities`.
`format`	enumerated	The underlying storage format. A list of enumerated values is available in `capabilities`. Copy On Write (COW) allows snapshots, with a small performance overhead. Raw does not allow snapshots, but offers improved performance.
`sparse`	Boolean: true or false	`true` if the physical storage for the disk should not be preallocated.
`bootable`	Boolean: true or false	`true` if this disk is to be marked as bootable.
`shareable`	Boolean: true or false	`true` to share the disk with multiple virtual machines.
`wipe_after_delete`	Boolean: true or false	`true` if the underlying physical storage for the disk should be zeroed when the disk is deleted.
`propagate_errors`	Boolean: true or false	`true` if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS.
`vm id=`	GUID	The ID of the containing virtual machine.
`quota id=`	GUID	Sets a quota for the disk.
`lunStorage`	complex	A reference to a direct LUN mapping for storage usage. Requires a `storage` element that contains iSCSI or FCP device details.
`active`	Boolean	Defines if the disk is connected to the virtual machine.
^[a] This element is only required if the disk is being added to a virtual machine and not created from a virtual machine template.

⁠

Example 15.6. An XML representation of a disk device

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/
  ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>  
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>10737418240</size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>   
    <lunStorage>
        <storage>
            <logical_unit id="lun1">
                ...
            </logical_unit>
        <storage>
    </lunStorage>
</disk>

When adding a new disk, the size element is required. Also the API requires the storage_domains element when the disk is added to a virtual machine and not itself created from a template.

⁠

Example 15.7. Creating a new a disk device on a virtual machine

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>

The name, description, storage_domains, interface, bootable, shareable, wipe_after_delete and propagate_errors elements are updatable post-creation.

⁠

Example 15.8. Updating a virtual machine disk

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <bootable>false</bootable>
    <shareable>false</shareable>
</disk>

Removal of a virtual machine disk requires a DELETE request.

⁠

Example 15.9. Removing a virtual machine disk

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1

HTTP/1.1 204 No Content

Report a bug

⁠15.4.1.2. Disk Cloning

Clone a disk from a template with the clone element. Set the clone element to true within the disks sub-collection when creating a virtual machine. This clones a disk from the base template and attaches it to the virtual machine.

⁠

Example 15.10. Cloning a disk from a template

The following example clones a disk from a template during the creation of a virtual machine.

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
        
<vm>
    <name>cloned_vm</name>
    <template id="64d4aa08-58c6-4de2-abc4-89f19003b886"/>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
    <disks>
        <clone>true</clone>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b">
            <format>COW</format>
        </disk>
        <disk id="42aef10d-3dd5-4704-aa73-56a023c1464c">
            <format>COW</format>
        </disk>
    </disks>
</vm>

Important

Search queries for virtual machine disks based upon disk name require the alias search parameter instead of name.

Report a bug

⁠15.4.1.3. Disk Statistics Sub-Collection

Each virtual machine's disk exposes a statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:

⁠

Table 15.3. Elements for virtual machine disk statistics

Element	Type	Description
`name`	string	The unique identifier for the statistic entry.
`description`	string	A plain text description of the statistic.
`unit`	string	The unit or rate to measure the statistical values.
`type`	One of `GAUGE` or `COUNTER`	The type of statistic measures.
`values type=`	One of `INTEGER` or `DECIMAL`	The data type for the statistical values that follow.
`value`	complex	A data set that contains `datum`.
`datum`	see `values type`	An individual piece of data from a `value`.
`disk id=`	relationship	A relationship to the containing `disk` resource.

The following table lists the statistic types for virtual machine disks.

⁠

Table 15.4. Virtual machine disk statistic types

Name	Description
`data.current.read`	The data transfer rate in bytes per second when reading from the disk.
`data.current.write`	The data transfer rate in bytes per second when writing to the disk.

⁠

Example 15.11. An XML representation of a virtual machine's statistics sub-collection

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/disks/
      f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
      33b9212b-f9cb-3fd0-b364-248fb61e1272">
        <name>data.current.read</name>
        <description>Read data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" 
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.

Report a bug

⁠15.4.1.4. Floating Disk Attach and Detach Actions

Attach any floating disks from the main rel="disks" collection using a POST request on the virtual machine's disks sub-collection. Include the id of the disk to attach.

⁠

Example 15.12. Attach a floating disk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
  <id="d135f1c5-b5e1-4238-9381-b3277f5a3742"/>
</disk>

Detach any disk from a virtual machine's disks sub-collection using a DELETE request on the disk resource but ensure to include a detach Boolean element so the disk is not destroyed.

⁠

Example 15.13. Detach a disk from a virtual machine

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  d135f1c5-b5e1-4238-9381-b3277f5a3742HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <detach>true</detach>
</action>

Report a bug

⁠15.4.1.5. Disk Activate and Deactivate Actions

Each virtual machine's disk provides a set of activate and deactivate actions to add and remove disks from a virtual machine.

⁠

Example 15.14. Action to activate a virtual machine disk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

⁠

Example 15.15. Action to deactivate a virtual machine disk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

Use these actions to hotplug disks to virtual machines and activate newly attached floating disks.

Important

The hotplugging feature only supports VirtIO disks and virtual machine operating systems that support hotplugging operations. Example operating systems include:

Red Hat Enterprise Linux 6;
Red Hat Enterprise Linux 5;
Windows Server 2008; and,
Windows Server 2003.

Report a bug