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).
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 sockets and cores available to the guest.
| |
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.
|
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”).
<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>
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.
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>
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.
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 Accept: application/xml Content-type: application/xml <vm> <memory>1073741824</memory> </vm>
DELETE
request.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 HTTP/1.1 204 No Content
disks
sub-collection represents all virtual hard disk devices on a virtual machine. A disk
representation contains the following elements:
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.
|
![]() ![]() |
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.
|
<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>
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.
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>
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.
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>
statistics
sub-collection for disk-specific statistics. Each statistic
contains the following elements:
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.
|
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.
|
<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>
statistics
sub-collection is read-only.