Chapter 14. Templates

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

Note

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

Table 14.1. Virtual machine template elements

Element Type Description Properties
link rel="disks" relationship A link to the disks sub-collection for virtual machine template resources.
link rel="nics" relationship A link to the nics sub-collection for virtual machine template resources.
link rel="cdroms" relationship A link to the cdroms sub-collection for virtual machine template resources.
link rel="permissions" relationship A link to the permissions sub-collection for virtual machine template permissions. See Section 7.3.7, “ Permissions ”.
type enumerated The type of virtual machine the template provides. A list of enumerated values are available in capabilities. See Section 6.1.8, “Virtual Machine Types”.
status One of illegal, locked or ok The template status. These states are listed in template_states under capabilities (See Section 6.1.21, “Resource Status States”).
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 which the template is configured to boot from.
os initrd string A path to an initrd image to be used with the kernel above.
os cmdline string A kernel command line parameter string to be used with the kernel above.
cluster id= GUID A reference to the template's host cluster. See Chapter 9, Host Clusters.
vm id= GUID A reference to the VM on which this template is based. See Chapter 13, Virtual Machines.
domain id= GUID A reference to the template's domain.
creation_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this template was created.
origin One of rhev, vmware or xen The system from which this template originated.
high_availability complex Set enabled to true if the VM should be automatically restarted if the host crashes. A priority element controls the order in which VMs are re-started.
display complex The display type (either vnc or spice), port, and the number of monitors.
stateless Boolean: true or false A stateless template contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot.
usb complex Defines the USB policy for a virtual machine template. Requires an enabled element set to a Boolean value.
timezone tz database format: Area/Location The the Sysprep timezone setting for a Windows virtual machine template. Only certain timezones are allowed as specified in Appendix D, Timezones.
domain complex The the Sysprep domain setting for a Windows virtual machine template. Requires a name from the domains collection. See Chapter 16, Domains for more information about domains.

Example 14.1. An XML representation of a virtual machine template

<template id="00000000-0000-0000-0000-000000000000"
  href="/api/templates/00000000-0000-0000-0000-000000000000">
    <name>Blank</name>
    <description>Blank template</description>
    <actions>
        <link rel="export"
          href="/api/templates/00000000-0000-0000-0000-000000000000/export"/>
    </actions>
    <link rel="disks"
      href="/api/templates/00000000-0000-0000-0000-000000000000/disks"/>
    <link rel="nics"
      href="/api/templates/00000000-0000-0000-0000-000000000000/nics"/>
    <link rel="cdroms"
      href="/api/templates/00000000-0000-0000-0000-000000000000/cdroms"/>
    <link rel="permissions"
      href="/api/templates/00000000-0000-0000-0000-000000000000/permissions"/>
    <type>server</type>
    <status>
        <state>ok</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os>
        <boot dev="hd"/>
        <kernel/>
        <initrd/>
        <cmdline/>
    </os>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <creation_time>2010-08-16T14:24:29</creation_time>
    <origin>rhev</origin>
    <highly_available>
        <enabled>true</enabled>
        <priority>100</priority>
    </highly_available>
    <display>
        <type>vnc</type>
        <port>5910</port>
        <monitors>1</monitors>
    </display>
    <stateless>false</stateless>
    <usb>
        <enabled>true</enabled>
    </usb>
</template>

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

Example 14.2. Creating a template from a virtual machine

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

<template>
    <name>template1</name>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"/>
</template>

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

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

PUT /api/templates/a03dca95-98cb-430d-89dc-b11482543748 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
    <memory>1073741824</memory>
</template>

Removal of a virtual machine template requires a DELETE request.

Example 14.4. Removing a virtual machine template

DELETE /api/templates/a03dca95-98cb-430d-89dc-b11482543748 HTTP/1.1

HTTP/1.1 204 No Content

Templates contain a number of device sub-collections that follow the same XML representation structure as devices in the vms collection:

14.1.  Export Action

The templates collection contains an export action. Information on the action for importing templates is found in Section 11.2, “ Export Storage Domains ”.
The export action exports a template to an Export storage domain. A destination storage domain is specified with a storage_domain reference. By default, the export action overwrites any existing template with the same name in the destination domain. The exclusive parameter set to true avoids this.

Example 14.5. Action to export a template to an export storage domain

POST /api/templates/00000000-0000-0000-0000-000000000000/export HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    <exclusive>true<exclusive/>
</action>