Chapter 13. Virtual Machines

The vms collection provides information about virtual machines in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="vms" link obtained from the entry point URI (see Chapter 4, Entry Point).
The following table shows specific elements contained in a virtual machine resource representation.

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”

Table 13.1. Virtual machine elements

Element Type Description Properties
link rel="disks" relationship A link to the disks sub-collection for virtual machine resources.
link rel="nics" relationship A link to the nics sub-collection for virtual machine resources.
link rel="cdroms" relationship A link to the cdroms sub-collection for virtual machine resources.
link rel="snapshots" relationship A link to the snapshots sub-collection for virtual machine resources.
link rel="tags" relationship A link to the tags sub-collection for virtual machine resources.
link rel="permissions" relationship A link to the permissions sub-collection for virtual machine permissions. See Section 7.3.7, “ Permissions ”.
link rel="statistics" relationship A link to the statistics sub-collection for virtual machine resources.
type enumerated The virtual machine type. A list of enumerated values are available in capabilities. See Section 6.1.8, “Virtual Machine Types”.
status See below The virtual machine status.
memory integer The amount of memory allocated to the guest in bytes.
cpu complex The CPU topology i.e. number of logical sockets available to the guest and the number of cores per socket. The total cores available to the virtual machine equals the number of sockets multiplied by the cores per socket.
os type= string, e.g. RHEL5 or WindowsXP The guest operating system type.
os boot dev= enumerated A list of boot devices described by a dev attribute on a boot element. A list of enumerated values are available in capabilities. See Section 6.1.9, “Boot Devices”.
os kernel string A path to a kernel image the virtual machine is configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
os initrd string A path to an initrd image to be used with the previously specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
os cmdline string A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
high_availability complex Set enabled to true if the virtual machine should be automatically restarted if the virtual machine or its host crashes. A priority element controls the order in which Virtual Machines are re-started.
display complex The display type (either vnc or spice), port, and the number of monitors.
cluster id= GUID A reference to the virtual machine's host cluster. See Chapter 9, Host Clusters.
template id= GUID A reference to the template on which this virtual machine is based.
domain id= GUID A reference to the virtual machine's domain.
start_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this virtual machine was started.
creation_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this virtual machine was created.
origin One of rhev, vmware or xen The system from which this virtual machine originated.
stateless Boolean: true or false true if the virtual machine is stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot.
placement_policy complex Sets the placement policy for virtual machine migration. Requires a default host= and an affinity (one of migratable, user_migratable or pinned). Leave the host element empty to set no preferred host.
memory_policy complex Sets the memory policy for virtual machines. Defines the minimum amount of guaranteed memory on a host in order for the virtual machine to run.
custom_properties complex A set of user-defined environment variable passed as parameters to custom scripts. Each custom_property contains name and value attributes. A list of enumerated values are available in capabilities. See Section 6.1.17, “Custom Properties”.
usb complex Defines the USB policy for a virtual machine. Requires an enabled element set to a Boolean value.
guest_info complex A reference to the guest client information. Includes an ip element with an address= attribute.
vmpool complex A reference to the virtual machine pool. This element only appears for virtual machines part of a pool.
timezone tz database format: Area/Location The the Sysprep timezone setting for a Windows virtual machine. Only certain timezones are allowed as specified in Appendix D, Timezones.
domain complex The the Sysprep domain setting for a Windows virtual machine. Requires a name from the domains collection. See Chapter 16, Domains for more information about domains.

The status contains one of the following enumerative values: unassigned, down, up, powering_up, powered_down, paused, migrating_from, migrating_to, unknown, not_responding, wait_for_launch, reboot_in_progress, saving_state, restoring_state, suspended, image_illegal, image_locked or powering_down. These states are listed in vm_states under capabilities (See Section 6.1.21, “Resource Status States”).

Example 13.1. An XML representation of a virtual machine

<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
  href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399">
    <name>vm1</name>
    <description>Virtual Machine 1</description>
    <actions>
        <link rel="start"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/start"/>
        <link rel="stop"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/stop"/>
        <link rel="shutdown"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/shutdown"/>
        <link rel="suspend"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/suspend"/>
        <link rel="detach"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/detach"/>
        <link rel="migrate"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/migrate"/>
        <link rel="export"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/export"/>
        <link rel="import"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        <link rel="move"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move"/>
        <link rel="ticket"
          href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/ticket"/>
    </actions>
    <link rel="disks"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks"/>
    <link rel="nics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics"/>
    <link rel="cdroms"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/cdroms"/>
    <link rel="snapshots"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/snapshots"/>
    <link rel="users"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/users"/>
    <link rel="tags"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/tags"/>
    <link rel="permissions"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/permissions"/>
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/statistics"/>
    <type>desktop</type>
    <status>
        <state>up</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os type="RHEL5">
        <boot dev="hd"/>
        <kernel/>
        <initrd/>
        <cmdline/>
    </os>
    <highly_available>
        <enabled>true</enabled>
        <priority>20</priority>
    </highly_available>
    <display>
        <type>vnc</type>
        <port>5910</port>
        <monitors>1</monitors>
    </display>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/api/templates/00000000-0000-0000-0000-000000000000"/>
    <start_time>2010-18-16T13:14:15</start_time>
    <creation_time>2010-08-16T14:24:29</creation_time>
    <origin>rhev</origin>
    <stateless>false</stateless>
    <placement_policy>
        <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>536870912</guaranteed>
    </memory_policy>
    <usb>
        <enabled>true</enabled>
    </usb>
    <custom_properties>
        <custom_property value="124" name="sndbuf"/>
    </custom_properties>
    <guest_info>
        <ip address="192.168.0.25"/>
    </guest_info>
</vm>

Creation of a new virtual machine requires the name, template and cluster elements. Identify the template and cluster elements with the id attribute or name element. See Section 7.2.4, “ Creating a Resource in a Collection ” for more information.

Example 13.2. Creating a virtual machine with 512 MB and boots from the virtual hard disk

POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <name>vm2</name>
    <description>Virtual Machine 2</description>
    <type>desktop</type>
    <memory>536870912</memory>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <os>
      <boot dev="hd"/>
    </os>
</vm>

The name, description, type, memory, cpu topology, os, high_availability, display, timezone, domain, stateless, placement_policy, memory_policy, usb and custom_properties elements are updatable post-creation. See Section 7.3.2, “ Updating a Resource ” for more information.

Example 13.3. Updating a virtual machine to contain 1 GB of memory

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

<vm>
    <memory>1073741824</memory>
</vm>

Removal of a virtual machine requires a DELETE request.

Example 13.4. Removing a virtual machine

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1

HTTP/1.1 204 No Content

13.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:

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”

Table 13.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. [a]
size integer Size of the disk in bytes.
type enumerated The type (function) of the disk device. A list of enumerated values is available in capabilities. See Section 6.1.12, “Disk Types”.
status One of illegal, invalid, locked or ok The status of the disk device. These states are listed in disk_states under capabilities (See Section 6.1.21, “Resource Status States”).
interface enumerated The type of interface driver used to connect to the disk device. A list of enumerated values is available in capabilities. See Section 6.1.15, “Disk Interfaces”.
format enumerated The underlying storage format. A list of enumerated values is available in capabilities. See Section 6.1.14, “Disk Formats”. 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.
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.
[a] Only required when the first disk is being added to a virtual machine that was not itself created from a template.

Example 13.5. 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>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>    
</disk>

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

Example 13.6. 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>

13.1.1. 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 13.7. 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>

13.1.2. Disk Statistics

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

Table 13.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 13.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 13.8. 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.