Red Hat Enterprise Virtualization 3.1
Using the Red Hat Enterprise Virtualization Application Programming Interfaces
Edition 1
Legal Notice
Copyright © 2012 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
This document describes Red Hat Enterprise Virtualization's developer APIs.
- Preface
- I. Introduction
- 1. Introduction
- 2. Authentication and Security
- 3. REST API Beginner Example
- 3.1. Example: Access API Entry Point
- 3.2. Example: List Data Center Collection
- 3.3. Example: List Host Cluster Collection
- 3.4. Example: List Logical Networks Collection
- 3.5. Example: List Host Collection
- 3.6. Example: Approve Host
- 3.7. Example: Create NFS Data Storage
- 3.8. Example: Create NFS ISO Storage
- 3.9. Example: Attach Storage Domains to Data Center
- 3.10. Example: Activate Storage Domains
- 3.11. Example: Create Virtual Machine
- 3.12. Example: Create Virtual Machine NIC
- 3.13. Example: Create Virtual Machine Storage Disk
- 3.14. Example: Attach ISO Image to Virtual Machine
- 3.15. Example: Start Virtual Machine
- 3.16. Example: Check System Events
- 3.17. Example Completion
- 4. Python Beginner Example
- 4.1. Python Quick Start Introduction
- 4.2. Example: Accessing the API Entry Point using Python
- 4.3. Example: Listing the Data Center Collection using Python
- 4.4. Example: Listing the Cluster Collection using Python
- 4.5. Example: Listing the Logical Networks Collection using Python
- 4.6. Example: Listing the Host Collection using Python
- 4.7. Example: Approving a Host using Python
- 4.8. Example: Creating NFS Data Storage using Python
- 4.9. Example: Creating NFS ISO Storage using Python
- 4.10. Example: Attaching Storage Domains to a Data Center using Python
- 4.11. Example: Activating Storage Domains using Python
- 4.12. Example: Creating a Virtual Machine using Python
- 4.13. Example: Creating a Virtual Machine NIC using Python
- 4.14. Example: Creating a Virtual Machine Storage Disk using Python
- 4.15. Example: Attaching an ISO Image to a Virtual Machine using Python
- 4.16. Example: Starting a Virtual Machine using Python
- 4.17. Example: Checking System Events using Python
- II. REST Application Programming Interface
- 5. Entry Point
- 6. Compatibility Level Versions
- 7. Capabilities
- 7.1. Version-Dependent Capabilities
- 7.2. Current Version
- 7.3. Features
- 7.4. CPUs
- 7.5. Power Managers
- 7.6. Fence Types
- 7.7. Storage Types
- 7.8. Storage Domain Types
- 7.9. Virtual Machine Types
- 7.10. Boot Devices
- 7.11. Display Types
- 7.12. NIC Interface Types
- 7.13. OS Types
- 7.14. Disk Formats
- 7.15. Disk Interfaces
- 7.16. Virtual Machine Affinities
- 7.17. Custom Properties
- 7.18. Boot Protocols
- 7.19. Error Handling
- 7.20. Storage Formats
- 7.21. Virtual Machine Device Types
- 7.22. Gluster Volume Types
- 7.23. Gluster Transport Types
- 7.24. Guster Acces Protocols
- 7.25. Resource Status States
- 7.26. Permits
- 7.27. Scheduling Policies
- 8. Common Features
- 9. Data Centers
- 10. Host Clusters
- 11. Networks
- 12. Storage Domains
- 13. Hosts
- 14. Virtual Machines
- 15. Floating Disks
- 16. Templates
- 17. Virtual Machine Pools
- 18. Domains
- 19. Roles
- 20. Groups
- 21. Users
- 22. Tags
- 23. Events
- III. Python Sofware Development Kit
- 24. Software Development Kit Overview
- 25. Using the Software Development Kit
- 25.1. Connecting to the API using Python
- 25.2. Resources and Collections
- 25.3. Retrieving Resources from a Collection
- 25.4. Retrieving a Specific Resource from a Collection
- 25.5. Retrieving a List of Resources from a Collection
- 25.6. Adding a Resource to a Collection
- 25.7. Updating a Resource in a Collection
- 25.8. Removing a Resource from a Collection
- 25.9. Handling Errors
- 26. Python Reference Documentation
- A. API Usage with cURL
- B. Importing Certificates
- C. Enumerated Value Translation
- D. Event Codes
- E. Timezones
- F. Revision History
The Red Hat Enterprise Virtualization platform is a richly featured virtualization platform that provides fully integrated management across virtual machines with multiple hosts. It is based on KVM (Kernel-based Virtual Machine), the leading open source virtualization platform, and provides superior technical capabilities. The platform offers scalability in the management of a large number of physical hosts and virtual machines.
This guide explains how to use Red Hat Enterprise Virtualization Manager's Representational State Transfer (REST) API. This document covers the fundamentals of the REST architectural concepts in the context of a virtualization environment and provides examples of the API in operation.
In addition Red Hat Enterprise Virtualization also provides a Python Software Development Kit (SDK) . The SDK provides Python libraries for interacting with the REST API. The installation and use of the Python SDK is documetned in this guide.
The target audience for this guide includes developers and system administrators who aim to integrate their Red Hat Enterprise Virtualization environment with third-party applications and scripts.
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
Press Enter to execute the command.Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in
mono-spaced bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose → → from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose → → from the main menu bar. Next, choose → from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose → from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold ItalicProportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, typesshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.Themount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.
Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in
mono-spaced roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
mono-spaced roman but add syntax highlighting as follows:
static int kvm_vm_ioctl_deassign_device(struct kvm *kvm,
struct kvm_assigned_pci_dev *assigned_dev)
{
int r = 0;
struct kvm_assigned_dev_kernel *match;
mutex_lock(&kvm->lock);
match = kvm_find_assigned_dev(&kvm->arch.assigned_dev_head,
assigned_dev->assigned_dev_id);
if (!match) {
printk(KERN_INFO "%s: device hasn't been assigned before, "
"so cannot be deassigned\n", __func__);
r = -EINVAL;
goto out;
}
kvm_deassign_device(kvm, match);
kvm_free_assigned_device(kvm, match);
out:
mutex_unlock(&kvm->lock);
return r;
}
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.
Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:
- search or browse through a knowledgebase of technical support articles about Red Hat products.
- submit a support case to Red Hat Global Support Services (GSS).
- access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/ against the product Red Hat Enterprise Virtualization Manager.
When submitting a bug report, be sure to mention the manual's identifier: Guides-Developer
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Red Hat will make commercially reasonable efforts to ensure that applications developed for a certain version of Red Hat Enterprise Virtualization (RHEV) will work unmodified with future versions of RHEV within the same major release. Compatibility between different major releases is not guaranteed.
Red Hat Enterprise Virtualization exposes a number of interfaces for interacting with the components of the virtualization environment. These interfaces are in addition to the user interfaces provided by the Red Hat Enterprise Virtualization Manager Administration, User, and Reports Portals. Many of these interfaces are fully supported. Some however are supported only for read access or only when your use of them has been explicitly requested by Red Hat Support.
Supported Interfaces for Read and Write Access
Direct interaction with these interfaces is supported and encouraged for both read and write access:
- Representational State Transfer (REST) API
- The REST API exposed by the Red Hat Enterprise Virtualization Manager is a fully supported interface for interacting with Red Hat Enterprise Virtualization Manager.
- Software Development Kit (SDK)
- The SDK provided by the rhevm-sdk package is a fully supported interface for interacting with Red Hat Enterprise Virtualization Manager.
- Command Line Shell
- The command line shell provided by the rhevm-cli package is a fully supported interface for interacting with the Red Hat Enterprise Virtualization Manager.
- VDSM Hooks
- The creation and use of VDSM hooks to trigger modification of virtual machines based on custom properties specified in the Administration Portal is supported on Red Hat Enterprise Linux virtualization hosts. The use of VDSM Hooks on virtualization hosts running Red Hat Enterprise Virtualization Hypervisor is not currently supported.
Supported Interfaces for Read Access
Direct interaction with these interfaces is supported and encouraged only for read access. Use of these interfaces for write access is not supported unless explicitly requested by Red Hat Support:
- Red Hat Enterprise Virtualization Manager History Database
- Read access to the Red Hat Enterprise Virtualization Manager history database using the database views specified in the Administration Guide is supported. Write access is not supported.
- Libvirt on Virtualization Hosts
- Read access to
libvirtusing thevirsh -rcommand is a supported method of interacting with virtualization hosts. Write access is not supported.
Unsupported Interfaces
Direct interaction with these interfaces is not supported unless your use of them is explicitly requested by Red Hat Support:
- The vdsClient Command
- Use of the
vdsClientcommand to interact with virtualization hosts is not supported unless explicitly requested by Red Hat Support. - Red Hat Enterprise Virtualization Hypervisor Console
- Console access to Red Hat Enterprise Virtualization Hypervisor outside of the provided text user interface for configuration is not supported unless explicitly requested by Red Hat Support.
- Red Hat Enterprise Virtualization Manager Database
- Direct access to and manipulation of the Red Hat Enterprise Virtualization Manager database is not supported unless explicitly requested by Red Hat Support.
Important
Red Hat Support will not debug user created scripts or hooks except where it can be demonstrated that there is an issue with the interface being used rather than the user created script itself. For more general information about Red Hat support policies see https://access.redhat.com/support/offerings/production/soc.html.
Table of Contents
- 1. Introduction
- 2. Authentication and Security
- 3. REST API Beginner Example
- 3.1. Example: Access API Entry Point
- 3.2. Example: List Data Center Collection
- 3.3. Example: List Host Cluster Collection
- 3.4. Example: List Logical Networks Collection
- 3.5. Example: List Host Collection
- 3.6. Example: Approve Host
- 3.7. Example: Create NFS Data Storage
- 3.8. Example: Create NFS ISO Storage
- 3.9. Example: Attach Storage Domains to Data Center
- 3.10. Example: Activate Storage Domains
- 3.11. Example: Create Virtual Machine
- 3.12. Example: Create Virtual Machine NIC
- 3.13. Example: Create Virtual Machine Storage Disk
- 3.14. Example: Attach ISO Image to Virtual Machine
- 3.15. Example: Start Virtual Machine
- 3.16. Example: Check System Events
- 3.17. Example Completion
- 4. Python Beginner Example
- 4.1. Python Quick Start Introduction
- 4.2. Example: Accessing the API Entry Point using Python
- 4.3. Example: Listing the Data Center Collection using Python
- 4.4. Example: Listing the Cluster Collection using Python
- 4.5. Example: Listing the Logical Networks Collection using Python
- 4.6. Example: Listing the Host Collection using Python
- 4.7. Example: Approving a Host using Python
- 4.8. Example: Creating NFS Data Storage using Python
- 4.9. Example: Creating NFS ISO Storage using Python
- 4.10. Example: Attaching Storage Domains to a Data Center using Python
- 4.11. Example: Activating Storage Domains using Python
- 4.12. Example: Creating a Virtual Machine using Python
- 4.13. Example: Creating a Virtual Machine NIC using Python
- 4.14. Example: Creating a Virtual Machine Storage Disk using Python
- 4.15. Example: Attaching an ISO Image to a Virtual Machine using Python
- 4.16. Example: Starting a Virtual Machine using Python
- 4.17. Example: Checking System Events using Python
Red Hat Enterprise Virtualization Manager provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their Red Hat Enterprise Virtualization environment outside of the standard web interface. The REST API is useful for developers and administrators who aim to integrate the functionality of a Red Hat Enterprise Virtualization environment with custom scripts or external applications that access the API via the standard Hypertext Transfer Protocol (HTTP).
The benefits of the REST API are:
- Broad client support - Any programming language, framework, or system with support for HTTP protocol can use the API;
- Self descriptive - Client applications require minimal knowledge of the virtualization infrastructure as many details are discovered at runtime;
- Resource-based model - The resource-based REST model provides a natural way to manage a virtualization platform.
This provides developers and administrators with the ability to:
- Integrate with enterprise IT systems.
- Integrate with third-party virtualization software.
- Perform automated maintenance or error checking tasks.
- Automate repetitive tasks in a Red Hat Enterprise Virtualization environment with scripts.
This documentation acts as a reference to the Red Hat Enterprise Virtualization Manager REST API. It aims to provide developers and administrators with instructions and examples to help harness the functionality of their Red Hat Enterprise Virtualization environment through the REST API either directly or using the provided Python libraries.
Representational State Transfer (REST) is a design architecture that focuses on resources for a specific service and their representations. A resource representation is a key abstraction of information that corresponds to one specific managed element on a server. A client sends a request to a server element located at a Uniform Resource Identifier (URI) and performs operations with standard HTTP methods, such as
GET, POST, PUT, and DELETE. This provides a stateless communication between the client and server where each request acts independent of any other request and contains all necessary information to complete the request.
This guide requires the following:
- A networked installation of Red Hat Enterprise Virtualization Manager, which includes the REST API;
- A client or programming library that initiates and receives HTTP requests from the REST API. For example:
- Red Hat Enterprise Virtualization 3.1 provides a Python software development kit (SDK) that interacts with the REST API. This guide includes a Python Beginner Example to help developers get started with using the SDK.
- This guide includes basic instructions on use with cURL in Appendix A, API Usage with cURL.
- Knowledge of Hypertext Transfer Protocol (HTTP), which is the protocol used for REST API interactions. The Internet Engineering Task Force provides a Request for Comments (RFC) explaining the Hypertext Transfer Protocol at http://www.ietf.org/rfc/rfc2616.txt; and,
- Knowledge of Extensible Markup Language (XML), which the API uses to construct resource representations. The W3C provides a full specification on XML at http://www.w3.org/TR/xml/.
Additionally, to use the Python SDK you will need to download and install the rhevm-sdk package. This package is available to systems subscribed to a
Red Hat Enterprise Virtualization entitlement pool if using certificate-based Red Hat Network, or the rhel-x86_64-server-6-rhevm-3.1 channel if using Red Hat Network classic. See the Red Hat Enterprise Virtualization Installation Guide for more information on subscribing your system(s) to download software from these locations.
This chapter provides information on authorization through Red Hat Enterprise Virtualization Manager's security.
The API requires Hypertext Transfer Protocol Secure (HTTPS) [1] for secure transport-level encryption of requests. This involves a process of attaining a certificate from your Red Hat Enterprise Virtualization Manager server and importing it into your client's certificate store.
Important
Attain your certificate from the Red Hat Enterprise Virtualization Manager server using a secure network connection.
Procedure 2.1. Attain a certificate
This process helps a user attain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to the client machine. A user achieves this using one of three methods:
- Method 1 - Use a command line tool to download the certificate from the server. Examples of command line tools include cURL and Wget; both are available for multiple platforms.
- If using cURL:
curl -o rhevm.cer http://[rhevm-server]/ca.crt
- If using Wget:
wget -O rhevm.cer http://[rhevm-server]/ca.crt
- Method 2 - Use a web browser to navigate to the certificate located at:
http://[rhevm-server]/ca.crt
Depending on the chosen browser, the certificate either downloads or imports into the browser's keystore.- If the browser downloads the certificate: save the file as
rhevm.cer.If the browser imports the certificate: export it from the browser's certification options and save it asrhevm.cer.
- Method 3 - Access your Red Hat Enterprise Virtualization Manager server either physically or through a secure shell (SSH) client, export the certificate from the server's keystore and copy it to your client machine.
- Access your Red Hat Enterprise Virtualization Manager server as the
rootuser. - Export a certificate from the server's keystore using the Java keytool management utility:
keytool -exportcert -keystore /etc/pki/rhevm/.keystore -alias rhevm -storepass mypass -file rhevm.cer
This creates a certificate file calledrhevm.cer. - Copy the certificate to the client machine using the
scpcommand:scp rhevm.cer [username]@[client-machine]:[directory]
Each of the three methods results in a certificate file named
rhevm.cer on your client machine. An API user imports this file into the client's certificate store.
Procedure 2.2. Import a certificate to your client
- A certificate import for your client relies on how the client itself stores and interprets certificates. This guide contains some examples on importing certificates in Appendix B, Importing Certificates. For other clients, please refer to your client documentation for more information on importing a certificate.
Any user with a Red Hat Enterprise Virtualization account has access to the REST API. An API user submits a mandatory Red Hat Enterprise Virtualization Manager username and password with all requests to the API. Each request uses HTTP Basic Authentication [2] to encode these credentials. If a request does not include an appropriate
Authorization header, the API sends a 401 Authorization Required as a result:
Example 2.1. Access to the REST API without appropriate credentials
HEAD [base] HTTP/1.1 Host: [host] HTTP/1.1 401 Authorization Required
Request are issued with an
Authorization header for the specified realm. An API user encodes an appropriate Red Hat Enterprise Virtualization Manager domain and user in the supplied credentials with the username@domain:password convention.
The following table shows the process for encoding credentials in base64.
Table 2.1. Encoding credentials for API access
| Item | Value |
|---|---|
| username | rhevmadmin |
| domain | domain.example.com |
| password | 123456 |
| unencoded credentials | rhevmadmin@domain.example.com:123456 |
| base64 encoded credentials | cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 |
An API user provides the base64 encoded credentials as shown:
Example 2.2. Access to the REST API with appropriate credentials
HEAD [base] HTTP/1.1 Host: [host] Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 HTTP/1.1 200 OK ...
Important
Basic authentication involves potentially sensitive information, such as passwords, sent as plain text. REST API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests. See Section 2.1, “TLS/SSL Certification” for more information.
Important
Some base64 libraries break the result into multiple lines and terminate each line with a newline character. This breaks the header and causes a faulty request. The Authorization header requires the encoded credentials on a single line within the header.
The API also provides the ability for authentication session support. An API user sends an initial request with authentication details, then sends all subsequent requests using a session cookie to authenticate. The following procedure demonstrates how to use an authenticated session.
Procedure 2.3. Requesting an authenticated session
- Send a request with the
AuthorizationandPrefer: persistent-authHEAD [base] HTTP/1.1 Host: [host] Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 Prefer: persistent-auth HTTP/1.1 200 OK ...
This returns a response with the following header:Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/api; Secure
Note theJSESSIONID=value. In this example the value isJSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK. - Send all subsequent requests with the
Prefer: persistent-authandcookieheader with theJSESSIONID=value. TheAuthorizationis no longer needed when using an authenticated session.HEAD [base] HTTP/1.1 Host: [host] Prefer: persistent-auth cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK HTTP/1.1 200 OK ...
- When the session is no longer required, perform a request to the sever without the
Prefer: persistent-authheader.HEAD [base] HTTP/1.1 Host: [host] Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 HTTP/1.1 200 OK ...
[1]
HTTPS is described in RFC 2818 HTTP Over TLS.
[2]
Basic Authentication is described in RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.
- 3.1. Example: Access API Entry Point
- 3.2. Example: List Data Center Collection
- 3.3. Example: List Host Cluster Collection
- 3.4. Example: List Logical Networks Collection
- 3.5. Example: List Host Collection
- 3.6. Example: Approve Host
- 3.7. Example: Create NFS Data Storage
- 3.8. Example: Create NFS ISO Storage
- 3.9. Example: Attach Storage Domains to Data Center
- 3.10. Example: Activate Storage Domains
- 3.11. Example: Create Virtual Machine
- 3.12. Example: Create Virtual Machine NIC
- 3.13. Example: Create Virtual Machine Storage Disk
- 3.14. Example: Attach ISO Image to Virtual Machine
- 3.15. Example: Start Virtual Machine
- 3.16. Example: Check System Events
- 3.17. Example Completion
This chapter provides an example to demonstrate the REST API's ability to setup a basic Red Hat Enterprise Virtualization environment and create a virtual machine.
In addition to the standard prerequisites (see Section 1.2, “Prerequisites”), this example requires the following:
- A networked and configured host containing Red Hat Enterprise Virtualization Hypervisor;
- An ISO file containing a desired virtual machine operating system to install. This chapter uses Red Hat Enterprise Linux Server 6 for our installation ISO example; and
- Red Hat Enterprise Virtualization's rhevm-iso-uploader tool to upload your chosen operating system ISO file.
This example uses cURL to demonstrate REST requests with a client application. Find out more about cURL use with the REST API in Appendix A, API Usage with cURL. Note that any application capable of HTTP requests can substitute for cURL.
Important
For simplicity, the HTTP request headers in this example omit the
Host: and Authorization: fields. However, these fields are mandatory and require data specific to your installation of Red Hat Enterprise Virtualization Manager.
Important
All cURL examples include placeholders for authentication details (
USER:PASS) and certificate location (CERT). Ensure all requests performed with cURL fulfil certification and authentication requirements. See Chapter 2, Authentication and Security and Appendix A, API Usage with cURL for more information.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for the
id attribute for each resource. Identifier codes in this example might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.
The following request retrieves a representation of the main entry point of the API.
Example 3.1. Access the API entry point
Request:
GET /api HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]\ --cacert[CERT]https://[RHEVM Host]:8443/api
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<api>
<link rel="capabilities" href="/api/capabilities"/>
<link rel="clusters" href="/api/clusters"/>
<link rel="clusters/search" href="/api/clusters?search={query}"/>
<link rel="datacenters" href="/api/datacenters"/>
<link rel="datacenters/search" href="/api/datacenters?search={query}"/>
<link rel="events" href="/api/events"/>
<link rel="events/search" href="/api/events?search={query}"/>
<link rel="hosts" href="/api/hosts"/>
<link rel="hosts/search" href="/api/hosts?search={query}"/>
<link rel="networks" href="/api/networks"/>
<link rel="roles" href="/api/roles"/>
<link rel="storagedomains" href="/api/storagedomains"/>
<link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
<link rel="tags" href="/api/tags"/>
<link rel="templates" href="/api/templates"/>
<link rel="templates/search" href="/api/templates?search={query}"/>
<link rel="users" href="/api/users"/>
<link rel="groups" href="/api/groups"/>
<link rel="domains" href="/api/domains"/>
<link rel="vmpools" href="/api/vmpools"/>
<link rel="vmpools/search" href="/api/vmpools?search={query}"/>
<link rel="vms" href="/api/vms"/>
<link rel="vms/search" href="/api/vms?search={query}"/>
<special_objects>
<link rel="templates/blank"
href="/api/templates/00000000-0000-0000-0000-000000000000"/>
<link rel="tags/root"
href="/api/tags/00000000-0000-0000-0000-000000000000"/>
</special_objects>
<product_info>
<name>Red Hat Enterprise Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="0" major="3"/>
</product_info>
<summary>
<vms>
<total>5</total>
<active>0</active>
</vms>
<hosts>
<total>1</total>
<active>1</active>
</hosts>
<users>
<total>1</total>
<active>1</active>
</users>
<storage_domains>
<total>2</total>
<active>2</active>
</storage_domains>
</summary>
</api>
The entry point provides a user with links to the collections in a virtualization environment. The
rel= attribute of each collection link provides a reference point for each link. The next step in this example examines the datacenter collection, which is available through the rel="datacenter" link.
The entry point also contains other data such as
product_info, special_objects and summary. This data is covered in chapters outside this example.
Red Hat Enterprise Virtualization Manager creates a
Default data center on installation. This example uses the Default data center as the basis for our virtual environment.
The following request retrieves a representation of the data center collection:
Example 3.2. List data center collection
Request:
GET /api/datacenters HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]\ --cacert[CERT]\ https://[RHEVM Host]:8443/api/datacenters
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<data_centers>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988">
<name>Default</name>
<description>The default Data Center</description>
<link rel="storagedomains"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/
storagedomains"/>
<link rel="permissions"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/permissions"/>
<storage_type>nfs</storage_type>
<storage_format>v1</storage_format>
<version minor="0" major="3"/>
<supported_versions>
<version minor="0" major="3"/>
</supported_versions>
<status>
<state>up</state>
</status>
</data_center>
</data_centers>
Note the
id code of your Default data center. This code identifies this data center in relation to other resources of your virtual environment.
The data center also contains a link to the
storagedomains sub-collection. The data center uses this sub-collection to attach storage domains from the storagedomains main collection, which this example covers later.
Red Hat Enterprise Virtualization Manager creates a
Default host cluster on installation. This example uses the Default cluster to group resources in your Red Hat Enterprise Virtualization environment.
The following request retrieves a representation of the cluster collection:
Example 3.3. List host clusters collection
Request:
GET /api/clusters HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]\ --cacert[CERT]\ https://[RHEVM Host]:8443/api/clusters
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<clusters>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
<name>Default</name>
<description>The default server cluster</description>
<link rel="networks"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
<link rel="permissions"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
<cpu id="Intel Penryn Family"/>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
<memory_policy>
<overcommit percent="100"/>
<transparent_hugepages>
<enabled>false</enabled>
</transparent_hugepages>
</memory_policy>
<scheduling_policy/>
<version minor="0" major="3"/>
<error_handling>
<on_error>migrate</on_error>
</error_handling>
</cluster>
</clusters>
Note the
id code of your Default host cluster. This code identifies this host cluster in relation to other resources of your virtual environment.
The
Default cluster is associated with the Default data center through a relationship using the id and href attributes of the data_center element.
The
networks sub-collection contains a list of associated network resources for this cluster. The next section examines the networks collection in more detail.
Red Hat Enterprise Virtualization Manager creates a default
rhevm network on installation. This network acts as the management network for Red Hat Enterprise Virtualization Manager to access hypervisor hosts.
This network is associated with our
Default cluster and is a member of the Default data center. This example uses the rhevm network to connect our virtual machines.
The following request retrieves a representation of the logical networks collection:
Example 3.4. List logical networks collection
Request:
GET /api/networks HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]\ --cacert[CERT]\ https://[RHEVM Host]:8443/api/networks
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<networks>
<network id="00000000-0000-0000-0000-000000000009"
href="/api/networks/00000000-0000-0000-0000-000000000009">
<name>rhevm</name>
<description>Management Network</description>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
<stp>false</stp>
<status>
<state>operational</state>
</status>
<display>false</display>
</network>
</networks>
The
rhevm network is attached to the Default data center through a relationship using the data center's id code.
The
rhevm network is also attached to the Default cluster through a relationship in the cluster's network sub-collection.
This example uses a Red Hat Enterprise Virtualization Hypervisor host. Red Hat Enterprise Virtualization Manager automatically registers any configured Red Hat Enterprise Virtualization Hypervisor. This example retrieves a representation of the hosts collection and shows a Red Hat Enterprise Virtualization Hypervisor host named
hypervisor registered with the virtualization environment.
Example 3.5. List hosts collection
Request:
GET /api/hosts HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]\ --cacert[CERT]\ https://[RHEVM Host]:8443/api/hosts
Result:
HTTP/1.1 200 OK
Accept: application/xml
<hosts>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
<name>hypervisor</name>
<actions>
<link rel="install"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/install"/>
<link rel="activate"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/activate"/>
<link rel="fence"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/fence"/>
<link rel="deactivate"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/deactivate"/>
<link rel="approve"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve"/>
<link rel="iscsilogin"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsilogin"/>
<link rel="iscsidiscover"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsidiscover"/>
<link rel="commitnetconfig"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/
commitnetconfig"/>
</actions>
<link rel="storage"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/storage"/>
<link rel="nics"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/nics"/>
<link rel="tags"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/tags"/>
<link rel="permissions"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/permissions"/>
<link rel="statistics"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/statistics"/>
<address>10.64.14.110</address>
<status>
<state>non_operational</state>
</status>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<port>54321</port>
<storage_manager>true</storage_manager>
<power_management>
<enabled>false</enabled>
<options/>
</power_management>
<ksm>
<enabled>false</enabled>
</ksm>
<transparent_hugepages>
<enabled>true</enabled>
</transparent_hugepages>
<iscsi>
<initiator>iqn.1994-05.com.example:644949fe81ce</initiator>
</iscsi>
<cpu>
<topology cores="2"/>
<name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
<speed>2993</speed>
</cpu>
<summary>
<active>0</active>
<migrating>0</migrating>
<total>0</total>
</summary>
</host>
</hosts>
Note the
id code of your Default host. This code identifies this host in relation to other resources of your virtual environment.
This host is a member of the
Default cluster and accessing the nics sub-collection shows this host has a connection to the rhevm network.
The
hypervisor host resource contains an approve action. A user accesses this action's URI with a POST request.
Example 3.6. Approve a pre-configured Red Hat Enterprise Virtualization Hypervisor host
Request:
POST /api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action/>" \
https://[RHEVM Host]:8443/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve
The POST request requires a body for the message entities to initiate an action. Since the action does not require additional parameters, the body contains an empty
action element.
Use the
approve action only for Red Hat Enterprise Virtualization Hypervisor hosts. Red Hat Enterprise Linux hosts require a different process to connect to the virtualization environment.
This approves and activates the host for use in your virtual environment. The
status for hypervisor changes from non_operational to up.
An NFS data storage domain is an exported NFS share attached to a data center and provides storage for virtualized guest images. Creation of a new storage domain requires a
POST request, with the storage domain representation included, sent to the URL of the storage domain collection.
Example 3.7. Create an NFS data storage domain
Request:
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>data1</name>
<type>data</type>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/data1</path>
</storage>
<host>
<name>hypervisor</name>
</host>
</storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>data1</name><type>data</type> \
<storage><type>nfs</type><address>192.168.0.10</address> \
<path>/data1</path></storage> \
<host><name>hypervisor</name></host></storage_domain>" \
https://[RHEVM Host]:8443/api/storagedomains
The API creates a NFS data storage domain called
data1 with an export path of 192.168.0.10:/data1 and sets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource.
Result:
HTTP/1.1 200 OK
Accept: application/xml
<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"
href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac">
<name>data1</name>
<link rel="permissions"
href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/
permissions"/>
<link rel="files"
href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/files"/>
<type>data</type>
<master>false</master>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/data1</path>
</storage>
<available>175019917312</available>
<used>27917287424</used>
<committed>10737418240</committed>
<storage_format>v1</storage_format>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>
An NFS ISO storage domain is a mounted NFS share attached to a data center and provides storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Creation of a new storage domain requires a
POST request, with the storage domain representation included, sent to the URL of the storage domain collection.
Example 3.8. Create an NFS ISO storage domain
Request:
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>iso1</name>
<type>iso</type>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/iso1</path>
</storage>
<host>
<name>hypervisor</name>
</host>
</storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>iso1</name><type>iso</type> \
<storage><type>nfs</type><address>192.168.0.10</address> \
<path>/iso1</path></storage> \
<host><name>hypervisor</name></host></storage_domain>" \
https://[RHEVM Host]:8443/api/storagedomains
The API creates a NFS iso storage domain called
iso1 with an export path of 192.168.0.10:/iso1 and gets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource.
Result:
HTTP/1.1 200 OK
Accept: application/xml
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da">
<name>iso1</name>
<link rel="permissions"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
permissions"/>
<link rel="files"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files"/>
<type>iso</type>
<host id="" href="">
<master>false</master>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/iso1</path>
</storage>
<available>82678120448</available>
<used>18253611008</used>
<committed>0</committed>
<storage_format>v1</storage_format>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>
The following example attaches the
data1 and iso1 storage domains to the Default data center.
Example 3.9. Attach data1 storage domain to the Default data center
Request:
POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml <storage_domain> <name>data1</name> </storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>data1</name></storage_domain>" \
https://[RHEVM Host]:8443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains
Example 3.10. Attach iso1 storage domain to the Default data center
Request:
POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml <storage_domain> <name>iso1</name> </storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>iso1</name></storage_domain>" \
https://[RHEVM Host]:8443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains
These
POST requests place our two new storage_domain resources in the storagedomains sub-collection of the Default data center. This means the storagedomain sub-collection contains attached storage domains of the data center.
This example activates the
data1 and iso1 storage domains for the Red Hat Enterprise Virtualization Manager's use.
Example 3.11. Activate data1 storage domain
Request:
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/ 9ca7cb40-9a2a-4513-acef-dc254af57aac/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action/>" \
https://[RHEVM Host]:8443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/activate
Example 3.12. Activate iso1 storage domain
Request:
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/ 00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action/>"
https://[RHEVM Host]:8443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate
This activates both storage domains for use with the data center.
The following example creates a virtual machine called
vm1 on the Default cluster using the virtualization environment's Blank template as a basis. The request also defines the virtual machine's memory as 512 MB and sets the boot device to a virtual hard disk.
Example 3.13. Create a virtual machine
Request:
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm1</name>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot dev="hd"/>
</os>
</vm>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<vm><name>vm1</name><cluster><name>default</name> \
</cluster><template><name>Blank</name></template> \
<memory>536870912</memory><os><boot dev='hd'/></os></vm>" \
https://[RHEVM Host]:8443/api/vms
Result:
HTTP/1.1 200 OK
Accept: application/xml
<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
<name>vm1</name>
<actions>
<link rel="shutdown"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
<link rel="start"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
<link rel="stop"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
<link rel="suspend"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/>
<link rel="detach"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/>
<link rel="export"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/>
<link rel="move"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/>
<link rel="ticket"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/>
<link rel="migrate"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/>
</actions>
<link rel="disks"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/>
<link rel="nics"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/>
<link rel="cdroms"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/>
<link rel="snapshots"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/>
<link rel="tags"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/>
<link rel="permissions"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/>
<link rel="statistics"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/>
<type>desktop</type>
<status>
<state>down</state>
</status>
<memory>536870912</memory>
<cpu>
<topology cores="1" sockets="1"/>
</cpu>
<os type="Unassigned">
<boot dev="cdrom"/>
</os>
<high_availability>
<enabled>false</enabled>
<priority>0</priority>
</high_availability>
<display>
<type>spice</type>
<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>2011-06-15T04:48:02.167Z</start_time>
<creation_time>2011-06-15T14:48:02.078+10:00</creation_time>
<origin>rhev</origin>
<stateless>false</stateless>
<placement_policy>
<affinity>migratable</affinity>
</placement_policy>
<memory_policy>
<guaranteed>536870912</guaranteed>
</memory_policy>
</vm>
The following example creates a virtual network interface to connect the example virtual machine to the
rhevm network.
Example 3.14. Create a virtual machine NIC
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml
<nic>
<interface>virtio</interface>
<name>nic1</name>
<network>
<name>rhevm</name>
</network>
</nic>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<nic><name>nic1</name><network><name>rhevm</name></network></nic>" \
https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics
The following example creates an 8 GB Copy-On-Write storage disk for the example virtual machine.
Example 3.15. Create a virtual machine storage disk
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<storage_domains>
<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"/>
</storage_domains>
<size>8589934592</size>
<type>system</type>
<interface>virtio</interface>
<format>cow</format>
<bootable>true</bootable>
</disk>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<disk><storage_domains> \
<storage_domain id='9ca7cb40-9a2a-4513-acef-dc254af57aac'/> \
</storage_domains><size>8589934592</size><type>system</type> \
<interface>virtio</interface><format>cow</format> \
<bootable>true</bootable></disk>" \
https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks
The
storage_domain element tells the API to store the disk on the data1 storage domain.
The boot media for our example virtual machine requires an CD-ROM or DVD ISO image for an operating system installation. This example uses a Red Hat Enterprise Server 6 ISO image for installation.
ISO images must be available in the
iso1 ISO domain for the virtual machines to use. Red Hat Enterprise Virtualization Platform provides an uploader tool that ensures that the ISO images are uploaded into the correct directory path with the correct user permissions.
Once the ISO is uploaded, an API user requests the ISO storage domain's
files sub-collection to view the file resource:
Example 3.16. View the files sub-collection in an ISO storage domain
Request:
GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]--cacert[CERT]\ https://[RHEVM Host]:8443/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files
The API returns the following representation of the files sub-collection:
<files>
<file id="rhel-server-6.0-x86_64-dvd.iso"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
files/rhel-server-6.0-x86_64-dvd.iso.iso">
<name>rhel-server-6.0-x86_64-dvd.iso.iso</name>
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
</file>
</files>
An API user attaches the
rhel-server-6.0-x86_64-dvd.iso to our example virtual machine.
Example 3.17. Attach an ISO image to the virtual machine
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms HTTP/1.1 Accept: application/xml Content-type: application/xml <cdrom> <file id="rhel-server-6.0-x86_64-dvd.iso"/> </cdrom>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>" \
https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms
The virtual environment is complete and the virtual machine contains all necessary components to function. This example starts the virtual machine using the
start action.
Example 3.18. Start the virtual machine
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<vm>
<os>
<boot dev="cdrom"/>
</os>
</vm>
</action>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action><vm><os><boot dev='cdrom'/></os></vm></action>" \
https://[RHEVM Host]:8443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start
The additional message entity sets the virtual machine's boot device to CD-ROM for this boot only. This enables the virtual machine to install Red Hat Enterprise Server 6 from the attached ISO image. The boot device reverts back to
disk for all future boots.
The
start action for the vm1 creates several entries in the events collection. This example lists the events collection and identifies events specific to the API starting a virtual machine.
Example 3.19. List the events collection
Request:
GET /api/events HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u[USER:PASS]\ --cacert[CERT]\ https://[RHEVM Host]:8443/api/events
Result:
<events>
...
<event id="103" href="/api/events/103">
<description>User admin logged out.</description>
<code>31</code>
<severity>normal</severity>
<time>2011-06-29T17:42:41.544+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
<event id="102" href="/api/events/102">
<description>vm1 was started by admin (Host: hypervisor).</description>
<code>153</code>
<severity>normal</severity>
<time>2011-06-29T17:42:41.499+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"/>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"/>
</event>
<event id="101" href="/api/events/101">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-06-29T17:42:40.505+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
...
</events>
The following events occur:
id="101"- The API authenticates with theadminuser's username and password.id="102"- The API, acting as theadminuser, startsvm1on thehypervisorhost.id="103"- The API logs out of theadminuser account.
- 4.1. Python Quick Start Introduction
- 4.2. Example: Accessing the API Entry Point using Python
- 4.3. Example: Listing the Data Center Collection using Python
- 4.4. Example: Listing the Cluster Collection using Python
- 4.5. Example: Listing the Logical Networks Collection using Python
- 4.6. Example: Listing the Host Collection using Python
- 4.7. Example: Approving a Host using Python
- 4.8. Example: Creating NFS Data Storage using Python
- 4.9. Example: Creating NFS ISO Storage using Python
- 4.10. Example: Attaching Storage Domains to a Data Center using Python
- 4.11. Example: Activating Storage Domains using Python
- 4.12. Example: Creating a Virtual Machine using Python
- 4.13. Example: Creating a Virtual Machine NIC using Python
- 4.14. Example: Creating a Virtual Machine Storage Disk using Python
- 4.15. Example: Attaching an ISO Image to a Virtual Machine using Python
- 4.16. Example: Starting a Virtual Machine using Python
- 4.17. Example: Checking System Events using Python
This chapter provides a series of examples demonstrating the steps to create a virtual machine within a basic Red Hat Enterprise Virtualization environment, using the Python SDK.
These examples use the ovirtsdk Python library provided by the rhevm-sdk package. This package is available to systems subscribed to a
Red Hat Enterprise Virtualization entitlement pool if using certificate-based Red Hat Network, or the rhel-x86_64-server-6-rhevm-3.1 channel if using Red Hat Network classic. See the Red Hat Enterprise Virtualization Installation Guide for more information on subscribing your system(s) to download software from these locations.
You will also need:
- A networked installation of Red Hat Enterprise Virtualization Manager.
- A networked and configured Red Hat Enterprise Virtualization Hypervisor.
- An ISO image file containing an operating system for installation on a virtual machine.
- A working understanding of both the logical and physical objects that make up a Red Hat Enterprise Virtualization environment.
- A working understanding of the Python programming language.
Important
All Python examples include placeholders for authentication details (
USER for user name, and PASS for password). Ensure all requests performed with Python fulfil the authentication requirements of your environment.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for the
id attribute for each resource. Identifier codes in these examples might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.
Note
These Python examples contain only basic exception and error handling logic. For more information on the exception handling specific to the SDK refer to the
pydoc for the ovirtsdk.infrastructure.errors module.
The ovirtsdk Python library provides the
API class, which acts as the entry point for the API.
Example 4.1. Accessing the API entry point using Python
This python example connects to an instance of the REST API provided by the Red Hat Enterprise Virtualization Manager at
rhevm.demo.redhat.com. To connect the example creates an instance of the API class If connection was successful a message is printed. Finally the disconnect() method of the API class is called to close the connection.
The parameters provided to the constructor for the
The constructor for the
API class in this example are:
- The
urlof the Manager to connect to. - The
usernameof the user to authenticate as. - The
passwordof the user to authenticate as. - The
ca_filewhich is the path to a certificate. The certificate is expected to be a copy of the one for the Manager's Certificate Authority. It can be obtained fromhttps://.HOST/ca.crt
API class supports other parameters. Only mandatory parameters are specified in this example.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") print "Connected to %s successfully!" % api.get_product_info().name api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the connection attempt was successful, the example outputs the text:
Connected to Red Hat Enterprise Virtualization Manager successfully!
The
API class provides access to a data centers collection, named datacenters. This collection contains all data centers in the environment.
Example 4.2. Listing the Data Center Collection using Python
This Python example lists the data centers in the
datacenters collection. It also outputs some basic information about each data center in the collection.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") dc_list = api.datacenters.list() for dc in dc_list: print "%s (%s)" % (dc.get_name(), dc.get_id()) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only the
Default data center exists, and it is not activated, the example outputs:
Default (d8b74b20-c6e1-11e1-87a3-00163e77e2ed)
The API class provides a clusters collection, named
clusters. This collection contains all clusters in the environment.
Example 4.3. Listing the clusters collection using Python
This Python example lists the clusters in the
clusters collection. It also outputs some basic information about each cluster in the collection.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") c_list = api.clusters.list() for c in c_list: print "%s (%s)" % (c.get_name(), c.get_id()) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only the
Default cluster exists, the example outputs:
Default (99408929-82cf-4dc7-a532-9d998063fa95)
The
API class provides access to a logical networks collection, named networks. This collection contains all logical networks in the environment.
Example 4.4. Listing the logical networks collection using Python
This Python example lists the logical networks in the
networks collection. It also outputs some basic information about each network in the collection.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") n_list = api.logicalnetworks.list() for n in n_list: print "%s (%s)" % (n.get_name(), n.get_id()) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only the default management network exists, the example outputs:
rhevm (00000000-0000-0000-0000-000000000009)
The
API class provides access to a hosts collection, named hosts. This collection contains all hosts in the environment.
Example 4.5. Listing the host collection using Python
This Python example lists the hosts in the
hosts collection.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="HOST", username="USER", password="PASS", ca_file="ca.crt") h_list = api.hosts.list() for h in h_list: print "%s (%s)" % (h.get_name(), h.get_id()) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
In an environment where only one host, named
Atlantic, has been attached the example outputs:
Atlantic (5b333c18-f224-11e1-9bdd-00163e77e2ed)
Red Hat Enterprise Virtualization Hypervisor hosts are added to the Red Hat Enterprise Virtualization Manager during their configuration. Once you have added a Hypervisor it requires approval in the Manager before it can actually be used in the environment.
Example 4.6. Approving a host using Python
This Python example calls the
approve method for a host named Atlantic.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="HOST", username="USER", password="PASS", ca_file="ca.crt") h = api.hosts.get(name="Atlantic") if(h.approve()): print "Host '%s' approved (Status: %s)." % (h.get_name(), h.get_status().get_state()) else: print "Approval of '%s' failed." % h.get_name() api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
approve request is successful then the script will output:
Host 'Atlantic' approved (Status: Up).
Note that the
status reflects that the host has been approved and is now considered to be up.
When a Red Hat Enterprise Virtualization environment is first being created it is necessary to define at least a data storage domain, and an ISO storage domain. The data storage domain will be used to store virtual machine disk images while the ISO storage domain will be used to store installation media for guest operating systems.
The
API class provides access to a storage domains collection, named storagedomains. This collection contains all the storage domains in the environment. The storagedomains collection can also be used to add and remove storage domains.
Note
The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Enterprise Virtualization. Refer to the Red Hat Enterprise Virtualization Administration Guide for more information on preparing NFS shares for use.
Example 4.7. Creating NFS data storage using Python
This Python example adds an NFS data domain to the
storagedomains collection. Adding an NFS storage domain in Python can be broken down into several steps:
- Identify the data center to which the storage must be attached, using the
getmethod of thedatacenterscollection.dc = api.datacenters.get(name="Default")
- Identify the host that must be used to attach the storage, using the
getmethod of thehostscollection.h = api.hosts.get(name="Atlantic")
- Define the
Storageparameters for the NFS storage domain. In this example the NFS location192.0.43.10/storage/datais being used.s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")
- Request creation of the storage domain, using the
addmethod of thestoragedomainscollection. In addition to theStorageparameters it is necessary to pass:- A name for the storage domain.
- The data center object that was retrieved from the
datacenterscollection. - The host object that was retrieved from the
hostscollection. - The type of storage domain being added (
data,iso, orexport). - The storage format to use (
v1,v2, orv3).
Once these steps are combined, the completed script is:
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt") dc = api.datacenters.get(name="Default") h = api.hosts.get(name="Atlantic") s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs") sd_params = params.StorageDomain(name="data1", data_center=dc, host=h, type_="data", storage_format="v3", storage=s) try: sd = api.storagedomains.add(sd_params) print "Storage Domain '%s' added (%s)." % (sd.get_name()) except Exception as ex: print "Adding storage domain failed: %s" % ex api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
add method call is successful then the script will output:
Storage Domain 'data1' added (bd954c03-d180-4d16-878c-2aedbdede566).
To create a virtual machine you must be able to provide installation media for the guest operating system. In a Red Hat Enterprise Virtualization Environment you store the installation media on an ISO storage domain.
Note
The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Enterprise Virtualization. Refer to the Red Hat Enterprise Virtualization Administration Guide for more information on preparing NFS shares for use.
Example 4.8. Creating NFS ISO storage using Python
This Python example adds an NFS ISO domain to the
storagedomains collection. Adding an NFS storage domain in Python can be broken down into several steps:
- Identify the data center to which the storage must be attached, using the
getmethod of thedatacenterscollection.dc = api.datacenters.get( name="Default" )
- Identify the host that must be used to attach the storage, using the
getmethod of thehostscollection.h = api.hosts.get(name="Atlantic")
- Define the
Storageparameters for the NFS storage domain. In this example the NFS location192.0.43.10/storage/isois being used.s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")
- Request creation of the storage domain, using the
addmethod of thestoragedomainscollection. In addition to theStorageparameters it is necessary to pass:- A name for the storage domain.
- The data center object that was retrieved from the
datacenterscollection. - The host object that was retrieved from the
hostscollection. - The type of storage domain being added (
data,iso, orexport). - The storage format to use (
v1,v2, orv3).
Once these steps are combined, the completed script is:
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt") dc = api.datacenters.get(name="Default") h = api.hosts.get(name="Atlantic") s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs") sd_params = params.StorageDomain(name="iso1", data_center=dc, host=h, type_="iso", storage_format="v3", storage=s) try: sd = api.storagedomains.add(sd_params) print "Storage Domain '%s' added (%s)." % (sd.get_name()) except Exception as ex: print "Adding storage domain failed: %s" % ex api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
add method call is successful then the script will output:
Storage Domain 'iso1' added (789814a7-7b90-4a39-a1fd-f6a98cc915d8).
Once you have added storage domains to Red Hat Enterprise Virtualization you must attach them to a data center and activate them before they will be ready for use.
Example 4.9. Attaching storage domains to a data center using Python
This Python example attaches a data storage domain named
data1, and an ISO storage domain named iso1 to the default data center. The attach action is facilitated by the add method of the data center's storagedomains collection.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt") dc = api.datacenters.get(name="Default") sd_data = api.storagedomains.get(name="data1") sd_iso = api.storagedomains.get(name="iso1") try: dc_sd = dc.storagedomains.add(sd_data) print "Attached data storage domain '%s' to data center '%s' (Status: %s)." % (dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state()) except Exception as ex: print "Attaching data storage domain to data center failed: %s." % ex try: dc_sd = dc.storagedomains.add(sd_iso) print "Attached ISO storage domain '%s' to data center '%s' (Status: %s)." % (dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state()) except Exception as ex: print "Attaching ISO storage domain to data center failed: %s." % ex api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the calls to the
add methods are successful then the script will output:
Attached data storage domain 'data1' to data center 'Default' (Status: maintenance). Attached ISO storage domain 'iso1' to data center 'Default' (Status: maintenance).
Note that the
status reflects that the storage domains still need to be activated.
Once you have added storage domains to Red Hat Enterprise Virtualization and attached them to a data center you must activate them before they will be ready for use.
Example 4.10. Activating storage domains using Python
This Python example activates a data storage domain named
data1, and an ISO storage domain named iso1. Both storage domains are attached to the Default data center. The activate action is facilitated by the activate method of the storage domain.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") dc = api.datacenters.get(name="Default") sd_data = dc.storagedomains.get(name="data1") sd_iso = dc.storagedomains.get(name="iso1") try: sd_data.activate() print "Activated data storage domain '%s' in data center '%s' (Status: %s)." % (sd_data.get_name(), dc.get_name, sd_data.get_status().get_state()) except Exception as ex: print "Activating data storage domain in data center failed: %s." % ex try: sd_iso.activate() print "Activated ISO storage domain '%s' in data center '%s' (Status: %s)." % (sd_iso.get_name(), dc.get_name, sd_iso.get_status().get_state()) except Exception as ex: print "Activating ISO storage domain in data center failed: %s." % ex api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
activate requests are successful then the script will output:
Activated data storage domain 'data1' in data center 'Default' (Status: active). Activated ISO storage domain 'iso1' in data center 'Default' (Status: active).
Note that the
status reflects that the storage domains have been activated.
Virtual machine creation is performed in several steps. The first step, covered here, is to create the virtual machine object itself.
Example 4.11. Creating a virtual machine using Python
This Python example creates a virtual machine named
These options are combined into a virtual machine parameter object, before using the
vm1. The virtual machine in this example:
- Must have 512 MB of memory, expressed in bytes.
vm_memory = 512 * 1024 * 1024
- Must be attached to the
Defaultcluster, and therefore theDefaultdata center.vm_cluster = api.clusters.get(name="Default")
- Must be based on the default
Blanktemplate.vm_template = api.templates.get(name="Blank")
- Must boot from the virtual hard disk drive.
vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])
add method of the vms collection to create the virtual machine itself.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") vm_name = "vm1" vm_memory = 512 * 1024 * 1024 vm_cluster = api.clusters.get(name="Default") vm_template = api.templates.get(name="Blank") vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")]) vm_params = params.VM(name=vm_name, memory=vm_memory, cluster=vm_cluster, template=vm_template) os=vm_os) try: api.vms.add(vm=vm_params) print "Virtual machine '%s' added." % vm_name except Exception as ex: print "Adding virtual machine '%s' failed: %s" % (vm_name, ex) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Virtual machine 'vm1' added.
To ensure a newly created virtual machine has network access you must create and attach a virtual NIC.
Example 4.12. Creating a virtual machine NIC using Python
This Python example creates an NIC named
These options are combined into an NIC parameter object, before using the
nic1 and attaches it to the virtual machine named vm1. The NIC in this example:
- Must be a
virtionetwork device.nic_interface = "virtio"
- Must be linked to the
rhevmmanagement network.nic_network = api.networks.get(name="rhevm")
add method of the virtual machine's nics collection to create the NIC.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="HOST", username="USER", password="PASS", ca_file="ca.crt") vm = api.vms.get(name="vm1") nic_name = "nic1" nic_interface = "virtio" nic_network = api.networks.get(name="rhevm") nic_params = params.NIC(name=nic_name, interface=nic_interface, network=nic_network) try: nic = vm.nics.add(nic_params) print "Network interface '%s' added to '%s'." % (nic.get_name(), vm.get_name()) except Exception as ex: print "Adding network interface to '%s' failed: %s" % (vm.get_name(), ex) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Network interface 'nic1' added to 'vm1'.
To ensure a newly created virtual machine has access to persistent storage you must create and attach a disk.
Example 4.13. Creating a virtual machine storage disk using Python
This Python example creates an 8 GB
These options are combined into a disk parameter object, before using the
virtio disk drive and attaches it to the virtual machine named vm1. The disk in this example:
- must be stored on the storage domain named
data1,disk_storage_domain = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")])
- must be 8 GB in size,
disk_size = 8*1024*1024
- must be a
systemtype disk (as opposed todata),disk_type = "system"
- must be
virtiostorage device,disk_interface = "virtio"
- must be stored in
cowformat, anddisk_format = "cow"
- must be marked as a usable boot device.
disk_bootable = True
add method of the virtual machine's disks collection to create the disk itself.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") vm = api.vms.get(name="vm1") sd = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")]) disk_size = 8*1024*1024 disk_type = "system" disk_interface = "virtio" disk_format = "cow" disk_bootable = True disk_params = params.Disk(storage_domains=sd, size=disk_size, type_=disk_type, interface=disk_interface, format=disk_format, bootable=disk_bootable) try: d = vm.disks.add(disk_params) print "Disk '%s' added to '%s'." % (d.get_name(), vm.get_name()) except Exception as ex: print "Adding disk to '%s' failed: %s" % (vm.get_name(), ex) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Disk 'vm1_Disk1' added to 'vm1'.
To begin installing a guest operating system on a newly created virtual machine you must attach an ISO file containing the operating system installation media.
Example 4.14. Identifying ISO images
ISO images are found in the
files collection attached to the ISO storage domain. This example lists the contents of the files collection on an ISO storage domain.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") sd = api.storagedomains.get(name="iso1") iso = sd.files.list() for i in iso: print "%s" % i.get_name() except Exception as ex: print "Unexpected error: %s"
If successful the script will output an entry like this for each file found in the
files collection:
RHEL6.3-Server-x86_64-DVD1.iso
Note that because files on the ISO domain must be uniquely named the
id and name attributes of the file are shared.
Example 4.15. Attaching an ISO image to a virtual machine using Python
This Python example attaches the
RHEL6.3-Server-x86_64-DVD1.iso ISO image file to the vm1 virtual machine. Once identified the image file is attached using the add method of the virtual machine's cdroms collection.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="HOST", username="USER", password="PASS") sd = api.storagedomains.get(name="iso1") cd_iso = sd.files.get(name="RHEL6.3-Server-x86_64-DVD1.iso") cd_vm = api.vms.get(name="vm1") cd_params = params.CdRom(vm=cd_vm, file=cd_iso) try: cd_vm.cdroms.add(cd_request) print "Attached CD to '%s'." % cd_vm.get_name() except Exception as ex: print "Failed to attach CD to '%s': %s" % (cd_vm.get_name(), ex) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Attached CD to 'vm1'.
Starting a virtual machine
Example 4.16. Starting a virtual machine using Python
This example starts the virtual machine using the
start method.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") vm = api.vms.get(name="vm1") try: vm.start() print "Started '%s'." % vm.get_name() except Exception ex: print "Unable to start '%s': %s" % (vm.get_name(), ex) api.disconnect() except Exception as ex: print "Unexpected error: %s" % ex
If the
start request is successful then the script will output:
Started 'vm1'.
Note that the
status reflects that the virtual machine has been started and is now up.
Red Hat Enterprise Virtualization Manager records and logs many system events. These event logs are accessible through the user interface, the system log files, and using the API. The ovirtsdk library exposes events using the
events collection.
Example 4.17. Checking System Events using Python
In this example the
events collection is listed. Note that:
- The
queryparameter of thelistmethod is used to ensure that all available pages of results are returned. By default thelistmethod will only return the first page of results which defaults to a maximum of100records in length. - The resultant list is reversed to ensure that events are included in the output in the order that they occurred.
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API (url="https://HOST", username="USER", password="PASS", ca_file="ca.crt") event_list = [] event_page_index = 1 event_page_current = api.events.list(query="page %s" % event_page_index) while(len(event_page_current) != 0): event_list = event_list + event_page_current event_page_index = event_page_index + 1 try: event_page_current = api.events.list(query="page %s" % event_page_index) except Exception as ex: print "Error retrieving page %s of list: %s" % (event_page_index, ex) event_list.reverse() for event in event_list: print "%s %s CODE %s - %s" % (event.get_time(), event.get_severity().upper(), event.get_code(), event.get_description()) except Exception as ex: print "Unexpected error: %s" % ex
Output from this script will look like this - albeit with different events depending on the state of the environment:
2012-09-25T18:40:10.065-04:00 NORMAL CODE 30 - User admin@internal logged in. 2012-09-25T18:40:10.368-04:00 NORMAL CODE 153 - VM vm1 was started by admin@internal (Host: Atlantic). 2012-09-25T18:40:10.470-04:00 NORMAL CODE 30 - User admin@internal logged in.
Table of Contents
- 5. Entry Point
- 6. Compatibility Level Versions
- 7. Capabilities
- 7.1. Version-Dependent Capabilities
- 7.2. Current Version
- 7.3. Features
- 7.4. CPUs
- 7.5. Power Managers
- 7.6. Fence Types
- 7.7. Storage Types
- 7.8. Storage Domain Types
- 7.9. Virtual Machine Types
- 7.10. Boot Devices
- 7.11. Display Types
- 7.12. NIC Interface Types
- 7.13. OS Types
- 7.14. Disk Formats
- 7.15. Disk Interfaces
- 7.16. Virtual Machine Affinities
- 7.17. Custom Properties
- 7.18. Boot Protocols
- 7.19. Error Handling
- 7.20. Storage Formats
- 7.21. Virtual Machine Device Types
- 7.22. Gluster Volume Types
- 7.23. Gluster Transport Types
- 7.24. Guster Acces Protocols
- 7.25. Resource Status States
- 7.26. Permits
- 7.27. Scheduling Policies
- 8. Common Features
- 9. Data Centers
- 10. Host Clusters
- 11. Networks
- 12. Storage Domains
- 13. Hosts
- 14. Virtual Machines
- 15. Floating Disks
- 16. Templates
- 17. Virtual Machine Pools
- 18. Domains
- 19. Roles
- 20. Groups
- 21. Users
- 22. Tags
- 23. Events
A user begins interacting with the API through a
GET request on the entry point URI consisting of a host and base.
Example 5.1. Accessing the API Entry Point
If the host is
www.example.com and the base is /api, the entry point appears with the following request:
GET /api HTTP/1.1
Accept: application/xml
Host: www.example.com
Authorization: [base64 encoded credentials]
HTTP/1.1 200 OK
Content-Type: application/xml
<api>
<link rel="hosts" href="/api/hosts"/>
<link rel="vms" href="/api/vms"/>
...
<product_info>
<name>Red Hat Enterprise Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="1" major="3"/>
</product_info>
<special_objects>
<link rel="templates/blank" href="..."/>
<link rel="tags/root" href="..."/>
</special_objects>
<summary>
<vms>
<total>10</total>
<active>3</active>
</vms>
<hosts>
<total>2</total>
<active>2</active>
</hosts>
<users>
<total>8</total>
<active>2</active>
</users>
<storage_domains>
<total>2</total>
<active>2</active>
</storage_domains>
</summary>
</api>
Note
For simplicity, all other examples omit the
Host: and Authorization: request headers and assume the base is the default /api path. This base path differs depending on your implementation.
The entry point contains a
product_info element to help an API user determine the legitimacy of the Red Hat Enterprise Virtualization environment. This includes the name of the product, the vendor and the version.
Example 5.2. Verify a genuine Red Hat Enterprise Virtualization environment
The follow elements identify a genuine Red Hat Enterprise Virtualization 3.1 environment:
<api>
...
<product_info>
<name>Red Hat Enterprise Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="1" major="3"/>
</product_info>
...
</api>
Access to the Entry Point provides
link elements and URIs for all of the resource collections the API exposes. Each collection uses a relation type to identify the URI a client needs.
Table 5.1. Available Relationship Types
| Relationship | Description |
|---|---|
capabilities
| Supported capabilities of the Red Hat Enterprise Virtualization Manager. |
datacenters
| Data centers. |
clusters
| Host clusters. |
networks
| Virtual networks. |
storagedomains
| Storage domains. |
hosts
| Hosts. |
vms
| Virtual machines. |
disks
| Virtual machine disks. |
templates
| Templates. |
vmpools
| Virtual machine pools. |
domains
| Identity service domains. |
groups
| Imported identity service groups. |
roles
| Roles. |
users
| Users. |
tags
| Tags. |
events
| Events. |
Figure 5.1. The relationship between the API entry point and the resource collections exposed by the API
Note
All URIs shown in example responses are illustrative. The format of all URIs returned by the server is opaque. Clients navigate to specific resources through the entry point URI and use the relationship types to access the URIs.
The server chooses to include absolute URIs or absolute paths [3] in the
link element's href attribute, so clients are required to handle either form.
The
link elements also contain a set of search URIs for certain collections. These URIs use URI templates [4] to integrate search queries. The purpose of the URI template is to accept a search expression using the natural HTTP pattern of a query parameter. The client does not require prior knowledge of the URI structure. Thus clients should treat these templates as being opaque and access them with a URI template library.
Each search query URI template is identified with a relation type using the convention
"collection/search".
Table 5.2. Relationships associated with search query URIs
| Relationship | Description |
|---|---|
datacenters/search
| Query data centers. |
clusters/search
| Query host clusters. |
storagedomains/search
| Query storage domains. |
hosts/search
| Query hosts. |
vms/search
| Query virtual machines. |
disks/search
| Query disks. |
templates/search
| Query templates. |
vmpools/search
| Query virtual machine pools. |
events/search
| Query events. |
users/search
| Query users. |
Special object elements define relationships to special fixed resources within the virtualization environment.
Table 5.3. Special Objects
| Relationship | Description |
|---|---|
templates/blank
|
The default blank virtual machine template for your virtualization environment. This template exists in every cluster as opposed to a standard template, which only exists in a single cluster.
|
tags/root
|
The root tag that acts as a base for tag hierarchy in your virtualization environment.
|
The summary element shows a high level summary of the system's statistics.
Table 5.4. Summary Elements
| Element | Description |
|---|---|
vms
| Total number of vms and total number of active vms. |
hosts
| Total number of hosts and total number of active hosts. |
users
| Total number of users and total number of active users. |
storage_domains
| Total number of storage domains and total number of active storage domains. |
RESTful Service Description Language (RSDL) provides a description of the structure and elements in the the REST API in one whole XML specification. Invoke the RSDL using the following request.
GET /api?rsdl HTTP/1.1 Accept: application/xml
This produces an XML document in the following format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
<description>...</description>
<version major="3" minor="1" build="0" revision="0"/>
<schema href="/api?schema" rel="schema">
<name>...</name>
<description>...</description>
</schema>
<links>
<link href="/api/capabilities" rel="get">
...
</link>
...
</links>
</rsdl>
Table 5.5. RSDL Structure Elements
| Element | Description |
|---|---|
description
| A plain text description of the RSDL document. |
version
|
The API version, including major release, minor release, build and revision.
|
schema
| A link to the XML schema (XSD) file. |
links
|
Defines each link in the API.
|
Each
link element contains the following a structure:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
...
<links>
<link href="/api/..." rel="...">
<request>
<http_method>...</http_method>
<headers>
<header>
<name>...</name>
<value>...</value>
</header>
...
</headers>
<body>
<type>...</type>
<parameters_set>
<parameter required="..." type="...">
<name>...</name>
</parameter>
...
</parameters_set>
</body>
</request>
<response>
<type>...</type>
</response>
</link>
...
</links>
</rsdl>
Table 5.6. RSDL Link Structure Elements
| Element | Description |
|---|---|
link
|
A URI for API requests. Includes a URI attribute (href) and a relationship type attribute (rel).
|
request
| Defines the request properties required for the link. |
http_method
|
The method type to access this link. Includes the standard HTTP methods for REST API access: GET, POST, PUT and DELETE.
|
headers
|
Defines the headers for the HTTP request. Contains a series of header elements, which each contain a header name and value to define the header.
|
body
|
Defines the body for the HTTP request. Contains a resource type and a parameter_set, which contains a sets of parameter elements with attributes to define whether they are required for a request and the data type. The parameter element also includes a name element to define the Red Hat Enterprise Virtualization Manager property to modify and also a further parameter_set subset if type is set to collection.
|
response
|
Defines the output for the HTTP request. Contains a type element to define the resource structure to output.
|
Use the RSDL in your applications as a method to map all links and parameter requirements for controlling a Red Hat Enterprise Virtualization environment.
[3]
The RFC describing Uniform Resource Locator Generic Syntax provides a Collected ABNF for URI that explains the difference between these forms.
[4]
The Internet-Draft describing the format of a URI Template is available at http://tools.ietf.org/html/draft-gregorio-uritemplate-03.
Each host connected to Red Hat Enterprise Virtualization Manager contains a version of VDSM. VDSM is the agent within the virtualization infrastructure that runs on a hypervisor or host and provides local management for virtual machines, networks and storage. Red Hat Enterprise Virtualization Manager controls hypervisors and hosts using current or older versions of VDSM.
The Manager migrates virtual machines from host to host within a cluster. This means the Manager excludes certain features from a current version of VDSM until all hosts within a cluster have the same VDSM version, or more recent, installed.
The API represents this concept as a
compatibility level for each host, corresponding to the version of VDSM installed. A version element contains major and minor attributes, which describe the compatibility level.
When an administrator upgrades all hosts within a cluster to a certain level, the
version level appears under a supported_versions element. This indicates the cluster's version is now updatable to that level. Once the administrator updates all clusters within a data center to a given level, the data center is updatable to that level.
Example 6.1. Upgrading compatibility levels
The API reports the following compatibility levels for Red Hat Enterprise Virtualization Manager 3.0 instance:
<host ...>
...
<version major="3" minor="0"/>
...
</host>
<cluster ...>
...
<version major="3" minor="0"/>
<supported_versions/>
...
</cluster>
<data_center ...>
...
<version major="3" minor="0"/>
<supported_versions/>
...
</data_center>
All hosts within a cluster are updated to VDSM
3.1 and the API reports:
<host ...>
...
<version major="3" minor="1"/>
...
</host>
<cluster ...>
...
<version major="3" minor="0"/>
<supported_versions>
<version major="3" minor="1"/>
</supported_versions>
...
</cluster>
<data_center ...>
...
<version major="3" minor="0"/>
<supported_versions/>
...
</data_center>
The cluster is now updatable to
3.1. When the cluster is updated, the API reports:
<cluster ...>
...
<version major="3" minor="1"/>
<supported_versions/>
...
</cluster>
<data_center ...>
...
<version major="3" minor="0"/>
<supported_versions>
<version major="3" minor="1"/>
</supported_versions>
...
</data_center>
The API user updates the data center to
3.1. Once upgraded, the API exposes features available in Red Hat Enterprise Virtualization 3.1 for this data center.
- 7.1. Version-Dependent Capabilities
- 7.2. Current Version
- 7.3. Features
- 7.4. CPUs
- 7.5. Power Managers
- 7.6. Fence Types
- 7.7. Storage Types
- 7.8. Storage Domain Types
- 7.9. Virtual Machine Types
- 7.10. Boot Devices
- 7.11. Display Types
- 7.12. NIC Interface Types
- 7.13. OS Types
- 7.14. Disk Formats
- 7.15. Disk Interfaces
- 7.16. Virtual Machine Affinities
- 7.17. Custom Properties
- 7.18. Boot Protocols
- 7.19. Error Handling
- 7.20. Storage Formats
- 7.21. Virtual Machine Device Types
- 7.22. Gluster Volume Types
- 7.23. Gluster Transport Types
- 7.24. Guster Acces Protocols
- 7.25. Resource Status States
- 7.26. Permits
- 7.27. Scheduling Policies
The
capabilities collection provides information about the supported capabilities of a Red Hat Enterprise Virtualization Manager version. These capabilities include active features and available enumerated values for specific properties. An API user accesses this information through the rel="capabilities" link obtained from the entry point URI (see Chapter 5, Entry Point).
The
capabilities element contains any number of version elements that describe capabilities dependent on a compatibility level.
The
version element includes attributes for major and minor version numbers. This indicates the current version level, which this document discusses in Chapter 6, Compatibility Level Versions.
The following representation shows capabilities specific to Red Hat Enterprise Virtualization Manager
3.1 and 3.0 respectively:
<capabilities>
<version major="3" minor="1">
...
</version>
<version major="3" minor="0">
...
</version>
...
</capabilities>
Each
version contains a series of capabilities dependent on the version specified.
The
current element signifies if the version specified is the most recent supported compatibility level. The value is either a Boolean true or false.
<capabilities>
<version major="3" minor="1">
...
<current>true</current>
...
</version>
</capabilities>
Each
version contains a list of compatible features.
Table 7.1. Feature Types
| Feature Element | Type | Description |
|---|---|---|
transparent_hugepages
| Boolean: true or false | Defines the availability of Transparent Hugepages for hosts. |
<capabilities>
<version major="3" minor="1">
...
<features>
<transparent_hugepages>true</transparent_hugepages>
</features>
...
</version>
</capabilities>
Each cluster is configured with a minimal CPU type that all hosts in that cluster must support. Guests running on hosts within the cluster all run on this CPU type, ensuring that every guest is migratable to any host within the cluster.
Red Hat Enterprise Virtualization has a set of supported CPU types to choose from when configuring a cluster.
Table 7.2. CPU properties
| Element | Description |
|---|---|
id
| An opaque identifier for the CPU model. |
level
| An indication as to the relative priority/preference for the CPUs in the list. |
<capabilities>
<version major="3" minor="1">
...
<cpus>
<cpu id="Intel Conroe Family">
<level>3</level>
</cpu>
<cpu id="Intel Penryn Family">
<level>4</level>
</cpu>
...
</cpus>
...
</version>
</capabilities>
Red Hat Enterprise Virtualization platform provides a list of supported
power_managers for host fencing configuration. Each power_management option contains a set of properties.
Table 7.3. Power Management Properties
| Element | Description |
|---|---|
type
| The supported fencing device type. |
options
|
A list of options available to the supported fencing device. Options include a name and a value type.
|
<capabilities>
<version major="3" minor="1">
...
<power_managers>
<power_management type="alom">
<options>
<option type="bool" name="secure"/>
<option type="int" name="port"/>
</options>
</power_management>
<power_management type="apc">
<options>
<option type="bool" name="secure"/>
<option type="int" name="port"/>
<option type="int" name="slot"/>
</options>
</power_management>
<power_management type="bladecenter">
<options>
<option type="bool" name="secure"/>
<option type="int" name="port"/>
<option type="int" name="slot"/>
</options>
</power_management>
...
</power_managers>
...
</version>
</capabilities>
The
fence_types element defines fence_type options to fence a host and reduce power usage.
<capabilities>
<version major="3" minor="1">
...
<fence_types>
<fence_type>manual</fence_type>
<fence_type>restart</fence_type>
<fence_type>start</fence_type>
<fence_type>stop</fence_type>
<fence_type>status</fence_type>
</fence_types>
...
</version>
</capabilities>
The
storage_types element defines the available physical storage_type options.
<capabilities>
<version major="3" minor="1">
...
<storage_types>
<storage_type>iscsi</storage_type>
<storage_type>fcp</storage_type>
<storage_type>nfs</storage_type>
<storage_type>localfs</storage_type>
<storage_type>posixfs</storage_type>
</storage_types>
...
</version>
</capabilities>
The
storage_domain_types element shows the available storage_domain_type options in a virtualization environment.
<capabilities>
<version major="3" minor="1">
...
<storage_domain_types>
<storage_domain_type>data</storage_domain_type>
<storage_domain_type>iso</storage_domain_type>
<storage_domain_type>export</storage_domain_type>
</storage_domain_types>
...
</version>
</capabilities>
The
vm_types element defines each virtual machine type (vm_type) available for creation in a virtual environment.
<capabilities>
<version major="3" minor="1">
...
<vm_types>
<vm_type>desktop</vm_type>
<vm_type>server</vm_type>
</vm_types>
...
</version>
</capabilities>
Each virtual machine boots from a selected device. The
boot_devices element lists such boot_device options.
<capabilities>
<version major="3" minor="1">
...
<boot_devices>
<boot_device>cdrom</boot_device>
<boot_device>hd</boot_device>
<boot_device>network</boot_device>
</boot_devices>
...
</version>
</capabilities>
Access to a virtual machine through Red Hat Enterprise Virtualization Manager requires a display protocol. The
display_types element lists each display_type protocol.
<capabilities>
<version major="3" minor="1">
...
<display_types>
<display_type>vnc</display_type>
<display_type>spice</display_type>
</display_types>
...
</version>
</capabilities>
A virtual machine requires a network interface to connect to a network. The
nic_interfaces element defines the supported NIC types available. Each nic_interface depends on the drivers available for different types of virtual machines. VirtIO drivers are available for Red Hat Enterprise Linux 4.8 and above, and for Windows virtual machines. Windows supports rtl8139 without the need for drivers. Other Linux machines, or earlier versions of Red Hat Enterprise Linux, use e1000 or rtl8139.
<capabilities>
<version major="3" minor="1">
...
<nic_interfaces>
<nic_interface>e1000</nic_interface>
<nic_interface>virtio</nic_interface>
<nic_interface>rtl8139</nic_interface>
<nic_interface>rtl8139_virtio</nic_interface>
</nic_interfaces>
...
</version>
</capabilities>
Each virtual machine contains an
os_type value to define the virtual machine operating system. The default is unassigned.
<capabilities>
<version major="3" minor="1">
...
<os_types>
<os_type>unassigned</os_type>
<os_type>windows_xp</os_type>
<os_type>windows_2003</os_type>
<os_type>windows_2008</os_type>
<os_type>other_linux</os_type>
<os_type>other</os_type>
<os_type>rhel_5</os_type>
<os_type>rhel_4</os_type>
<os_type>rhel_3</os_type>
<os_type>windows_2003x64</os_type>
<os_type>windows_7</os_type>
<os_type>windows_7x64</os_type>
<os_type>rhel_5x64</os_type>
<os_type>rhel_4x64</os_type>
<os_type>rhel_3x64</os_type>
<os_type>windows_2008x64</os_type>
<os_type>windows_2008r2x64</os_type>
<os_type>rhel_6</os_type>
<os_type>rhel_6x64</os_type>
<os_types>
...
</version>
</capabilities>
An API user selects the format for virtual disks. The
disk_formats element defines the format types. The disk_format types include pre-allocated (raw) or thin-provisioned (Copy-On-Write or cow).
<capabilities>
<version major="3" minor="1">
...
<disk_formats>
<disk_format>cow</disk_format>
<disk_format>raw</disk_format>
</disk_formats>
...
</version>
</capabilities>
The
disk_interfaces element lists disk_interface options for emulated protocols to interface with virtual disks.
<capabilities>
<version major="3" minor="1">
...
<disk_interfaces>
<disk_interface>ide</disk_interface>
<disk_interface>virtio</disk_interface>
</disk_interfaces>
...
</version>
</capabilities>
Virtual machines migrate between hosts in a cluster. The
vm_affinities element defines each available migration affinity for virtual machines.
<capabilities>
<version major="3" minor="1">
...
<vm_affinities>
<affinity>migratable</affinity>
<affinity>user_migratable</affinity>
<affinity>pinned</affinity>
</vm_affinities>
...
</version>
</capabilities>
The
custom_properties element lists a set of environment variables for a virtual environment. The virtual environment uses these variables as parameters for event-triggered VDSM scripts. Each custom_property includes attributes for a property name and a regular expression (regexp) to define the format of the property value.
<capabilities>
<version major="3" minor="1">
...
<custom_properties>
<custom_property name="sap_agent" regexp="^(true|false)$"/>
<custom_property name="sndbuf" regexp="^[0-9]+$"/>
<custom_property name="vhost"
regexp="^(([a-zA-Z0-9_]*):(true|false))
(,(([a-zA-Z0-9_]*):(true|false)))*$"/>
<custom_property name="viodiskcache"
regexp="^(none|writeback|writethrough)$"/>
</custom_properties>
...
</version>
</capabilities>
The
boot_protocol element lists each possible IP assignment boot_protocol for hosts when booting.
<capabilities>
<version major="3" minor="1">
...
<boot_protocols>
<boot_protocol>dhcp</boot_protocol>
<boot_protocol>static</boot_protocol>
<boot_protocol>none</boot_protocol>
</boot_protocols>
...
</version>
</capabilities>
A Red Hat Enterprise Virtualization Manager determines whether to migrate virtual machines on a non-operational host using one of the
on_error options the in the error_handling element.
<capabilities>
<version major="3" minor="1">
...
<error_handling>
<on_error>migrate</on_error>
<on_error>do_not_migrate</on_error>
<on_error>migrate_highly_available</on_error>
</error_handling>
...
</version>
</capabilities>
The
storage_formats element lists the available format versions for storage meta-data.
<capabilities>
<version major="3" minor="1">
...
<storage_formats>
<format>v1</format>
<format>v2</format>
<format>v3</format>
</storage_formats>
...
</version>
</capabilities>
The
vm_device_types element lists the available devices on the virtual machine.
<capabilities>
<version major="3" minor="1">
...
<vm_device_types>
<vm_device_types>floppy</vm_device_types>
<vm_device_types>cdrom</vm_device_types>
</vm_device_types>
...
</version>
</capabilities>
The
gluster_volume_types element lists the available type of Gluster volumes.
<capabilities>
<version major="3" minor="1">
...
<gluster_volume_types>
<gluster_volume_type>DISTRIBUTE</gluster_volume_types>
<gluster_volume_types>REPLICATE</gluster_volume_types>
...
</gluster_volume_types>
...
</version>
</capabilities>
The
transport_types element lists the available transport types for Gluster volumes.
<capabilities>
<version major="3" minor="1">
...
<transport_types>
<transport_type>TCP</transport_type>
<transport_type>RDMA</transport_type>
</transport_types>
...
</version>
</capabilities>
The
access_protocols element lists the available access protocols for Gluster volumes.
<capabilities>
<version major="3" minor="1">
...
<access_protocols>
<access_protocol>GLUSTER</access_protocol>
<access_protocol>NFS</access_protocol>
<access_protocol>CIFS</access_protocol>
</access_protocols>
...
</version>
</capabilities>
Each
version contains a set of states for resource statuses. These resource status elements include creation_states, power_management_states, host_states, host_non_operational_details, network_states, storage_domain_states, template_states, vm_states, vm_pause_details, disk_states, host_nic_states, data_center_states, gluster_volume_states and brick_states.
Permits are allowable actions a user assigns to a role. Each
permit contains a set of properties.
Table 7.4. Permit properties
| Element | Type | Description |
|---|---|---|
id=
| integer | The opaque identifier for a permit. |
name
| string | The name of the permit. |
administrative
| Boolean: true or false | The permit is assigned to only administrative roles. |
<capabilities>
...
<permits>
<permit id="1">
<name>create_vm</name>
<administrative>false</administrative>
</permit>
<permit id="2">
<name>delete_vm</name>
<administrative>false</administrative>
</permit>
...
</permits>
...
</capabilities>
This chapter examines features common to resources and collections.
Note
Throughout this guide, the elements of each resource are detailed in tables. These tables include a properties column, displaying icons depicting element properties. The meaning of these icons is shown in Table 8.1, “Element property icons”.
Table 8.1. Element property icons
| Property | Description | Icon |
|---|---|---|
| Required for creation | These elements must be included in the client-provided representation of a resource on creation, but are not mandatory for an update of a resource. |
|
| Non-updateable | These elements cannot have their value changed when updating a resource. Include these elements in a client-provided representation on update only if their values are not altered by the API user. If altered, the API reports an error. |
|
| Read-only | These elements are read-only. Values for read-only elements are not created or modified. |
|
The API structures resource representations in the following XML document structure:
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
In the context of a virtual machine, the representation appears as follows:
<vm id="5b9bbce5-0d72-4f56-b931-5d449181ee06"
href="/api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
<name>RHEL6-Machine</name>
<description>Red Hat Enterprise Linux 6 Virtual Machine</description>
...
</vm>
All resource representations contain a set of common attributes
Table 8.2. Common attributes to resource representations
| Attribute | Type | Description | Properties |
|---|---|---|---|
id
| GUID |
Each resource in the virtualization infrastructure contains an id, which acts as a globally unique identifier (GUID). The GUID is the primary method of resource identification.
|
|
href
| string | The canonical location of the resource as an absolute path. |
|
All resource representations contain a set of common elements.
Table 8.3. Common elements to resource representations
| Element | Type | Description | Properties |
|---|---|---|---|
name
| string |
A user-supplied human readable name for the resource. The name is unique across all resources of its type.
|
|
description
| string | A free-form user-supplied human readable description of the resource. |
This section examines common features for collections.
A listing of the resources in a collection is obtained by issuing a
GET request on the collection URI obtained from the entry point.
GET /api/collection HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<collection>
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
...
</collection>
Use an optional
max URL parameter to limit the list of results.
GET /api/collection;max=1 HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<collection>
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
</collection>
The API extends collection representations to include sub-collections when the
Accept header includes the detail parameter.
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection
This includes multiple sub-collection requests using either separated
detail parameters:
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1; detail=subcollection2
Or one
detail parameter that separates the sub-collection with the + operator:
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
The API supports extended sub-collections for the following main collections.
Table 8.4. Collections that use extended sub-collections
| Collection | Extended Sub-Collection Support |
|---|---|
hosts
|
statistics
|
vms
|
statistics, nics, disks
|
Example 8.1. A request for extended statistics, nics and disks sub-collections in the vms collection
GET /api/vms HTTP/1.1 Accept: application/xml; detail=statistics+nics+disks
A
GET request on a "collection/search" link results in a search query of that collection. The API only returns resources within the collection that satisfy the search query constraints.
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<collection>
<resource id="resource_id" href="/api/collection/resource_id">
...
</resource>
...
</collection>
The API uses the URI templates to perform a search
query with a GET request:
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
The
query template value refers to the search query the API directs to the collection. This query uses the same format as Red Hat Enterprise Virtualization Query Language:
(criteria) [sortby (element) asc|desc]
The
sortby clause is optional and only needed when ordering results.
Table 8.5. Example search queries
| Collection | Criteria | Result |
|---|---|---|
hosts
|
vms.status=up
|
Displays a list of all hosts running virtual machines that are up.
|
vms
|
domain=qa.company.com
| Displays a list of all virtual machines running on the specified domain. |
vms
|
users.name=mary
|
Displays a list of all virtual machines belonging to users with the username mary.
|
events
|
severity>normal sortby time
|
Displays the list of all events with severity higher than normal and sorted by the time element values.
|
events
|
severity>normal sortby time desc
|
Displays the list of all events with severity higher than normal and sorted by the time element values in descending order.
|
The API requires the
query template to be URL-encoded to translate reserved characters, such as operators and spaces.
Example 8.2. URL-encoded search query
GET /api/vms?search=name%3Dvm1 HTTP/1.1 Accept: application/xml
Important
Some queries for enumerated values require translation to values used in Red Hat Enterprise Virtualization Query Language. For more information, see Appendix C, Enumerated Value Translation.
All search queries are case sensitive by default. The URL syntax provides a Boolean option to toggle case sensitivity.
Example 8.3. Case insensitive search query
GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml
Search queries substitute part of a value with an asterisk as a wildcard.
Example 8.4. Wildcard search query for name=vm*
GET /api/vms?search=name%3Dvm* HTTP/1.1 Accept: application/xml
This query would result in all virtual machines with names beginning with
vm, such as vm1, vm2, vma or vm-webserver.
Example 8.5. Wildcard search query for name=v*1
GET /api/vms?search=name%3Dv*1 HTTP/1.1 Accept: application/xml
This query would result in all virtual machines with names beginning with
v and ending with 1, such as vm1, vr1 or virtualmachine1.
Some Red Hat Enterprise Virtualization environments contain large collections of resources. However, the API only displays a default number of resources for one search query to a collection. To display more than the default, the API separates collections into pages via a search query containing the
page command.
Example 8.6. Paginating resources
This example paginates resources in a collection. The URL-encoded request is:
GET /api/collection?search=page%201 HTTP/1.1 Accept: application/xml
Increase the
page value to view the next page of results.
GET /api/collection?search=page%202 HTTP/1.1 Accept: application/xml
Use the
page command also in conjunction with other commands in a search query. For example:
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1 Accept: application/xml
This query displays the second page in a collection listing ordered by a chosen element.
The API creates a new resource with a
POST request to the collection URI containing a representation of the new resource.
A
POST request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request.
Each resource type has its own specific required properties. The client supplies these properties as XML elements when creating a new resource. Refer to the individual resource type documentation for more details. If a required property is absent, the creation fails with a
fault representation indicating the missing elements.
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<name>Resource-Name</name>
</resource>
HTTP/1.1 201 Created
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
...
</resource>
The
Location header in the response gives the URI of the queried resource. The response body contains either a complete representation, partial representation or no representation of the resource. It is recommended that clients rely only on fetching the representation via the URI in the response header.
The API performs asynchronous
POST requests unless the user overrides them with an Expect: 201-created header.
For example, certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resource results in a
202 Accepted status. The initial document structure for a 202 Accepted resource also contains a creation_status element and link for creation status updates. For example:
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<name>Resource-Name</name>
</resource>
HTTP/1.1 202 Accepted
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<creation_status>
<state>pending</state>
</creation status>
<link rel="creation_status"
href="/api/collection/resource_id/creation_status/creation_status_id"/>
...
</resource>
A
GET request to the creation_status link provides a creation status update:
GET /api/collection/resource_id/creation_status/creation_status_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<creation id="creation_status_id"
href="/api/collection/resource_id/creation_status/creation_status_id">
<status>
<state>complete</state>
</status>
</creation>
Overriding the asynchronous resource creation requires an
Expect: 201-created header:
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created
<resource>
<name>Resource-Name</name>
</resource>
This section examines common features for resources.
The API retrieves the state of a resource with a
GET request on a URI obtained from a collection listing.
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
...
</resource>
The API modifies resource properties with a
PUT request containing an updated description from a previous GET request for the resource URI. Details on modifiable properties are found in the individual resource type documentation.
A
PUT request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request.
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<name>New-Resource-Name</name>
</resource>
HTTP/1.1 200 OK
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
<name>New-Resource-Name</name>
...
</resource>
This does not include immutable resource properties that an API user has attempted to modify. If an attempt is made to modify a strictly immutable resource property, the API reports a
409 Conflict error with a fault representation in the response body.
Properties omitted from the representation are ignored and not changed.
Asynchronous Requests
PUT requests also feature the ability to asynchronously update resources. This means a client can send an update request without waiting for the request to complete. Perform an asynchronous update request with the async URL parameter and an Expect: 202-Accepted header.
PUT /api/collection/resource_id;async HTTP/1.1 Accept: application/xml Expect: 202-Accepted
The API deletes a resource with a
DELETE request sent to its URI.
DELETE /api/collection/resource_id HTTP/1.1 Accept: application/xml HTTP/1.1 204 No Content
Some cases require optional body content in the
DELETE request to specify additional properties. A DELETE request with optional body content requires a Content-Type: application/xml header to inform the API of the XML representation in the body content. If a DELETE request contains no body content, omit the Content-Type: application/xml header.
Asynchronous Requests
DELETE requests also feature the ability to asynchronously delete resources. This means a client can send a delete request without waiting for the request to complete. Perform an asynchronous delete request with the async URL parameter and an Expect: 202-Accepted header.
DELETE /api/collection/resource_id;async HTTP/1.1 Accept: application/xml Expect: 202-Accepted
A sub-collection relationship defines a hierarchical link between a resource and a sub-collection. The sub-collection exists or has some meaning in the context of a parent resource. For example, a virtual machine contains network interfaces, which means the API maps the relationship between the virtual machine resource and the network interfaces sub-collection.
Sub-collections are used to model the following relationships types:
- N:M mappings, where one parent resource can contain several child resources and vice versa. For example, a virtual machine can contain several disks and some disks are shared among multiple virtual machines.
- 1:N mappings, where mapped resources are dependent on a parent resource. Without the parent resource, the dependent resource cannot exist. For example, the link between a virtual machine and snapshots.
- 1:N mappings, where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a cluster and a network.
The API defines a relationship between a resource and a sub-collection using the
link rel= attribute:
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
...
<link rel="subcollection"
href="/api/collection/resource_id/subcollection"/>
...
</resource>
The API user now queries the sub-collection.
GET /api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<subcollection>
<subresource id="subresource_id"
href="/api/collection/resource_id/subcollection/subresource_id">
...
</subresource>
...
</subcollection>
XML element links act as an alternative to sub-collections to express relationships between resources. XML element links are simply elements with a "href" attribute that points to the linked element.
XML element links are used to model simple 1:N mappings between resources without a dependency and without data associated with the relationship. For example, the relationship between a host and a cluster.
Examples of such relationships include:
- Backlinks from a resource in a sub-collection to a parent resource; or
- Links between resources with an arbitrary relationship.
Example 8.7. Backlinking from a sub-collection resource to a resource using an XML element
GET /api/collection/resource_id/subcollection/subresource_id HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/xml
<subcollection>
<subresource id="subresource_id"
href="/api/collection/resource_id/subcollection/subresource_id">
<resource id="resource_id" href="/api/collection/resource_id"/>
...
</subresource>
</subcollection>
Most resources include a list of action links to provide functions not achieved through the standard HTTP methods.
<resource>
...
<actions>
<link rel="start" href="/api/collection/resource_id/start"/>
<link rel="stop" href="/api/collection/resource_id/stop"/>
...
</actions>
...
</resource>
The API invokes an action with a
POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and task-specific parameters.
Table 8.6. Common action parameters
| Element | Description |
|---|---|
async
|
true if the server responds immediately with 202 Accepted and an action representation contains a href link to be polled for completion.
|
grace_period
| a grace period in milliseconds, which must expire before the action is initiated. |
Individual actions and their parameters are documented in the individual resource type's documentation. Some parameters are mandatory for specific actions and their absence is indicated with a
fault response.
An action also requires a
Content-Type: application/xml header since the POST request requires an XML representation in the body content.
When the action is initiated asynchronously, the immediate
202 Accepted response provides a link to monitor the status of the task:
POST /api/collection/resource_id/action HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<action>
<async>true</async>
</action>
HTTP/1.1 202 Accepted
Content-Type: application/xml
<action id="action_id"
href="/api/collection/resource_id/action/action_id">
<async>true</async>
...
<action>
A subsequent
GET on the action URI provides an indication of the status of the asynchronous task.
Table 8.7. Action statuses
| Status | Description |
|---|---|
pending
| Task has not yet started. |
in_progress
| Task is in operation. |
complete
| Task completed successfully. |
failed
|
Task failed. The returned action representation would contain a fault describing the failure.
|
Once the task has completed, the action is retained for an indeterminate period. Once this has expired, subsequent
GETs are 301 Moved Permanently redirected back to the target resource.
GET /api/collection/resource_id/action/action_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<action id="action_id"
href="/api/collection/resource_id/action/action_id">
<status>
<state>pending</state>
</status>
<link rel="parent" /api/collection/resource_id"/>
<link rel="replay" href="/api/collection/resource_id/action"/>
<action>
An action representation also includes some links that are identified by the
rel attribute:
Table 8.8. Action relationships
| Type | Description |
|---|---|
parent
| A link back to the resource of this action. |
replay
| A link back to the original action URI. POSTing to this URI causes the action to be re-initiated. |
Each resource contains a
permissions sub-collection. Each permission contains a user, an assigned role and the specified resource. For example:
GET /api/collection/resource_id/permissions HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<permissions>
<permission id="permission-id"
href="/api/collection/resource_id/permissions/permission_id">
<role id="role_id" href="/api/roles/role_id"/>
<user id="user_id" href="/api/users/user_id"/>
<resource id="resource_id" href="/api/collection/resource_id"/>
</permission>
...
</permissions>
A resource acquires a new permission when an API user sends a
POST request with a permission representation and a Content-Type: application/xml header to the resource's permissions sub-collection. Each new permission requires a role and a user:
POST /api/collection/resource_id/permissions HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<permission>
<role id="role_id"/>
<user id="user_id"/>
</permission>
HTTP/1.1 201 Created
Content-Type: application/xml
<permission id="permission_id"
href="/api/resources/resource_id/permissions/permission_id">
<role id="role_id" href="/api/roles/role_id"/>
<user id="user_id" href="/api/users/user_id"/>
<resource id="resource_id" href="/api/collection/resource_id"/>
</permission>
Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful resource state update or action with a
fault representation in the response entity body. The fault contains a reason and detail strings. Clients must accommodate failed requests via extracting the fault or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation.
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<id>id-update-test</id>
</resource>
HTTP/1.1 409 Conflict
Content-Type: application/xml
<fault>
<reason>Broken immutability constraint</reason>
<detail>Attempt to set immutable field: id</detail>
</fault>
The
datacenters collection provides information about the data centers in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="datacenters" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a data center resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 9.1. Data center elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="storagedomains"
| relationship | A link to the sub-collection for storage domains attached to this data center. | |
link rel="permissions"
| relationship | A link to the sub-collection for data center permissions. See Section 8.3.7, “ Permissions ”. | |
link rel="quotas"
| relationship | A link to the sub-collection for quotas associated with this data center. | |
storage_type
| enumerated |
Describes the storage type in this datacenter. A list of enumerated values is available in capabilities. See Section 7.7, “Storage Types”.
|
|
storage_format
| enumerated |
Describes the storage format version for the data center. A list of enumerated values are available in capabilities. See Section 7.20, “Storage Formats”.
|
|
version major= minor=
| complex | The compatibility level of the data center. See Chapter 6, Compatibility Level Versions. |
|
supported_versions
| complex |
A list of possible version levels for the data center. See Chapter 6, Compatibility Level Versions.
|
|
status
| see below | The data center status. |
|
The
status contains one of the following enumerative values: uninitialized, up, maintenance, not_operational, problematic and contend. These states are listed in data_center_states under capabilities (See Section 7.25, “Resource Status States”).
Example 9.1. An XML representation of a data center
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988">
<name>Default</name>
<description>The default Data Center</description>
<link rel="storagedomains"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/
storagedomains"/>
<link rel="permissions"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/permissions"/>
<link rel="quotas"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/quotas"/>
<storage_type>nfs</storage_type>
<storage_format>v3</storage_format>
<version minor="1" major="3"/>
<supported_versions>
<version minor="1" major="3"/>
</supported_versions>
<status>
<state>up</state>
</status>
</data_center>
Creation of a new data center requires the
name, storage_type and version elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 9.2. Creating a data center
POST /api/datacenters HTTP/1.1
Accept: application/xml
Content-type: application/xml
<data_center>
<name>NewDatacenter</name>
<storage_type>nfs</storage_type>
<version minor="0" major="3"/>
</data_center>
The
name, description, storage_type, version and storage_format elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 9.3. Updating a data center
PUT /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<data_center>
<name>UpdatedName</name>
<description>An updated description for the data center</description>
</data_center>
Removal of a data center requires a
DELETE request.
Example 9.4. Removing a data center
DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988 HTTP/1.1 HTTP/1.1 204 No Content
Each data center contains a sub-collection for attached storages domain. An API user interacts with this sub-collection using the standard REST methods as per Chapter 8, Common Features.
An attached storage domain has a similar representation to a top-level storage domain, with the exception that it has a data center specific
status and set of actions. States for the status element are listed in storage_domain_states under capabilities (See Section 7.25, “Resource Status States”)
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.
A data center is only ready for use when at least one storage domain is attached, which an API user
POSTs to the data center's storage domains sub-collection.
When attaching a storage domain, its
id or name must be supplied. An example of attaching a storage domain to a data center:
Example 9.5. Attach a storage domain to a data center
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
HTTP/1.1 201 Created
Location: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
fabe0451-701f-4235-8f7e-e20e458819ed">
<name>images0</name>
<type>data</type>
<status>
<state>inactive</state>
</status>
<master>true</master>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/images/0</path>
</storage>
<data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
<actions>
<link rel="activate"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
<link rel="deactivate"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
</actions>
</storage_domain>
Detach a storage domain from a data center with a
DELETE request. Include an optional async element for this request to be asynchronous.
Example 9.6. Detach a storage domain from a data center
DELETE /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <async>true</async> </action>
There are two possible actions for attached storage domains:
activate and deactivate.
An attached storage domain requires activation on a data center before use. The activate action does not take any action specific parameters.
Example 9.7. Action to active a storage domain on a datacenter
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
An attached storage domain is deactivated on a data center before removal. The deactivate action does not take any action specific parameters.
Example 9.8. Action to deactivate a storage domain on a datacenter
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Important
The information in this section is provided as a technical preview only.
The quotas sub-collection lists restrictions that Red Hat Enterprise Virtualization Manager implements on resources. An API user views this sub-collection and its resources using the
GET method as per Chapter 8, Common Features.
Example 9.9. An XML representation of a quota
<quota href="/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c
/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe"
id="e13ff85a-b2ba-4f7b-8010-e0d057c03dfe">
<name>MyQuota</name>
<description>A quota for my Red Hat Enterprise
Virtualization environment</description>
<data_center href= "/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c"
id="56087282-d7a6-11e1-af44-001a4a400e0c"/>
</quota>
Creation of a new quota requires the
name and description elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 9.10. Creating a quota
POST /api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1
Accept: application/xml
Content-type: application/xml
<quota>
<name>VMQuota</name>
<description>My new quota for virtual machines</description>
</quota>
Removal of a quota requires a
DELETE request.
Example 9.11. Removing a quota
DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe HTTP/1.1 HTTP/1.1 204 No Content
An API user forces the removal of a data center when encountering unresolvable problems with storage domains, such as the loss of connection to a master storage domain or a lack of available hosts when deleting storage domains. The API includes a
force action to help with these situations.
This action removes database entries associated with a chosen data center before the API removes the data center from the Red Hat Enterprise Virtualization environment. This means the API removes the data center regardless of associated storage domains.
This action requires a
DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.
Example 9.12. Force remove action on a data center
DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988 HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <force>true</force> </action>
This action:
- Deletes all database information for
datastorage domains associated the data center; - Deletes all database information for resources, such as virtual machines and templates, on
datastorage domains associated the data center; - Detaches
isoandexportstorage domains from the data center; and - Deletes the database information for the data center.
This action overrides the requirement for a data center to be empty before deletion.
Important
This action only removes the database entries for resources associated with the data center. The
data storage domains associated with the data center require manual format before reuse. Metadata for iso and export domains require manual cleaning prior to use on another data center.
The
clusters collection provides information about host clusters in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="clusters" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a host cluster resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 10.1. Host cluster elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="glustervolumes"
| relationship | A link to the sub-collection for Red Hat Storage volumes associated with this cluster. | |
link rel="networks"
| relationship | A link to the sub-collection for networks associated with this cluster. | |
link rel="permissions"
| relationship | A link to the sub-collection for cluster permissions. See Section 8.3.7, “ Permissions ”. | |
cpu id=
| complex | A server CPU reference that defines the CPU type all hosts must support in the cluster. See Section 7.4, “CPUs”. |
|
data_center id=
| GUID | A reference to the data center membership of this cluster. See Chapter 9, Data Centers. |
|
memory_policy
| complex | Defines the cluster's policy on host memory utilization. See Table 10.2, “Memory policy elements”. |
|
scheduling_policy
| complex | Defines the load-balancing or power sharing modes for hosts in the cluster. See Table 10.3, “Scheduling policy elements”. |
|
version major= minor=
| complex | The compatibility level of the cluster. See Chapter 6, Compatibility Level Versions. |
|
supported_versions
| complex |
A list of possible version levels for the cluster. See Chapter 6, Compatibility Level Versions.
|
|
error_handling
| complex/enumerated |
Defines virtual machine handling when a host within a cluster becomes non-operational. Requires a single on_error element containing an enumerated type property listed in capabilities. See Section 7.19, “Error Handling”.
| |
virt_service
| Boolean | Defines whether to expose virtualization services for this cluster. | |
gluster_service
| Boolean | Defines whether to expose Red Hat Storage services for this cluster. |
The
memory_policy element contains the following elements:
Table 10.2. Memory policy elements
| Element | Type | Description | Properties |
|---|---|---|---|
overcommit percent=
| complex |
The percentage of host memory allowed in use before no more virtual machines can start on a host. Virtual machines can use more than the available host memory due to memory sharing under KSM. Recommended values include 100 (None), 150 (Server Load) and 200 (Desktop Load).
|
|
transparent_hugepages
| complex |
Define the enabled status of Transparent Hugepages. The status is either true or false. Check capabilities feature set (see Section 7.3, “Features”) to ensure your version supports transparent hugepages.
|
|
The
scheduling_policy element contains the following elements:
Table 10.3. Scheduling policy elements
| Element | Type | Description | Properties |
|---|---|---|---|
policy
| enumerated |
The VM scheduling mode for hosts in the cluster. A list of enumerated types are listed in capabilities. See Section 7.27, “Scheduling Policies”.
|
|
thresholds low= high= duration=
| complex |
Defines CPU limits for the host. The high attribute controls the highest CPU usage percentage the host can have before being considered overloaded. The low attribute controls the lowest CPU usage percentage the host can have before being considered underutilized. The duration attribute refers to the number of seconds the host needs to be overloaded before the scheduler starts and moves the load to another host.
|
|
Example 10.1. An XML representation of a host cluster
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
<name>Default</name>
<description>The default server cluster</description>
<link rel="glustervolumes"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes"/>
<link rel="networks"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
<link rel="permissions"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
<cpu id="Intel Penryn Family"/>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
<memory_policy>
<overcommit percent="100"/>
<transparent_hugepages>
<enabled>false</enabled>
</transparent_hugepages>
</memory_policy>
<scheduling_policies>
<policy>evenly_distributed</policy>
<thresholds low="10" high="75" duration="120"/>
</scheduling_policies>
<version minor="0" major="3"/>
<supported_versions>
<version minor="0"<usage> major="3"/>
</supported_versions>
<error_handling>
<on_error>migrate</on_error>
</error_handling>
<virt_service>true</virt_service>
<gluster_service>false</gluster_service>
</cluster>
Creation of a new cluster requires the
name, cpu id= and datacenter elements. Identify the datacenter with either the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 10.2. Creating a host cluster
POST /api/clusters HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cluster>
<name>cluster1</name>
<cpu id="Intel Penryn Family"/>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"/>
</cluster>
The
name, description, cpu id= and error_handling elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 10.3. Updating a host cluster
PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cluster>
<description>Cluster 1</description>
</cluster>
Removal of a cluster requires a
DELETE request.
Example 10.4. Removing a cluster
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1 HTTP/1.1 204 No Content
Networks associated with a cluster are represented with the
networks sub-collection. Every host within a cluster connects to these associated networks.
The representation of a cluster's
network sub-collection is the same as a standard network resource (see Chapter 11, Networks) except for the following additional elements:
Table 10.4. Additional network elements
| Element | Type | Description | Properties |
|---|---|---|---|
cluster id=
| relationship | A reference to the cluster of which this network is a member. |
|
required
| Boolean | Defines required or optional network status. | |
display
| Boolean | Defines the display network status. Used for backward compatibility. | |
usages
| complex |
Defines a set of usage elements for the network. Users can define networks as VM and DISPLAY networks at this level.
|
An API user manipulates the
networks sub-collection as described in Chapter 8, Common Features. POSTing a network id or name reference to the networks sub-collection associates the network with the cluster.
Example 10.5. Associating a network resource with a cluster
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>rhevm</name>
</network>
HTTP/1.1 201 Created
Location: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>rhevm</name>
<status>
<state>operational</state>
</status>
<description>Display Network</description>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
<required>true</required>
<usages>
<usage>VM</usage>
</usages>
</network>
Update the resource with a
PUT request.
Example 10.6. Setting the display network status
PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<required>false</required>
<usages>
<usage>VM</usage>
<usage>DISPLAY</usage>
</usages>
</network>
The required or optional network status is set using a
PUT request to specify the Boolean value (true or false) of the required element.
Example 10.7. Setting optional network status
PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<required>false</required>
</network>
An association is removed with a
DELETE request to the appropriate element in the collection.
Example 10.8. Removing a network association from a cluster
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1 HTTP/1.1 204 No Content
Important
The information in this section is provided as a technical preview only.
Red Hat Enterprise Virtualization provides a means for creating and managing Red Hat Storage volumes. Red Hat Storage volumes are associated with host clusters and are represented with the
glustervolumes sub-collection.
Important
Red Hat Storage 2.0 is required for controlling volumes via Red Hat Enterprise Virtualization.
The representation of a Red Hat Storage volume resource in the
glustervolumes sub-collection is defined using the following elements:
Table 10.5. Gluster volume elements
| Element | Type | Description | Properties |
|---|---|---|---|
volume_type
| enumerated |
Defines the volume type. See the capabilities collection for a list of volume types.
|
|
bricks
| relationship |
The sub-collection for the Red Hat Storage bricks. When creating a new volume, the request requires a set of brick elements to create and manage in this cluster. Requires the server_id of the Red Hat Storage server and a brick_dir element for the brick directory
|
|
transport_types
| complex |
Defines a set of volume transport_type elements. See the capabilities collection for a list of available transport types.
|
|
replica_count
| integer | Defines the file replication count for a replicated volume. |
|
stripe_count
| integer | Defines the stripe count for a triped volume |
|
options
| complex |
A set of additional Red Hat Storage option elements. Each option includes an option name and a value.
|
|
Example 10.9. An XML representation of a Red Hat Storage volume
<gluster_volume id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
/glustervolume/e199f877-900a-4e30-8114-8e3177f47651">
<name>GlusterVolume1</name>
<link rel="bricks"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
/glustervolume/e199f877-900a-4e30-8114-8e3177f47651/bricks"/>
<volume_type>DISTRIBUTED_REPLICATE</volume_type>
<transport_types>
<transport_type>TCP</transport_type>
</transport_types>
<replica_count>2</replica_count>
<stripe_count>1</stripe_count>
<options>
<option>
<name>cluster.min-free-disk</name>
<value>536870912</value>
</option>
</options>
</gluster_volume>
An API user manipulates the
glustervolumes sub-collection as described in Chapter 8, Common Features. Create a Red Hat Storage volume via a POST request with the required name, volume_type and bricks to the sub-collection.
Example 10.10. Creating a Red Hat Storage volume
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<gluster_volume>
<name>GlusterVolume1</name>
<volume_type>DISTRIBUTED_REPLICATE</volume_type>
<bricks>
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<bricks>
</gluster_volume>
Remove a Red Hat Storage volume with a
DELETE request.
Example 10.11. Removing a Gluster volume
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1 HTTP/1.1 204 No Content
Important
Resources in the
glustervolumes sub-collection cannot be updated.
The
glustervolumes sub-collection contains its own bricks sub-collection to define individual bricks in a Red Hat Storage volume. The representation of a volume's bricks sub-collection is defined using the following elements:
Table 10.6. Brick elements
| Element | Type | Description | Properties |
|---|---|---|---|
server_id
| string | A reference to the Red Hat Storage server. |
|
brick_dir
| string | Defines a brick directory on the Red Hat Storage server. |
|
replica_count
| integer | Defines the file replication count for the brick in the volume. |
|
stripe_count
| integer | Defines the stripe count for the brick in the volume |
|
An API user manipulates the
glustervolumes sub-collection as described in Chapter 8, Common Features. Create new bricks via a POST request with the required server_id and brick_dir to the sub-collection.
Example 10.12. Adding a brick
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
Remove a brick with a
DELETE request.
Example 10.13. Removing a brick
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks/0a473ebe-01d2-444d-8f58-f565a436b8eb HTTP/1.1 HTTP/1.1 204 No Content
Important
Resources in the
bricks sub-collection cannot be updated.
The
start action makes a Gluster volume available for use.
Example 10.14. Starting a Volume
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
Use an optional
force Boolean element to force the action for a running volume. This is useful for starting disabled brick processes in a running volume.
The
stop action deactivates a Gluster volume.
Example 10.15. Stopping a Volume
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
Use an optional
force Boolean element to brute force the stop action.
The
setoption action sets a Gluster volume option.
Example 10.16. Set an option
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<option>
<name>cluster.min-free-disk</name>
<value>536870912</value>
</option>
<action>
The
resetoption action resets a Gluster volume option.
Example 10.17. Reset an option
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<option>
<name>cluster.min-free-disk</name>
</option>
<action>
The
networks collection provides information about the logical networks in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="networks" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a network resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 11.1. Network elements
| Element | Type | Description | Properties |
|---|---|---|---|
data_center id=
| GUID | A reference to the data center of which this cluster is a member. See Chapter 9, Data Centers. |
|
vlan id=
| integer | A VLAN tag. | |
mtu
| interger | Sets the maximum transmission unit for the logical network. If omitted, the logical network uses the default value. | |
stp
| Boolean: true or false |
true if Spanning Tree Protocol is enabled on this network.
| |
status
|
One of operational or non_operational
|
The status of the network. These states are listed in network_states under capabilities (See Section 7.25, “Resource Status States”).
|
|
usages
| complex |
Defines a set of usage elements for the network. Users can define networks as VM networks at this level.
|
Example 11.1. An XML representation of a network resource
<network id="00000000-0000-0000-0000-000000000009"
href="/api/networks/00000000-0000-0000-0000-000000000009">
<name>rhevm</name>
<description>Management Network</description>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
<mtu>1500</mtu>
<stp>false</stp>
<status>
<state>operational</status>
</status>
<usages>
<usage>VM</usage>
</usages>
</network>
Creation of a new network requires the
name and datacenter elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 11.2. Creating a network resource
POST /api/networks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<network>
<name>network 1</name>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"/>
</network>
The
name, description, ip, vlan, stp and display elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 11.3. Updating a network resource
PUT /api/networks/e6575a87-377c-4f67-9c1b-7b94eff76b17 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<network>
<description>Network 1</description>
</network>
Removal of a network requires a
DELETE request.
Example 11.4. Removing a network
DELETE /api/networks/e6575a87-377c-4f67-9c1b-7b94eff76b17 HTTP/1.1 HTTP/1.1 204 No Content
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.
The
storagedomains collection provides information about the storage domains in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="storagedomains" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a storage domain resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 12.1. Storage domain elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="permissions"
| relationship | A link to the sub-collection for storage domain permissions. See Section 8.3.7, “ Permissions ”. | |
link rel="files"
| relationship |
A link to the files sub-collection for this storage domains.
| |
link rel="vms"
| relationship |
A link to the vms sub-collection for a storage domain with type set to export.
| |
link rel="templates"
| relationship |
A link to the templates sub-collection for a storage domain with type set to export.
| |
type
| enumerated |
The storage domain type. A list of enumerated values are available in capabilities. See Section 7.8, “Storage Domain Types”.
|
|
master
| Boolean: true or false |
true if this is the master storage domain of a data center.
|
|
host
| complex | A reference to the host on which this storage domain should be initialized. The only restriction on this host is that it should have access to the physical storage specified. |
|
storage
| complex | Describes the underlying storage of the storage domain. For more information see Section 12.1, “ Storage types ”. |
|
available
| integer | Space available in bytes. |
|
used
| integer | Space used in bytes. |
|
committed
| integer | Space committed in bytes. |
|
storage_format
| enumerated |
Describes the storage format version for the storage domain. A list of enumerated values are available in capabilities. See Section 7.20, “Storage Formats”.
|
|
storage_domain_state
| enumerated |
Defines if the storage domain is currently attached to a data center. A list of enumerated values are available in capabilities.
|
|
Example 12.1. An XML representation of a storage domain
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
<name>data0</name>
<link rel="permissions"
href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
<link rel="files"
href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/files"/>
<type>data</type>
<master>true</master>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/images/0</path>
</storage>
<available>156766306304</available>
<used>433791696896</used>
<committed>617401548800</committed>
<storage_format>v1</storage_format>
<storage_domain_state>unattached</storage_domain_state>
</storage_domain>
Creation of a new storage domain requires the
name, type, host and storage elements. Identify the host element with the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 12.2. Creating a storage domain
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>data1</name>
<type>data</type>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/images/0</path>
</storage>
</storage_domain>
Only the
name element is updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 12.3. Updating a storage domain
PUT /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>data2</name>
...
</storage_domain>
Removal of a storage domain requires a
DELETE request.
Example 12.4. Removing a storage domain
DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1 HTTP/1.1 204 No Content
The API user attaches the storage domain to a data center after creation. See Section 9.1.1, “Attaching and Detaching a Storage Domain” for instructions.
Important
The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.
The
storage element contains a type element, which is an enumerated value found under the capabilities collection. See Section 7.7, “Storage Types”.
The storage element also contains additional elements specific to each storage
type. The next few sections examine these additional storage type elements.
The following table contains
nfs specific elements in a storage description.
Table 12.2. NFS specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
address
| string | The host name or IP address of the NFS server. |
|
path
| string | The path of NFS mountable directory on the server. |
|
The following table contains
posixfs specific elements in a storage description.
Table 12.3. PosixFS specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
address
| string | The host name or IP address of the PosixFS server. |
|
path
| string | The path of PosixFS mountable directory on the server. |
|
vfs_type
| string | The Linux-supported file system type of the PosixFS share. |
|
mount_options
| string | The options for mounting the PosixFS share. |
|
The following table contains
iscsi and fcp specific elements in a storage description.
Table 12.4. iSCSI and FCP specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
logical_unit id=
| complex |
The id of the logical unit. A storage domain also accepts multiple iSCSI or FCP logical units.
|
|
override_luns
| Boolean |
Defines whether to replace all logical unit settings with new settings. Set to true to override.
|
|
The
logical_unit contains a set of sub-elements.
Table 12.5. Logical unit elements
| Element | Type | Description | Properties |
|---|---|---|---|
address
| string | The address of the server containing the storage device. |
|
port
| integer | The port number of the server. |
|
target
| string | The target IQN for the storage device. |
|
username
| string | A CHAP user name for logging into a target. |
|
password
| string | A CHAP password for logging into a target. |
|
serial
| string | The serial ID for the target. |
|
vendor_id
| string | The vendor name for the target. |
|
product_id
| string | The product code for the target. |
|
lun_mapping
| integer | The Logical Unit Number device mapping for the target. |
|
In the case of iSCSI, if a
logical_unit description also contains details of the iSCSI target with the LUN in question, the target performs an automatic login when the storage domain is created.
The
localfs specific elements in a storage description are:
Table 12.6. Localfs specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
path
| string | The path of local storage domain on the host. |
|
A
localfs storage domain requires a data center with storage_type set to localfs (see Chapter 9, Data Centers). This data center only contains a single host cluster, and the host cluster only contains a single host.
Storage domains with
type set to export contain vms and templates sub-collections, which list the import candidate VMs and templates stored on that particular storage domain.
Example 12.5. Listing the virtual machines sub-collection of an export storage domain
GET /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<vms>
<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/
vms/082c794b-771f-452f-83c9-b2b5a19c0399">
<name>vm1</name>
...
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
<actions>
<link rel="import" href="/api/storagedomains/
fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
</actions>
</vm>
</vms>
VMs and templates in these collections have a similar representation to their counterparts in the top-level VMs and templates collection, except they also contain a
storage_domain reference and an import action.
The
import action imports a virtual machine or a template from an export storage domain. The destination cluster and storage domain is specified with cluster and storage_domain references.
Include an optional
name element to give the virtual machine or template a specific name.
Example 12.6. Action to import a virtual machine from an export storage domain
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>Default</name>
</cluster>
</action>
Example 12.7. Action to import a template from an export storage domain
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/templates/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>Default</name>
</cluster>
</action>
Include an optional
clone Boolean element to import the virtual machine as a new entity.
Example 12.8. Action to import a virtual machine as a new entity
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>Default</name>
</cluster>
<clone>true</clone>
<vm>
<name>MyVM</name>
</vm>
...
</action>
Include an optional
disks element to choose which disks to import using individual disk id elements.
Example 12.9. Selecting disks for an import action
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<cluster>
<name>Default</name>
</cluster>
<vm>
<name>MyVM</name>
</vm>
...
<disks>
<disk id="4825ffda-a997-4e96-ae27-5503f1851d1b"/>
</disks>
</action>
Delete a virtual machine or template from an
export storage domain with a DELETE request.
Example 12.10. Delete virtual machine from an export storage domain
DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/ 082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 Accept: application/xml HTTP/1.1 204 No Content
The
files sub-collection under each storage domain provides a way for clients to list available files. This sub-collection is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads through Red Hat Enterprise Virtualization Manager.
The addition of a CD-ROM device to a VM requires an ISO image from the
files sub-collection of an ISO storage domain.
Example 12.11. Listing the files sub-collection of an ISO storage domain
GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<files>
<file id="en_winxp_pro_with_sp2.iso"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
en_winxp_pro_with_sp2.iso">
<name>en_winxp_pro_with_sp2.iso</name>
<type>iso</type>
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
</file>
<file id="boot.vfd"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
boot.vfd">
<name>boot.vfd</name>
<type>vfd</type>
<storage_doman id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
</file>
</files>
Like other resources, files have opaque
id and href attributes. The name element contains the filename.
The API provides a user with the ability to remove an ISO or Export storage domain from one Red Hat Enterprise Virtualization Manager instance without re-formatting the underlying storage and import it into another instance. Importing is achieved similarly to adding a new storage domain, except the
name is not specified.
Example 12.12. Importing an existing export storage domain
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<storage_domain>
<type>export</type>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/export-domain</path>
</storage>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</storage_domain>
HTTP/1.1 201 Created
Content-Type: application/xml
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
<name>export1</name>
...
</storage_domain>
A
storage_domain reference is passed in the body of a DELETE request for a storage domain. The storage_domain reference is in the following form:
<storage_domain>
<host id="..."/>
</storage_domain>
OR
<storage_domain>
<host>
<name>...</name>
</host>
</storage_domain>
Format Storage Domain
An API user provides a optional format element to specify whether or not to format the storage domain after deletion.
Example 12.13. Formatting a storage domain after deletion
<storage_domain>
<host id="..."/>
<format>true</format>
</storage_domain>
If no
format element is passed, the storage domain remains unformatted.
Logical Removal of Storage Domain
The API also provides a function for the logical removal of the storage domain. This retains the storage domain's data for import. Use the destroy element to logically remove the storage domain and retain the data.
Example 12.14. Logical removal of a storage domain
<storage_domain>
<host id="..."/>
<destroy>true</destroy>
</storage_domain>
The
hosts collection provides information about the hosts in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="hosts" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a host resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 13.1. Host elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="storage"
| relationship |
A link to the storage sub-collection for host storage.
|
|
link rel="nics"
| relationship |
A link to the nics sub-collection for host network interfaces.
| |
link rel="tags"
| relationship |
A link to the tags sub-collection for host tags.
| |
link rel="permissions"
| relationship |
A link to the permissions sub-collection for host permissions. See Section 8.3.7, “ Permissions ”.
| |
link rel="statistics"
| relationship |
A link to the statistics sub-collection for host statistics.
|
|
type
|
One of rhel or rhev-h
| The host type. |
|
address
| string | The IP address or hostname of the host. |
|
certificate
| complex |
A reference to the host certificate details, including organization and subject.
|
|
status
| See below | The host status. |
|
cluster id=
| GUID | A reference to the cluster that includes this host. | |
port
| integer | The listen port of the VDSM daemon running on this host. |
|
storage_manager
| complex |
Defines an appropriate host to use as the storage pool manager (SPM). Requires a host priority attribute and a Boolean value (true or true).
|
|
power_management
| complex | Configuration options for host power management. See Section 13.1, “Power Management”. | |
ksm
| Boolean: true or false |
true if Kernel SamePage Merging (KSM) is enabled.
| |
transparent_hugepages
| Boolean: true or false |
true if Transparent Hugepages is enabled.
| |
iscsi
| complex |
The SCSI initiator for the host.
|
|
cpu
| complex |
Statistics for the host CPU. Includes sub-elements for the CPU's name, topology cores=, topology sockets= and speed. The topology cores= aggregates the total cores while the topology sockets= aggregates the total physical CPUs. The total cores available to virtual machines equals the number of sockets multiplied by the cores per socket.
|
|
memory
| integer | The total amount of host memory in bytes. |
|
summary
| complex |
Summary statistics of the virtual machines on the host. Includes sub-elements for numbers of active, migrating and total VMs.
|
|
version major= minor=
| complex | The compatibility level of the host See Chapter 6, Compatibility Level Versions. |
|
root_password
| string | The root password of this host, by convention only included in the client-provided host representation on creation. |
|
The
status contains one of the following enumerative values: down, error, initializing, installing, install_failed, maintenance, non_operational, non_responsive, pending_approval, preparing_for_maintenance, connecting, reboot, unassigned and up. These states are listed in host_states under capabilities (See Section 7.25, “Resource Status States”).
Example 13.1. An XML representation of a host
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<name>host1</name>
<actions>
<link rel="install"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/install"/>
<link rel="activate"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/activate"/>
<link rel="fence"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/fence"/>
<link rel="deactivate"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/deactivate"/>
<link rel="approve"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/approve"/>
<link rel="iscsilogin"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsilogin"/>
<link rel="iscsidiscover"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/iscsidiscover"/>
<link rel="commitnetconfig"
href="/api/hosts/762f3276-9d1e-11e0-a27c-525400d75548/commitnetconfig"/>
</actions>
<link rel="storage"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage"/>
<link rel="nics"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics"/>
<link rel="tags"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/tags"/>
<link rel="permissions"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/permissions"/>
<link rel="statistics"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/statistics"/>
<type>rhev-h</type>
<address>host1.example.com</address>
<status>
<state>up</state>
</status>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<port>54321</port>
<storage_manager priority="2">true</storage_manager>
<power_management>
<enabled>false</enabled>
<options/>
</power_management>
<ksm>
<enabled>true</enabled>
</ksm>
<transparent_hugepages>
<enabled>true</enabled>
</transparent_hugepages>
<iscsi>
<initiator>iqn.2001-04.com.example:diskarrays-sn-a8675309</initiator>
</iscsi>
<cpu>
<topology cores="2" sockets="1"/>
<name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
<speed>2993</speed>
</cpu>
<summary>
<active>2</active>
<migrating>0</migrating>
<total>3</total>
</summary>
<version major="3" minor="0"/>
</host>
Creation of a new host requires the
name, address and root_password elements. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 13.2. Creating a host
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host>
<name>host2</name>
<address>host2.example.com</address>
<root_password>p@55w0Rd!</root_password>
</host>
New host creation applies only to the addition of Red Hat Enterprise Linux hosts. Red Hat Enterprise Virtualization Manager detects hypervisor hosts automatically and requires approval for their use.
The
root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.
The
name, name, cluster, power_management, transparent_hugepages and ksm elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 13.3. Updating a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host>
<name>host3</name>
</host>
Removal of a host requires a
DELETE request.
Example 13.4. Removing a host
DELETE /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1 HTTP/1.1 204 No Content
The
power_management element provides users with the ability to set a power management configuration, which is required for host fencing. Certain sub-elements are required when configuring power_management.
Table 13.2. Power management options
| Element | Type | Description | Properties |
|---|---|---|---|
type=
| fencing device code |
A list of valid fencing device codes are available in the capabilities collection. See Section 7.5, “Power Managers”.
|
|
enabled
| Boolean: true or false | Indicates whether power management configuration is enabled or disabled. |
|
address
| string | The host name or IP address of the host. |
|
username
| string | A valid user name for power management. | |
password
| string | A valid, robust password for power management. | |
options
| complex |
Fencing options for the selected type=.
|
The
options element requires a list of option sub-elements. Each option requires a name and type attributes. Certain options are only available for specific fencing types as defined in the capabilities collection (see Section 7.5, “Power Managers”).
A new host includes an optional
power_management configuration when POSTing to the host resource. The power_management configuration is updatable using a PUT request.
Example 13.5. An XML representation of a host's power management configuration
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<name>host1</name>
...
<power_management type="ilo">
<enabled>true</enabled>
<address>192.168.1.107</address>
<username>admin</username>
<password>p@55w0Rd!</password>
<options>
<option name="secure" value="true"/>
<option name="port" value="54345"/>
<option name="slot" value="3"/>
</options>
</power_management>
...
</host>
The API provides two configuration settings for a host's memory management.
Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference. This helps with optimization for memory density. KSM uses the
ksm element.
Example 13.6. Setting KSM memory management
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<ksm>true</ksm>
</host>
Transparent Hugepage support expands the size of memory pages beyond the standard 4kB limit. This reduces memory consumption and increases host performance. Transparent Hugepage support uses the
transparent_hugepages element.
Example 13.7. Setting Transparent Hugepage memory management
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<transparent_hugepages>true</transparent_hugepages>
</host>
Availability of Transparent Hugepage support is found in the
capabilities collection. See Section 7.3, “Features”.
The
nics sub-collection represents a host's physical network interfaces. Each host_nic element in the representation acts as a network interface and contains the following elements:
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 13.3. Elements for a host's network interfaces
| Element | Type | Description | Properties |
|---|---|---|---|
name
| string |
The name of the host network interface, e.g. eth0
|
[a]
|
link rel="statistics"
| relationship |
A link to the statistics sub-collection for a host's network interface statistics.
|
|
link rel="master"
| relationship | A reference to the master bonded interface, if this is a slave interface. |
|
host id=
| GUID | A reference to the host. |
|
network id=
| GUID | A reference to the network, if any, that the interface is attached. |
[b]
|
mac address=
| string | The MAC address of the interface. |
|
ip address= netmask= gateway= mtu=
| complex | The IP level configuration of the interface. | |
mtu
| complex | The maximum transmission unit for the interface. | |
boot_protocol
| enumerated |
The protocol for IP address assignment when the host is booting. A list of enumerated values is available in capabilities. See Section 7.18, “Boot Protocols”.
| |
speed
| integer | The network interface speed in bits per second. |
|
status
| enumerated |
The link status for the network interface. These states are listed in host_nic_states under capabilities (See Section 7.25, “Resource Status States”).
|
|
vlan id
| integer | The VLAN which this interface represents. |
|
bonding
| complex |
A list of options and slave NICs for bonded interfaces.
|
[c]
|
bridged
| Boolean |
Defines the bridged network status. Set to true for a bridged network and true for a bridgeless network.
| |
[a]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[b]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[c]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
| |||
Example 13.8. An XML representation of a network interface on a host
<host_nic id="e8f02fdf-3d7b-4135-86e1-1bf185570cd8"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8">
<name>bond0</name>
<link rel="statistics"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8/statistics"/>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
<network id="e657d631-657d-42bb-a536-73501a085d85"
href="/api/networks/e657d631-657d-42bb-a536-73501a085d85"/>
<mac address="D6:76:F1:3A:AF:74"/>
<ip address="192.168.0.128" netmask="255.255.255.0" gateway="192.168.0.1"/>
<mtu>1500</mtu>
<boot_protocol>dhcp</boot_protocol>
<speed>1000000000</speed>
<status>
<state>up</state>
</status>
<bonding>
<options>
...
</options>
<slaves>
<host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
<host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
</slaves>
</bonding>
<actions>
<link rel="attach"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach"/>
<link rel="detach"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach"/>
</actions>
<bridged>true</bridged>
</host_nic>
An API user creates only bonded interfaces (see Section 13.3.1, “Bonded Interfaces”). All other network interfaces contain updatable
network, ip and boot_protocol elements using a PUT request.
When adding a new network interface, the
name and network elements are required. Identify the network element with the id attribute or name element.
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host_nic>
<name>MyNIC</name>
<network id="e657d631-657d-42bb-a536-73501a085d85">
<name>MyNetwork</name>
</network>
</host_nic>
An API user modifies a network interface with a
PUT request.
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/
e8f02fdf-3d7b-4135-86e1-1bf185570cd8 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host_nic>
<ip address="192.168.0.129" netmask="255.255.255.0" gateway="192.168.0.1"/>
</host_nic>
An API user removes a network interface with a
DELETE request.
DELETE /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/ e8f02fdf-3d7b-4135-86e1-1bf185570cd8 HTTP/1.1 HTTP/1.1 204 No Content
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.
A bonded interface is represented as a
host_nic resource containing a bonding element.
Table 13.4. Bonded interface properties
| Element | Type | Description | Properties |
|---|---|---|---|
options
| complex |
A list of option elements for a bonded interface. Each option contains property name and value attributes.
|
[a]
|
slaves
| complex |
A list of slave host_nic id= elements for a bonded interface.
|
[b]
|
[a]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[b]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
| |||
An API user creates a new bond when creating a new
host_nic (POST) or updating a host_nic (PUT). Use either the id or name elements identify the slave host_nic elements.
Example 13.9. Creating a bonded interface
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<host_nic>
<name>bond4</name>
<network id="e657d631-657d-42bb-a536-73501a085d85"/>
<bonding>
<options>
...
</options>
<slaves>
<host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
<host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
</slaves>
</bonding>
</host_nic>
Important
bond0, bond1, bond2, bond3 and bond4 are the only valid names for a bonded interface.
Use a
DELETE request to a bonded interface URI to delete it.
Important
Changes to bonded interface configuration must be explicitly committed. See Section 13.6.8, “ Commit Network Configuration Action ”.
Each host's network interface exposes a
statistics sub-collection for a host's network interface statistics. Each statistic contains the following elements:
Table 13.5. Elements for a host's network interface 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.
|
host_nic id=
| relationship |
A relationship to the containing host_nic resource.
|
The following table lists the statistic types for network interfaces on hosts.
Table 13.6. Host NIC statistic types
|
Name
|
Description
|
|---|---|
data.current.rx
|
The rate in bytes per second of data received.
|
data.current.tx
|
The rate in bytes per second of data transmitted.
|
errors.total.rx
|
Total errors from receiving data.
|
errors.total.tx
|
Total errors from transmitting data.
|
Example 13.10. An XML representation of a host's network interface statistics sub-collection
<statistics>
<statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
c34728e8-4338-4540-ac9b-86b8582e602e/statistics/
ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
<name>data.current.rx</name>
<description>Receive data rate</description>
<values type="DECIMAL">
<value>
<datum>0</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES_PER_SECOND</unit>
<host_nic id="c34728e8-4338-4540-ac9b-86b8582e602e"
href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
c34728e8-4338-4540-ac9b-86b8582e602e"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
A host network interface is attached to a network, indicating the given network is accessible over the interface. Either the
id or name elements identify the network.
Example 13.11. Action to attach a host network interface to a network
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>
Important
This networking configuration change must be explicitly committed. See Section 13.6.8, “ Commit Network Configuration Action ”.
Detach an interface from a network. Either the
id or name elements identify the network.
Example 13.12. Action to detach a host network interface from a network
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>
Important
This networking configuration change must be explicitly committed. See Section 13.6.8, “ Commit Network Configuration Action ”.
A host's
nics collection contains an action to perform setup of multiple network interfaces. Perform a POST request on the setupnetworks action.
Example 13.13. Action to setup multiple host network interfaces
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/setupnetworks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<host_nics>
<host_nic id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
<name>em1</name>
<network id="00000000-0000-0000-0000-000000000009"/>
<boot_protocol>dhcp</boot_protocol>
</host_nic<
<host_nic id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
<name>em2</name>
<network id="00000000-0000-0000-0000-000000000010"/>
<ip address="10.35.1.247" netmask="255.255.254.0"
gateway="10.35.1.254"/>
<boot_protocol>static</boot_protocol>
</host_nic>
<checkConnectivity>true</checkConnectivity>
<connectivityTimeout>60</connectivityTimeout>
<force>false</false>
</host_nics>
</action>
This action updates all specified network interface resources with standard NIC elements. The request includes additional elements specified in the following table.
Table 13.7. Additional elements for multiple host network interface setup
| Element | Type | Description | Properties |
|---|---|---|---|
checkConnectivity
| Boolean |
Set to true to verify connectivity between the host and the Red Hat Enterprise Virtualization Manager. If the connectivity is lost, Red Hat Enterprise Virtualization Manager reverts the settings.
| |
connectivityTimeout
| integer | Defines the timeout for loss of connectivity. | |
force
| Boolean |
Set to true to force changes even if connectivity is lost.
|
The
storage sub-collection provides a list of the iSCSI and FCP storage representations available on the host. This storage is used to create storage domains, as described in Chapter 12, Storage Domains.
Each
storage representation in the sub-collection represents a SCSI LUN.
Example 13.14. An XML representation of the storage sub-collection on a host
<host_storage>
<storage id="82fb123b-321e-40a1-9889-95dcd2654463"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage/
82fb123b-321e-40a1-9889-95dcd2654463">
<name>LUN0</name>
<type>iscsi</type>
<logical_unit id="LUN0">
<address>mysan.example.com</address>
<target>iqn.2009-08.com.example:mysan.foobar</target>
</logical_unit>
</storage>
</host_storage>
Note
The
host_storage collection is read-only.
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.
Each host resource exposes a
statistics sub-collection for host-specific statistics. Each statistic contains the following elements:
Table 13.8. Elements for host 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.
|
host id=
| relationship |
A relationship to the containing host resource.
|
The following table lists the statistic types for hosts.
Table 13.9. Host statistic types
|
Name
|
Description
|
|---|---|
memory.total
|
Total memory in bytes on the host.
|
memory.used
|
Memory in bytes used on the host.
|
memory.free
|
Memory in bytes free on the host.
|
memory.buffers
|
I/O buffers in bytes.
|
memory.cached
|
OS caches in bytes.
|
swap.total
|
Total swap memory in bytes on the host.
|
swap.free
|
Swap memory in bytes free on the host.
|
swap.used
|
Swap memory in bytes used on the host.
|
swap.cached
|
Swap memory in bytes also cached in host's memory.
|
ksm.cpu.current
|
Percentage of CPU usage for Kernel SamePage Merging.
|
cpu.current.user
|
Percentage of CPU usage for users.
|
cpu.current.system
|
Percentage of CPU usage for system.
|
cpu.current.idle
|
Percentage of idle CPU usage.
|
cpu.load.avg.5m
|
CPU load average per five minutes.
|
Example 13.15. An XML representation of the host's statistics sub-collection
<statistics>
<statistic id="4ae97794-f56d-3f05-a9e7-8798887cd1ac"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/
statistics/4ae97794-f56d-3f05-a9e7-8798887cd1ac">
<name>memory.total</name>
<description>Total memory</description>
<unit>BYTES</unit>
<type>GUAGE</type>
<values type="INTEGER">
<value>
<datum>3983540224<datum>
</value>
</values>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</statistic>
...
</statistics>
Note
A host's
statistics sub-collection is read-only.
The following sections describe the actions associated with
host resources.
The API contains a number of possible actions for hosts:
install, activate, fence, deactivate, approve, iscsilogin, iscsidiscover and commitnetconfig.
Install VDSM and related software on the host. The host type defines additional parameters for the action.
- Red Hat Enterprise Linux host - This host type requires a
root_passwordelement that refers to the password for the host'srootuser. - Red Hat Enterprise Virtualization Hypervisor host - This host type requires an
imageelement that refers to an ISO file stored on the Red Hat Enterprise Virtualization Manager server.
Example 13.16. Action to install VDSM to a Red Hat Enterprise Linux host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<root_password>p@55w0Rd!</root_password>
</action>
Example 13.17. Action to install VDSM to a Red Hat Enterprise Virtualization Hypervisor host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<image>/usr/share/rhev-hypervisor/rhev-hypervisor.iso</image>
</action>
Activate the host for use, such as running virtual machines.
Example 13.18. Action to activate a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
An API user controls a host's power management device with the
fence action. See Section 13.1, “Power Management” for details on configuring a fencing device for a host.
The
capabilities lists available fence_type options. See Section 7.6, “Fence Types” for details on accessing this list.
Example 13.19. Action to fence a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/fence
Accept: application/xml
Content-Type: application/xml
<action>
<fence_type>start</fence_type>
</action>
Deactivate the host to perform maintenance tasks.
Example 13.20. Action to deactivate a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/deactivate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Approve a pre-installed Red Hat Enterprise Virtualization Hypervisor host for usage in the virtualization environment. This action also accepts an optional
cluster element to define the target cluster for this host.
Example 13.21. Action to approve a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/approve HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
<action>
The
iscsilogin action enables a host to login to an iSCSI target. Logging into a target makes the contained LUNs available in the host_storage collection. See Section 13.4, “Storage Sub-Collection”.
Example 13.22. Action to enable a host to login to iSCSI target
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsilogin HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<iscsi>
<address>mysan.example.com</address>
<target>iqn.2009-08.com.example:mysan.foobar</target>
<username>jimmy</username>
<password>s3kr37</password>
</iscsi>
</action>
The
iscsidiscover action enables an iSCSI portal to be queried for its list of LUNs.
Example 13.23. Action to query a list of LUNs for iSCSI portal
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<iscsi>
<address>mysan.example.com</address>
</iscsi>
</action>
HTTP/1.1 202 Accept
Content-Type: application/xml
<action id="e9126d04-0f74-4e1a-9139-13f11fcbb4ab"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover/
e9126d04-0f74-4e1a-9139-13f11fcbb4ab">
<iscsi_target>iqn.2009-08.com.example:mysan.foobar</iscsi_target>
...
<action>
An API user commits the network configuration to persist a host network interface attachment or detachment, or persist the creation and deletion of a bonded interface.
Example 13.24. Action to commit network configuration
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/commitnetconfig HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Important
Networking configuration is only committed after the Manager has established that host connectivity is not lost as a result of the configuration changes. If host connectivity is lost, the host requires a reboot and automatically reverts to the previous networking configuration.
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 5, 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 8.1, “Element property icons”
Table 14.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 8.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 7.9, “Virtual Machine Types”.
|
|
status
| See below | The virtual machine status. |
|
memory
| integer | The amount of memory allocated to the guest in bytes. | |
cpu
| complex |
Defines CPU details for the virtual machine. The
topology sub-element sets 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.
The
cputune sub-element maps virtual CPUs to physical host CPUs using a series of vcpupin elements. Each vcpupin elements contains a virtual CPU attribute (vcpu) and an attribute to define which physical to use (cpuset). Set the cpuset to either a single CPU (cpuset="0"), multiple CPUs (cpuset="0,2"), a CPU range (cpuset="0-3") or a CPU range with exclusion (cpuset="0-3,^2").
| |
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 7.10, “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. The allow_reconnect Boolean value specifies if a client can reconnet to the machine via display.
| |
cluster id=
| GUID | A reference to the virtual machine's host cluster. See Chapter 10, 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, ovirt, 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.
| |
quota id=
| GUID | Sets a quota for the virtual machine. | |
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 7.17, “Custom Properties”.
| |
usb
| complex |
Defines the USB policy for a virtual machine. Requires an enabled element set to a Boolean value and a type element set to either native or legacy.
| |
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 E, Timezones. | |
domain
| complex |
The the Sysprep domain setting for a Windows virtual machine. Requires a name from the domains collection. See Chapter 18, Domains for more information about domains.
| |
payloads
| complex |
Defines a set of payload elements to deliver content to a virtual machine upon boot. Each payload requires a type attribute, either cdrom or floppy, and a file element that specifies the name and location using the name attribute. Within the file element is a content element, which defines the content to deliver to the file.
|
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 7.25, “Resource Status States”).
Example 14.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="2" sockets="2"/>
<cputune>
<vcpupin vcpu="0" cpuset="1-4,^2"/>
<vcpupin vcpu="1" cpuset="0,1"/>
<vcpupin vcpu="2" cpuset="2,3"/>
<vcpupin vcpu="3" cpuset="0,4"/>
</cputune>
</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>
<payloads>
<payload type='cdrom'>
<file name='/etc/hosts'>
<content>
127.0.0.1 localhost myvm.example.com
</content>
</file>
</payload>
</payloads>
</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 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 14.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>
Note
Memory in the previous example is converted to bytes using the following formula:
512MB * 10242 = 536870912 bytes
The
name, description, cluster, type, memory, cpu, os, high_availability, display, timezone, domain, stateless, placement_policy, memory_policy, usb, payloads, origin and custom_properties elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 14.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>
Note
Memory in the previous example is converted to bytes using the following formula:
1024MB * 10242 = 1073741824 bytes
Removal of a virtual machine requires a
DELETE request.
Example 14.4. Removing a virtual machine
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 HTTP/1.1 204 No Content
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 8.1, “Element property icons”
Table 14.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 (See Section 7.25, “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 7.15, “Disk Interfaces”.
| |
format
| enumerated |
The underlying storage format. A list of enumerated values is available in capabilities. See Section 7.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.
| |
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. See Section 12.1.3, “ iSCSI and FCP ” for more information.
|
|
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 14.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>
<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 14.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>
The
name, description, storage_domains, interface, bootable, shareable, wipe_after_delete and propagate_errors elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 14.7. 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 14.8. 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
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 14.9. 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.
Each virtual machine's disk exposes a
statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:
Table 14.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 14.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 14.10. 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.
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 14.11. 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 14.12. 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>
Each virtual machine's disk provides a set of
activate and deactivate actions to add and remove disks from a virtual machine.
Example 14.13. 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 14.14. 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.
The
nics sub-collection represents all network interface devices on a virtual machine. A nic representation contains the following elements:
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 14.5. Elements for virtual machine network interfaces
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="statistics"
| relationship |
A link to the statistics sub-collection for a virtual machine's network interface statistics.
|
|
network id=
| GUID | A reference to the network which the interface should be connected. |
|
interface
| enumerated |
The type of driver used for the nic. A list of enumerated values is available in capabilities. See Section 7.12, “NIC Interface Types”.
| |
mac address=
| string | The MAC address of the interface. |
|
port_mirroring
| complex |
Defines whether the NIC receives mirrored traffic. Define a networks element with a series of network id= references.
| |
active
| Boolean | Defines if the NIC is connected to the virtual machine. |
|
Example 14.15. An XML representation of a network interface
<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e"
ref="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
<link rel="statistics"
href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e/statistics"/>
<name>nic1</name>
<interface>virtio</interface>
<mac address="00:1a:4a:16:84:07"/>
<network id="00000000-0000-0000-0000-000000000009"
href="/api/networks/00000000-0000-0000-0000-000000000009"/>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
<port_mirroring>
<networks>
<network id="56087282-d7a6-11e1-af44-001a4a400e0c"
href="/api/networks/56087282-d7a6-11e1-af44-001a4a400e0c"/>
</networks>
</port_mirroring>
</nic>
When adding a new network interface, the
name and network elements are required. Identify the network element with the id attribute or name element.
Example 14.16. Creating a virtual machine NIC
POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml
<nic>
<name>nic1</name>
<network id="00000000-0000-0000-0000-000000000009"/>
</nic>
An API user modifies a network interface with a
PUT request.
Example 14.17. Updating a virtual machine NIC
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
Accept: application/xml
Content-type: application/xml
<nic>
<name>nic2</name>
<network id="00000000-0000-0000-0000-000000000010"/>
<type>e1000</type>
</nic>
An API user removes a network interface with a
DELETE request.
Example 14.18. Deleting a virtual machine NIC
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/ 7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1 HTTP/1.1 204 No Content
Each virtual machine's network interface exposes a
statistics sub-collection for network interface statistics. Each statistic contains the following elements:
Table 14.6. Elements for a virtual machine's network interface 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.
|
nic id=
| relationship |
A relationship to the containing nic resource.
|
The following table lists the statistic types for network interfaces on virtual machines.
Table 14.7. Virtual machine NIC statistic types
|
Name
|
Description
|
|---|---|
data.current.rx
|
The rate in bytes per second of data received.
|
data.current.tx
|
The rate in bytes per second of data transmitted.
|
errors.total.rx
|
Total errors from receiving data.
|
errors.total.tx
|
Total errors from transmitting data.
|
Example 14.19. An XML representation of a virtual machine's NIC statistics sub-collection
<statistics>
<statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/nics/
6cd08e76-57c0-41ba-a728-7eba46ae1e36/statistics/
ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
<name>data.current.rx</name>
<description>Receive data rate</description>
<values type="DECIMAL">
<value>
<datum>0</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES_PER_SECOND</unit>
<nic id="6cd08e76-57c0-41ba-a728-7eba46ae1e36"
href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
Each virtual machine's network interface provides a set of
activate and deactivate actions to add and remove NICs from a virtual machine.
Example 14.20. Action to activate a virtual machine NIC
POST /api/vms/b1c03f94-9cad-4344-8a89-6a7064a73bb3/nics/a4226079-5ce7-4927-bd78-814049ef1ffe/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Example 14.21. Action to deactivate a virtual machine NIC
POST /api/vms/b1c03f94-9cad-4344-8a89-6a7064a73bb3/nics/a4226079-5ce7-4927-bd78-814049ef1ffe/deactivate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Use these actions to hotplug and hotunplug NICs to virtual machines.
Important
The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:
- Red Hat Enterprise Linux 6;
- Red Hat Enterprise Linux 5;
- Windows Server 2008; and,
- Windows Server 2003.
The
cdroms sub-collection represents the CD-ROM device on a virtual machine. A cdrom representation contains the following elements:
Table 14.8. Elements for virtual machine CD-ROMs
| Element | Type | Description | Properties |
|---|---|---|---|
file id=
| string/filename | A reference to an ISO image. See Section 12.3, “ Files Sub-Collection ”. |
Example 14.22. An XML representation of a CD-ROM device
<cdrom id="00000000-0000-0000-0000-000000000000"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/
00000000-0000-0000-0000-000000000000">
<file id="rhel-server-6.0-x86_64-dvd.iso"/>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>
Send a
POST request with a file id element to add a new CD-ROM resource.
Example 14.23. Changing a CD-ROM file
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
<file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
The API changes the CD-ROM using a
PUT request:
Example 14.24. Changing a CD-ROM file
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
<file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
The API changes the CD-ROM for the current session only using a
PUT request with an additional current URI argument:
Example 14.25. Changing a CD-ROM file during a current session
POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000?current HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
<file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
Note
A virtual machine only contains a single CD-ROM device.
A virtual machine saves and restores disk state as a number of snapshots. These are represented and managed through a
rel="snapshot" sub-collection that behaves similar to other collections, as described in Chapter 8, Common Features.
Each virtual machine snapshot is represented with an individual
snapshot element that contains the following sub-elements:
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 14.9. Elements for virtual machine snapshots
| Element | Type | Description | Properties |
|---|---|---|---|
vm id=
| GUID | The ID and URI of the virtual machine to which this snapshot pertains. |
|
date
|
xsd:dateTime format: YYYY-MM-DDThh:mm:ss
| The date and time at which this snapshot was created. |
|
link rel="prev"
| relationship | A link to the previous snapshot of this virtual machine. |
|
When adding a new snapshot, only the
description element is specified.
Note
Note that it is not possible to modify snapshot elements using
PUT.
Example 14.26. An XML representation of a virtual machine snapshot
<snapshot id="f5288fd5-5178-4b7d-b87c-c01a40e40168"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/
f5288fd5-5178-4b7d-b87c-c01a40e40168">
<description>Virtual Machine 1 - Snapshot A</description>
<actions>
<link rel="restore"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/
f5288fd5-5178-4b7d-b87c-c01a40e40168/restore"/>
</actions>
<link rel="prev"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/
ce411b3e-e4e0-4482-8b2f-d1ed998b9130"/>
<vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
<date>2010-08-16T14:24:29</date>
</snapshot>
An API user restores a virtual machine snapshot using the
rel="restore" action link in the snapshot representation.
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/snapshots/f5288fd5-5178-4b7d-b87c-c01a40e40168/restore HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Note
The REST API also provides live snapshot capability, which allows users to take snapshots while a virtual machine is running.
API provides a function to create virtual machines from a snapshot of a previous machine. API users create a new virtual machine while retaining the original virtual machine with all snapshots intact.
Creation of a virtual machines from a snapshot requires an additional
snapshots element to a standard representation of a virtual machine, which a user sends in a POST request to the vms collection.
The
snapshots element contains a snapshot id= element to define the specific snapshot to use as a basis for the virtual machine. The snapshots element also requires a Boolean clone element, which signifies to the API to clone the new virtual machine from the specified snapshot.
Example 14.27. Clone Virtual Machine from Snapshot
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
...
<snapshots>
<clone<true</clone>
<snapshot id="id="3f68ee63-0016-4f8c-9b8a-11d9f28f7c9e"/>
</snapshots>
...
</vm>
Each virtual machine resource exposes a
statistics sub-collection for virtual machine-specific statistics. Each statistic contains the following elements:
Table 14.10. Elements for virtual machine 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.
|
vm id=
| relationship |
A relationship to the containing vm resource.
|
The following table lists the statistic types for virtual machines.
Table 14.11. Virtual machine statistic types
|
Name
|
Description
|
|---|---|
memory.installed
|
Total memory in bytes allocated for the virtual machine's use.
|
memory.used
|
Current memory in bytes used by the virtual machine.
|
cpu.current.guest
|
Percentage of CPU used by the guest.
|
cpu.current.hypervisor
|
Percentage of CPU overhead on the hypervisor.
|
cpu.current.total
|
Total percentage of the current CPU in use.
|
Example 14.28. An XML representation of a virtual machine's statistics sub-collection
<statistics>
<statistic id="ef802239-b74a-329f-9955-be8fea6b50a4"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/
statistics/ef802239-b74a-329f-9955-be8fea6b50a4">
<name>memory.installed</name>
<description>Total memory configured</description>
<unit>BYTES</unit>
<type>GUAGE</type>
<values type="DECIMAL">
<value>
<datum>1073741824<datum>
</value>
</values>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</statistic>
...
</statistics>
Note
A virtual machine's
statistics sub-collection is read-only.
The following sections describe the actions associated with
vm resources.
The API contains a number of possible actions for virtual machines:
start, stop, shutdown, suspend, detach, migrate, cancelmigration, export, move and ticket.
Information on the action for importing virtual machines is found in Section 12.2, “ Export Storage Domains ”.
The start action launches a virtual machine.
Example 14.29. Action to start a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The start action allows a
vm element to be provided as a parameter. If a vm element is provided, the virtual machine uses the values from the provided element and overrides system settings at start time. These settings persist until a user stops the virtual machine. Examples of these elements include os, domain, placement_policy, cdroms, stateless and display type.
Example 14.30. Action to start a virtual machine with overridden parameters
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<pause>true</pause>
<vm>
<stateless>true</stateless>
<display>
<type>spice</type>
</display>
<os>
<boot dev="cdrom"/>
</os>
<cdroms>
<cdrom>
<file id="windows-xp.iso"/>
</cdrom>
</cdroms>
<domain>
<name>domain.example.com</name>
<user>
<user_name>domain_user</user_name>
<password>domain_password</password>
</user>
</domain>
<placement_policy>
<host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>
</placement_policy>
</vm>
</action>
Note
Only virtual machines running Windows operating systems use the
domain element when overriding parameters on boot with the start action. The domain element determines the domain that the Windows virtual machine joins. If the domain does not exist in the domains collection (see Chapter 18, Domains), this element requires additional user authentication details, including a user_name and password. If the domain exists in the domains collection, the action requires no additional user authentication details.
The stop action forces a virtual machine to power-off.
Example 14.31. Action to stop a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The shutdown action sends a shutdown request to a virtual machine.
Example 14.32. Action to send a shutdown request to a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The suspend action saves the virtual machine state to disk and stops it. The virtual machine state is restored with the start action.
Example 14.33. Action to save virtual machine state and suspend the machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The detach action detaches a virtual machine from a pool.
Example 14.34. Action to detach a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The migrate action migrates a virtual machine to another physical host. The destination
host element is an optional element as Red Hat Enterprise Virtualization Manager automatically selects a default host for migration. If an API user requires a specific host, the user can specify the host with either an id or name parameter.
Example 14.35. Action to migrate a virtual machine to another host
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
The cancel migration action stops any migration of a virtual machine to another physical host.
Example 14.36. Action to cancel migration of a virtual machine to another host
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The export action exports a virtual machine to an
export storage domain. A destination storage domain must be specified with a storage_domain reference.
The export action reports a failed action if a virtual machine of the same name exists in the destination domain. Set the
exclusive parameter to true to change this behaviour and overwrite any existing virtual machine.
If snapshots of the virtual machine are not included with the exported virtual machine, set the
discard_snapshots parameter to true.
Example 14.37. Action to export a virtual machine to an export storage domain
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>export1</name>
</storage_domain>
<exclusive>true</exclusive>
<discard_snapshots>true</discard_snapshots>
</action>
The move action moves virtual machine disks to a different storage domain. The destination storage domain is specified via a
storage_domain reference to either a name or an id.
Example 14.38. Action to move virtual machine disks to a different storage domain
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/move HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images2</name>
</storage_domain>
</action>
The ticket action generates a time-sensitive authentication token for accessing a virtual machine's display. The client-provided
action optionally includes a ticket representation containing a value (if the token string needs to take on a particular form) and/or an expiry time in minutes. In any case, the response specifies the actual ticket value and expiry used.
Example 14.39. Action to generate authentication token for a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<ticket>
<expiry>120</expiry>
</ticket>
</action>
200 OK
Content-Type: application/xml
<action id="94e07552-14ba-4c27-8ce6-2cc75190d3ef"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
94e07552-14ba-4c27-8ce6-2cc75190d3ef">
<status>
<state>complete</state>
</status>
<ticket>
<value>5c7CSzK8Sw41</value>
<expiry>120</expiry>
</ticket>
<link rel="parent"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
<link rel="replay"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>
An API user forces the removal of a faulty virtual machine with the
force action. This action requires a DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.
Example 14.40. Force remove action on a virtual machine
DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<force>true</force>
</action>
The
disks collection provides information about all disks in a Red Hat Enterprise Virtualization environment. A user attaches and dettaches disks from any virtual machine and floats them between virtual machines. An API user accesses this information through the rel="disks" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a
disks resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 15.1. Elements for floating disks
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="statistics"
| relationship |
A link to the statistics sub-collection for a virtual machine's disk statistics.
|
|
image_id
| GUID | A reference to the virtual machine image stored on the defined storage domain. |
|
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.
|
|
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 (See Section 7.25, “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 7.15, “Disk Interfaces”.
| |
format
| enumerated |
The underlying storage format. A list of enumerated values is available in capabilities. See Section 7.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.
| |
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.
| |
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. See Section 12.1.3, “ iSCSI and FCP ” for more information.
|
|
active
| Boolean | Defines if the disk is connected to the virtual machine. |
|
Example 15.1. An XML representation of a disk device
<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
<link rel="statistics"
href="/api/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>
<lunStorage>
<storage>
<logical_unit id="lun1">
...
</logical_unit>
<storage>
</lunStorage>
</disk>
When creating a new floating disk, the API requires the
size and storage_domains elements.
Example 15.2. Creating a new a floating disk device
POST /api/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>
</disk>
Important
Search queries for disks based upon name require the
alias search parameter instead of name.
Each floating disk exposes a
statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:
Table 15.2. 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 floating disks.
Table 15.3. 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.3. An XML representation of a virtual machine's statistics sub-collection
<statistics>
<statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
href="/api/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/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
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 5, 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 8.1, “Element property icons”
Table 16.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 8.3.7, “ Permissions ”.
| |
type
| enumerated |
The type of virtual machine the template provides. A list of enumerated values are available in capabilities. See Section 7.9, “Virtual Machine Types”.
| |
status
|
One of illegal, locked or ok
|
The template status. These states are listed in template_states under capabilities (See Section 7.25, “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 7.10, “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 10, Host Clusters. |
|
vm id=
| GUID | A reference to the VM on which this template is based. See Chapter 14, 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, ovirt, 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. The allow_reconnect Boolean value specifies if a client can reconnet to the machine via display.
| |
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 and a type element set to either native or legacy.
| |
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.
| |
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 7.17, “Custom Properties”.
| |
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 E, Timezones. | |
domain
| complex |
The the Sysprep domain setting for a Windows virtual machine template. Requires a name from the domains collection. See Chapter 18, Domains for more information about domains.
|
Example 16.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 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 16.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 8.3.2, “ Updating a Resource ” for more information.
Example 16.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 16.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:
disks- This collection accepts removal (DELETE) requests. See Section 14.1, “Disks Sub-Collection” for more information.nics- Thenicssub-collection accepts requests for creation (POST), modification (PUT) and removal (DELETE) of network interfaces in a virtual machine template. See Section 14.2, “Network Interfaces Sub-Collection” for more information.cdroms- This is a read-only sub-collection. See Section 14.3, “CD-ROMs Sub-Collection” for more information.
Note
Users delete a template
disk from a specific storage domain using the following body in the DELETE request:
DELETE /api/templates/a03dca95-98cb-430d-89dc-b11482543748/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
...
</action>
The
templates collection contains an export action. Information on the action for importing templates is found in Section 12.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.
The export action reports a failed action if a virtual machine template of the same name exists in the destination domain. Set the
exclusive parameter to true to change this behaviour and overwrite any existing virtual machine template.
Example 16.5. Action to export a template to an export storage domain
POST /api/templates/a03dca95-98cb-430d-89dc-b11482543748/export HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
<exclusive>true<exclusive/>
</action>
The
vmpools collection provides information about the virtual machine pools in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="vmpools" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a virtual machine pool resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 17.1. Virtual machine pool elements
| Element | Type | Description | Properties |
|---|---|---|---|
size
| integer | The number of virtual machines in the pool. | |
cluster id=
| GUID | A reference to the cluster resource which virtual machines in this pool run. |
|
template id=
| GUID | A reference to the template resource which virtual machines in this pool are based. |
|
Example 17.1. An XML representation of a virtual machine pool
<vmpool id="2d2d5e26-1b6e-11e1-8cda-001320f76e8e"
href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e">
<name>VMPool1</name>
<description>Virtual Machine Pool 1</description>
<size>2</size>
<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"/>
</vmpool>
A new pool requires the
name, cluster and template elements. Identify the cluster and template with the id attribute or name element. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 17.2. Creating a virtual machine pool
POST /api/vmpools HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vmpool>
<name>VM Pool A</name>
<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"/>
</vmpool>
The
name, description and size are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 17.3. Updating a virtual machine pool
PUT /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vmpool>
<name>VM Pool B</name>
<description>Virtual Machine Pool B</description>
<size>3</size>
</vmpool>
Removal of a virtual machine pool requires a
DELETE request.
Example 17.4. Removing a virtual machine
DELETE /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1 HTTP/1.1 204 No Content
Important
The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement in Section 5, “Backwards Compatibility Statement”.
The API provides the ability to access user and group information from the organization's directory service using the
domains collection. Domain information is referenced with the rel="domains" link.
Table 18.1. Domain elements
| Element | Type | Description |
|---|---|---|
name
| string | The domain name. |
link rel="users"
| relationship | A link to the sub-collection for users associated with this domain. |
link rel="groups"
| relationship | A link to the sub-collection for groups associated with this domain. |
The links to
users and groups sub-collections also accept search queries. See Section 8.2.3, “ Searching Collections with Queries ” for more information.
Example 18.1. An XML representation of a domain resource
<domain id="77696e32-6b38-7268-6576-2e656e676c61"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61">
<name>domain.example.com</name>
<link rel="users"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users"/>
<link rel="groups"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups"/>
<link rel="users/search"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
users?search={query}"/>
<link rel="groups/search"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
groups?search={query}"/>
</domain>
Note
The
domains collection and its sub-collections are read-only.
The
users sub-collection contains all users in the directory service. This information is used to add new users to the Red Hat Enterprise Virtualization environment as per Chapter 21, Users.
Table 18.2. Domain user elements
| Element | Type | Description |
|---|---|---|
name
| string | The name of the user. |
last_name
| string | The surname of the user. |
user_name
| string | The username from directory service. |
domain id
| GUID | The containing directory service domain. |
groups
| complex | A list of directory service groups for this user. |
Example 18.2. An XML representation of a user in the users sub-collection
<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users/
d3b4e7be-5f57-4dac-b937-21e1771a501f">
<name>RHEV-M Admin</name>
<user_name>rhevmadmin@domain.example.com</user_name>
<domain id="77696e32-6b38-7268-6576-2e656e676c61"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
<groups>
<group>
<name>domain.example.com/Users/Enterprise Admins</name>
</group>
<group>
<name>domain.example.com/Users/Domain Admins</name>
</group>
...
</groups>
</user>
The
groups sub-collection contains all groups in the directory service. A domain group resource contains a set of elements.
Table 18.3. Domain group elements
| Element | Type | Description |
|---|---|---|
name
| string | The name of the group. |
domain id
| GUID | The containing directory service domain. |
Example 18.3. An XML representation of a group in the groups sub-collection
<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups/
85bf8d97-273c-4a5c-b801-b17d58330dab">
<name>example.com/Users/Enterprise Admins</name>
<domain id="77696e32-6b38-7268-6576-2e656e676c61"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
</group>
The
rel="roles" link obtained from the entry point URI (see Chapter 5, Entry Point) provides access to a static set of system roles. Each individual role element contains the following:
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 19.1. Role elements
| Element | Type | Description | Properties |
|---|---|---|---|
link="permits"
| relationship |
A link to the permits sub-collection for role permits.
|
|
mutable
| Boolean: true or false |
Defines the ability to update or delete the role. Roles with mutable set to false are roles built into the Red Hat Enterprise Virtualization environment.
|
|
administrative
| Boolean: true or false | Defines the role as administrative-only. |
Example 19.1. An XML representation of the roles collection
<roles>
<role id="00000000-0000-0000-0000-000000000001"
href="/api/roles/00000000-0000-0000-0000-000000000001">
<name>SuperUser</name>
<description>Roles management administrator</description>
<link rel="permits"
href="/api/roles/00000000-0000-0000-0000-000000000001/permits"/>
<mutable>false</mutable>
<administrative>true</administrative>
</role>
<role id="00000000-0000-0000-0001-000000000001"
href="/api/roles/00000000-0000-0000-0001-000000000001">
<name>RHEVMUser</name>
<description>RHEVM user</description>
<link rel="permits"
href="/api/roles/00000000-0000-0000-0001-000000000001/permits"/>
<mutable>false</mutable>
<administrative>false</administrative>
</role>
<role id="00000000-0000-0000-0001-000000000002"
href="/api/roles/00000000-0000-0000-0001-000000000002">
<name>RHEVMPowerUser</name>
<description>RHEVM power user</description>
<link rel="permits"
href="/api/roles/00000000-0000-0000-0001-000000000002/permits"/>
<mutable>false</mutable>
<administrative>false</administrative>
</role>
</roles>
Creation of a role requires values for
name, administrative and a list of initial permits. See Section 8.2.4, “ Creating a Resource in a Collection ” for more information.
Example 19.2. Creating a role
POST /api/roles HTTP/1.1
Accept: application/xml
Content-type: application/xml
<role>
<name>Finance Role</name>
<administrative>true</administrative>
<permits>
<permit id="1"/>
</permits>
</role>
The
name, description and administrative elements are updatable post-creation. See Section 8.3.2, “ Updating a Resource ” for more information.
Example 19.3. Updating a role
PUT /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<role>
<name>Engineering Role</name>
<description>Standard users in the Engineering Role</description>
<administrative>false</administrative>
</role>
Removal of a role requires a
DELETE request.
Example 19.4. Removing a role
DELETE /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1 HTTP/1.1 204 No Content
Each role contains a set of allowable actions, or
permits, which the API lists in capabilities. For more information on access to permits, see Section 7.26, “Permits”.
A role's
permits are listed as a sub-collection:
Example 19.5. Listing a role's permits
GET /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<permits>
<permit id="1"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
<name>create_vm</name>
<administrative>false</administrative>
<role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
</permit>
...
</permits>
Assign a
permit to a role with a POST request to the permits sub-collection. Use either an id attribute or a name element to specify the permit to assign.
Example 19.6. Assign a permit to a role
POST /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<permit id="1"/>
HTTP/1.1 201 Created
Content-Type: application/xml
<permits>
<permit id="1"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
<name>create_vm</name>
<administrative>false</administrative>
<role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
</permit>
</permits>
Remove a
permit from a role with a DELETE request to the permit resource.
Example 19.7. Remove a permit from a role
DELETE /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1 HTTP/1.1 HTTP/1.1 204 No Content
The
groups collection contains imported groups from directory services. A group resource contains a set of elements.
Table 20.1. Imported group elements
| Element | Type | Description |
|---|---|---|
link rel="tags"
| relationship |
A link to the tags sub-collection for tags attached to this group.
|
link rel="permissions"
| relationship |
A link to the permissions sub-collection for permissions attached to this group.
|
link rel="roles"
| relationship |
A link to the roles sub-collection for roles attached to this group.
|
Example 20.1. An XML representation of a group resource
<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab">
<name>Everyone</name>
<link rel="tags"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/tags"/>
<link rel="permissions"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/permissions"/>
<link rel="roles"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/roles"/>
</group>
The API adds existing directory service groups to the Red Hat Enterprise Virtualization Manager database with a
POST request to the groups collection.
Example 20.2. Adding a group from directory service
POST /api/group HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<group>
<name>www.example.com/accounts/groups/mygroup</name>
</group>
Users are exposed in a top-level collection and are referenced with the
rel="users" link. Individual user elements contain the following:
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 21.1. User elements
| Element | Type | Description | Properties |
|---|---|---|---|
user_name
| string | The user principal name (UPN). The UPN is used as a more convenient identifier when adding a new user. |
|
link rel="tags"
| relationship |
A link to the tags sub-collection for user resources.
| |
link rel="roles"
| relationship |
A link to the roles sub-collection for user resources.
| |
name
| string | A free-text name for the user. |
|
domain
| string | The containing directory service domain. |
|
groups
| complex | A list of directory service groups for this user. |
|
Example 21.1. An XML representation of a user resource
GET /api/users HTTP/1.1
Accept: application/xml
<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
<name>RHEV-M Admin</name>
<actions/>
<link rel="roles"
href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
<link rel="tags"
href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/tags"/>
<domain>domain.example.com</domain>
<logged_in>false</logged_in>
<user_name>rhevmadmin@domain.example.com</user_name>
<groups>
<group>Group Policy Creator Owners@domain.example.com/Users</group>
<group>Domain Admins@domain.example.com/Users</group>
<group>Enterprise Admins@domain.example.com/Users</group>
<group>Schema Admins@domain.example.com/Users</group>
<group>Administrators@domain.example.com/Builtin</group>
</groups>
</user>
The API adds an existing directory service user to the Red Hat Enterprise Virtualization Manager database with a
POST request to the users collection. The client-provided new user representation includes an embedded roles list with at least one initial role to assign to the user. For example, the following request assigns two initial roles to the user joe@domain.example.com:
Example 21.2. Adding a user from directory service and assigning two roles
POST /api/users HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<user>
<user_name>joe@domain.example.com</user_name>
<roles>
<role>
<name>RHEVMPowerUser</name>
</role>
<role id="00000000-0000-0000-0001-000000000003"/>
</roles>
</user>
The new user is identified either by Red Hat Enterprise Virtualization Manager user ID or via the directory service user principal name (UPN). The user ID format reported from the directory service domain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as in LDIF [5] , the ID has the opposite byte order and is base-64 encoded. Hence it is usually more convenient to refer to the new user by UPN.
Note
The user exists in the directory service domain before it is added to the Red Hat Enterprise Virtualization Manager database. An API user has the option to query this domain through the
domains collection prior to creation of the user.
Roles are identified either by name or ID. The example above shows both approaches.
Further roles are attached or detached with
POST or DELETE requests to the roles sub-collection of an individual user. The example below illustrates how the API adds the RHEVMVDIUser role to the role assignments for a particular user.
Note
The embedded user roles list of the
user element is only used for the initial creation. All interactions post-creation with the user's role assignments go through the roles sub-collection.
Example 21.3. Adding roles to a user
POST /api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<role>
<name>RHEVMVDIUser</name>
</role>
Note
Users are not updated with the
PUT verb. The only changes allowed post-creation are in the user's role assignments.
The API removes users from the Red Hat Enterprise Virtualization Manager database with a
DELETE request on the users collection. The directory service domain remains unchanged after such a deletion.
The
tags collection provides information about tags in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="tags" link obtained from the entry point URI (see Chapter 5, Entry Point).
The following table shows specific elements contained in a tag resource representation.
Note
The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Table 22.1. Tag elements
| Element | Type | Description | Properties |
|---|---|---|---|
host
| GUID | A reference to the host which the tag is attached. See Chapter 13, Hosts. |
|
user
| GUID | A reference to the user which the tag is attached. See Chapter 21, Users. |
|
vm
| GUID | A reference to the VM which the tag is attached. See Chapter 14, Virtual Machines. |
|
parent
| complex | A reference to the VM which the tag is attached. |
Example 22.1. An XML representation of a tag resource
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
<name>Finance</name>
<description>Resources for the Finance department</description>
<parent>
<tag id="-1" href="/api/tags/-1"/>
</parent>
</tag>
Creation of a new tag requires the
name element. The name, description and parent elements are updatable post-creation.
The collection referenced by
link rel="tags" from a host, user or vms represents the set of tags associated with the entity.
The
tag representations are as described in Chapter 22, Tags, except they also contain a host id, user id or vm id reference to the entity in question.
Each tags collection is manipulated as described in Chapter 8, Common Features. Associating a tag with an entity is achieved by
POSTing a tag reference (identifying the tag either by its id or name) to the collection.
Example 22.2. Associating a tag with a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<name>Finance</name>
</tag>
HTTP/1.1 201 Created
Content-Type: application/xml
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
<name>Finance</name>
<description>Resources for the Finance department</description>
<vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>
Removing an association is achieved with a
DELETE request to the appropriate element in the collection.
Example 22.3. Removing a tag from a virtual machine
DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1 HTTP/1.1 204 No Content
To query the set of entities associated with a given tag, the
collection/search URI template for the appropriate collection should be used to search for entities matching tag=MyTag.
Example 22.4. Querying a collection for tagged resources
GET /api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<vms>
<vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
...
</vm>
...
</vms>
An API user assigns a
parent element to a tag to create a hierarchical link to a parent tag. The tags are presented as a flat collection, which descends from the root tag, with tag representations containing a link element to a parent tag
Note
The
root tag is a special pseudo-tag assumed as the default parent tag if no parent tag is specified. The root tag cannot be deleted nor assigned a parent tag.
This tag hierarchy is expressed in the following way:
Example 22.5. Tag Hierarchy
<tags>
<tag id="-1" href="/api/tags/-1">
<name>root</name>
<description>root</description>
<parent>
<tag id="-1" href="/api/tags/-1"/>
</parent>
</tag>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
<name>Finance</name>
<description>Resources for the Finance department</description>
<parent>
<tag id="-1" href="/api/tags/-1"/>
</parent>
</tag>
<tag id="ac18dabf-23e5-12be-a383-a38b165ca7bd"
href="/api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd">
<name>Billing</name>
<description>Billing Resources</description>
<parent>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
</parent>
</tag>
</tags>
In this XML representation, the tags follow this hierarchy:
root (id: -1)
- Finance (id: f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e)
- Billing (id: ac18dabf-23e5-12be-a383-a38b165ca7bd)
POSTing a new tag with a parent element creates an association with a parent tag, using either the id attribute or the name element to reference the parent tag
Example 22.6. Setting an association with a parent tag with the id attribute
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<tag>
<name>Billing</name>
<description>Billing Resources</description>
<parent>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
</parent>
</tag>
Example 22.7. Setting an association with a parent tag with the name element
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<tag>
<name>Billing</name>
<description>Billing Resources</description>
<parent>
<tag>
<name>Finance</name>
</tag>
</parent>
</tag>
A tag changes a parent using a
PUT request:
Example 22.8. Changing the parent tag
PUT /api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<parent>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
</parent>
</tag>
The
rel="events" link obtained from the entry point URI accesses the events collection and lists system events from Red Hat Enterprise Virtualization Manager.
Table 23.1. Event elements
| Element | Type | Description |
|---|---|---|
description
| string | A description of the system event |
code
| integer | The integer event code. See Appendix D, Event Codes for a full list of event codes with descriptions. |
severity
|
One of normal, warning, error or alert
| The level of severity for the event. |
time
|
xsd:dateTime format: YYYY-MM-DDThh:mm:ss
| The timestamp indicating when the event happened. |
user id
| GUID | The identification code for the user who triggered the event. |
Example 23.1. An XML representation of the events collection
<events>
<event id="537" href="/api/events/537">
<description>User vdcadmin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-01-12T10:48:27.827+02:00</time>
<user id="9b9002d1-ec33-4083-8a7b-31f6b8931648"
href="/api/users/9b9002d1-ec33-4083-8a7b-31f6b8931648"/>
</event>
...
</events>
In addition to
user, an event representation also contains a set of XML element relationships to resources relevant to the event.
Example 23.2. An XML representation of a virtual machine creation event
<event id="635" href="/api/events/635">
<description>VM bar was created by rhevadmin.</description>
<code>34</code>
<severity>normal</severity>
<time>2011-07-11T16:32:03.172+02:00</time>
<user id="4621b611-43eb-4d2b-ae5f-1180850268c4"
href="/api/users/4621b611-43eb-4d2b-ae5f-1180850268c4"/>
<vm id="9b22d423-e16b-4dd8-9c06-c8e9358fbc66"
href="/api/vms/9b22d423-e16b-4dd8-9c06-c8e9358fbc66"/>
<storage_domain id="a8a0e93d-c570-45ab-9cd6-3c68ab31221f"
href="/api/storagedomains/a8a0e93d-c570-45ab-9cd6-3c68ab31221f"/>
</event>
This example representation provides XML element relationships to a virtual machine resource and a storage domain resource.
Note
The
events collection is read-only.
The
events collection provides search queries similar to other resource collections (See Section 8.2.3, “ Searching Collections with Queries ”). An additional feature when searching the events collection is the ability to search from a certain event. This queries all of events since a specified event.
Querying from an event requires an additional
from parameter added before the search query. This from argument references an event id code.
Example 23.3. Searching from an event
GET /api/events;from=1012?search=type%3D30 HTTP/1.1 Accept: application/xml
This displays all events with
type set to 30 since id="1012"
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
<event id="1018" href="/api/events/1018">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-07-11T14:03:22.485+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
<event id="1016" href="/api/events/1016">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-07-11T14:03:07.236+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
<event id="1014" href="/api/events/1014">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-07-11T14:02:16.009+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
</events>
Important
The
from argument previously used the following format:
/api/events?search=type%3D30&from=1012
This format is now depreciated.
A virtualization environment generates a large amount of events after a period of time. However, the API only displays a default number of events for one search query. To display more than the default, the API separates results into pages with the
page command in a search query.
The following search query tells the API to paginate results using a
page value in combination with the sortby clause:
sortby time asc page 1
The
sortby clause defines the base element to order of the results and whether the results are ascending or descending. For search queries of events, set the base element to time and the order to ascending (asc) so the API displays all events from the creation of your virtualization environment.
The
page condition defines the page number. One page equals the default number of events to list. Pagination begins at page 1. To view more pages, increase the page value:
sortby time asc page 2
sortby time asc page 3
sortby time asc page 4
Example 23.4. Paginating events
This example paginates
event resources. The URL-encoded request is:
GET /api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1 Accept: application/xml
Increase the
page value to view the next page of results.
GET /api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1 Accept: application/xml
Use an additional
from argument to set the starting id.
GET /api/events?search=sortby%20time%20asc%20page%202&from=30 HTTP/1.1 Accept: application/xml
Table of Contents
- 24. Software Development Kit Overview
- 25. Using the Software Development Kit
- 25.1. Connecting to the API using Python
- 25.2. Resources and Collections
- 25.3. Retrieving Resources from a Collection
- 25.4. Retrieving a Specific Resource from a Collection
- 25.5. Retrieving a List of Resources from a Collection
- 25.6. Adding a Resource to a Collection
- 25.7. Updating a Resource in a Collection
- 25.8. Removing a Resource from a Collection
- 25.9. Handling Errors
- 26. Python Reference Documentation
The software development kit provides programming language specific libraries for interacting with the REST API provided by Red Hat Enterprise Virtualization Manager. These libraries include classes to represent resources made available by the API and methods for interacting with them. This allows you to concentrate on writing code specific to what they you are trying to achieve rather than on hand crafting appropriately formatted HTTP requests and manually orchestrating their delivery.
The software development kit includes collections and methods mapping directly to all aspects of the REST API. As a result this software development kit documentation focuses on providing examples written in the supported programming language. For a complete reference of all collections, resources, actions, and attributes supported refer to the REST API material.
To install the software development kit you must have:
- A system with Red Hat Enterprise Linux 6.3, or later, installed. Both the Server and Workstation variants are supported.
- A subscription to Red Hat Hat Enterprise Virtualization entitlements.
When you install the rhevm-sdk package the Python 2.6 interpreter will be installed if it does not already exist on the system.
Important
To run scripts which make use of the libraries provided by the software development kit the rhevm-sdk must be installed. As a result the prerequisites listed here must be met both on the systems being used to develop scripts using the software development kit and on those systems on which the scripts are intended to run.
Summary
The software development kit is provided by the rhevm-sdk. The package includes all of the Python bindings for the Red Hat Enterprise Virtualization Manager Application Programming Interface (API). To begin using the software development kit you must install the rhevm-sdk package on the system that you wish to use for your script development. The instructions that appear here are intended for use on a system running Red Hat Enterprise Linux 6.3 or later.
Procedure 24.1. Installing the Python SDK
- Ensure that your system has the required entitlements:
- When using certificate-based Red Hat Network you must subscribe to the
Red Hat Enterprise Virtualizationentitlement to install the rhevm-sdk package. - When using Red Hat Network classic you must ensure subscribe to the
Red Hat Enterprise Virtualization Manager (v.3.1 x86_64)channel to install the rhevm-sdk package. This software channel is also referred to asrhel-x86_64-server-6-rhevm-3.1.
- Ensure that you are logged in as the
rootuser. - Install the rhevm-sdk package using the
yumcommand.# yum install rhevm-sdk
Result
The rhevm-sdk package is now installed. The ovirtsdk Python library is now available for use on the local system.
- 25.1. Connecting to the API using Python
- 25.2. Resources and Collections
- 25.3. Retrieving Resources from a Collection
- 25.4. Retrieving a Specific Resource from a Collection
- 25.5. Retrieving a List of Resources from a Collection
- 25.6. Adding a Resource to a Collection
- 25.7. Updating a Resource in a Collection
- 25.8. Removing a Resource from a Collection
- 25.9. Handling Errors
To connect to the REST API using Python you must create an instance of the
API class from the ovirtsdk.api module. To be able to do this it is necessary to first import the class at the start of the script:
from ovirtsdk.api import API
The constuctor of the
API class takes a number of arguments. Supported arguments are:
- url
- Specifies the URL of the Manager to connect to, including the
/apipath. This parameter is mandatory. - username
- Specifies the user name to connect using, in User Principle Name (UPN) format. This parameter is mandatory.
- password
- Specifies the password for the user name provided by the
usernameparameter. This parameter is mandatory. - key_file
- Specifies a PEM formatted key file containing the private key associated with the certificate specified by
cert_file. This parameter is optional. - cert_file
- Specifies a PEM formatted client certificate to be used for establishing the identity of the client on the server. This parameter is optional.
- ca_file
- Specifies the certificate file of the certificate authority for the server. This parameter is mandatory unless the
insecureparameter is set toTrue. - port
- Specifies the port to connect using, where it has not been provided as component of the
urlparameter. This parameter is optional. - timeout
- Specifies the amount of time in seconds that is allowed to pass before a request is to be considered as having timed out. This parameter is optional.
- persistent_auth
- Specifies whether persistent authentication is enabled for this connection. Valid values are
TrueandFalse. This parameter is optional. - insecure
- Specifies whether or not the connection needs to be secured. Valid values are
TrueandFalse. If theinsecureparameter is set toFalse- which is the default - then theca_file,key_file, andcert_filemust be supplied to secure the connection. - filter
- Specifies whether or not user permission based filter is on or off. Valid values are
TrueandFalse. If thefilterparameter is set toFalse- which is the default - then the authentication credentials provided must be those of an administrative user. If thefilterparameter is set toTruethen any user can be used and the Manager will filter the actions available to the user based on their permissions. - debug
- Specifies whether debug mode is enabled for this connection. Valid values are
TrueandFalse. This parameter is optional.
This example script creates an instance of the
API class, checks that the connection is working using the test() method, and disconnects using the disconnect() method.
from ovirtsdk.api import API api_instance = API ( url="https://rhevm31.demo.redhat.com", username="admin@internal", password="Redhat123" ca_file="/etc/pki/ovirt-engine/ca.pem") print "Connected successfully!" api_instance.disconnect()
For a full list of methods supported by the
API class refer to the PyDoc output for the ovirtsdk.api package.
The RESTful nature of the API is evident throughout the Python bindings for both philosophical and practical reasons. All RESTful APIs have two key concepts that you need to be aware of:
- Collections
- A collection is a set of resources of the same type. The API provides both top level collections and sub-collections. An example of a top level collection is the
hostscollection which contains all virtualization hosts in the environment. An example of a sub-collection is thehost.nicscollection which contains resources for all network interface cards attached to a host resource.The interface for interacting with collections provides methods for adding resources (add), getting resources (get), and listing resources (list). - Resources
- A resource in a RESTful API is an object with a fixed interface that also contains a set of attributes that are relevant to the specific type of resource being represented. The interface for interacting with resources provides methods for updating (
update) and deleting (delete) resources. Additionally some resources support actions specific to the resource type. An example is theapprovemethod ofHostresources.
Resources are retrieved from a collection using the
get and list methods.
- get
- Retrieves a single resource from the collection. The item to retrieve is determined based on the name provided as an argument. The
getmethod takes these arguments:name- The name of the resource to retrieve from the collection.
- list
- Retrieves any number of resources from the collection. The items to retrieve are determined based on the criteria provided. The
listmethod takes these arguments:**kwargs- A dictionary of additional arguments allowing keyword based filtering.query- A query written in the same format as that used for searches executed using the Red Hat Enterprise Virtualization user interfaces.max- The maximum number of resources to retrieve.case_sensitive- Whether or not search terms are to be treated as case sensitive (TrueorFalse, the default isTrue).
In these examples a specific resource is retrieved from a collection using the
get method.
Example 25.1. Retrieving a Specific Resource by Name
Retrieving the
Default data center from the datacenters collection using the name parameter of the get method:
dc = api.datacenters.get("Default")
This syntax is equivalent:
dc = api.datacenters.get(name="Default")
In these examples a list of resources is retrieved from a collection using the
list method.
Example 25.2. Retrieving a List of all Resources in a Collection
Retrieving a list of all resources in the
datacenters collection. The query parameter of the list method allows the use of engine based queries. In this way the SDK supports the use of queries in the same format as those executed in the Administration and User Portals. The query parameter is also the mechanism for providing pagination arguments while iterating through the collection.
dc_list = [] dc_page_index = 1 dc_page_current = api.datacenters.list(query="page %s" % dc_page_index) while(len(dc_page_current) != 0): dc_list = dc_list + dc_page_current dc_page_index = dc_page_index + 1 dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
In this example the list of resources contained in the
datacenters collection is ultimately stored in the locally defined dc_list list variable.
Warning
The
list method of a collection is restricted to returning only as many elements as allowed by the SearchResultsLimit Red Hat Enterprise Virtualization Manager configuration key.
To ensure that all records in a the
list are returned it is recommended that you paginate through the results as illustrated in this example.
Alternatively you may choose to set the
max parameter of the list method to the maximum number of records that you wish to retrieve.
Example 25.3. Retrieving a List of Resources in a Collection Matching a Keyword Based Filter
Retrieving a list of all resources in the
datacenters collection that have a storage type of nfs. In this example both the query parameter and **kwargs parameter are supplied. The query is used for pagination in the same way as illustrated in the previous example. The **kwargs parameter is used to filter based on the storage type of the data center.
dc_list = [] dc_page_index = 1 dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"}) while(len(dc_page_current) != 0): dc_list = dc_list + dc_page_current dc_page_index = dc_page_index + 1 dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
In this example the list of resources contained in the
datacenters collection with a storage type of nfs is ultimately stored in the locally defined dc_list list variable.
The
add method of a collection adds a resource. The resource to be added is created based on the parameters provided. Parameters are provided to the add method using an instance of an object from the ovirtsdk.xml.params module. Which specific class from the module needs to be used varies based on the type of resource being created.
Example 25.4. Adding a Resource to a Collection
In this example a virtual machine resource is created.
vm_params = params.VM(name="DemoVM", cluster=api.clusters.get("Default"), template=api.templates.get("Blank"), memory=536870912) vm = api.vms.add(vm_params)
While the virtual machine created by this example is not yet ready to run it illustrates the process for creating any Red Hat Enterprise Virtualization resource:
- Create an instance of the parameter object for the type of resource being created.
- Identify the collection to which the resource will be added.
- Call the
addmethod of the collection passing the parameter object as a parameter.
Some parameter objects also have complex parameters of their own.
Example 25.5. Complex Parameters
In this example an NFS data center running in full version 3.1 compatibility mode is being created. To do this it is necessary to first construct a
ovirtsdk.xml.params.Version object. Then this is used as a parameter when creating an instance of a ovirtsdk.xml.params.DataCenter object containing parameters of the data center to be created. The resource is then created using the add method of the datacenters collection.
v_params = params.Version(major=3, minor=1) dc_params = params.DataCenter(name="DemoDataCenter", storage_type="NFS", version=v_params) dc = api.datacenters.add(dc_params)
To update a resource you must retrieve it from the collection it resides in, modify the desired parameters, and then call the
update method for the resource to save the changes. Parameter modification is performed by using the set_* methods of the retrieved resource.
Example 25.6. Updating a Resource
In this example the data center named
DemoDataCenter has its description updated.
dc = api.datacenters.get("DemoDataCenter") dc.set_description("This data center description provided using the Python SDK") dc.update()
To remove a resource you must retrieve it from the collection that contains it and call the
delete method of the resource.
Example 25.7. Removing a Resource from a Collection
Deleting a virtual machine named
DemoVM from the vms collection:
vm = api.vms.get("DemoVM") vm.delete()
Where errors are encountered the Software Development Kit uses exceptions to highlight them. The Software Development Kit defines exception types in addition to those defined by the Python interpreter itself. These exceptions are located in the
ovirtsdk.infrastructure.errors module:
ConnectionErrorDisconnectedErrorImmutableErrorNoCertificatesErrorRequestErrorUnsecuredConnectionAttemptError
These exceptions can be caught and handled like any other Python exception:
Example 25.8. Catching a ConnectionError Exception
from ovirtsdk.api import API from ovirtsdk.xml import params try: api = API(url="https://HOST", user="USER, pass="PASS, ca_file="/etc/pki/ovirt-engine/ca.pem") except ConnectionError err: print "Connection failed: %s" % err
Documentation generated using pydoc is available for these modules provided by the rhevm-sdk package:
If instead you wish to view the
pydoc generated documentation on your local machine provide the name of the module you are interested in as an argument to the pydoc command:
$ pydoc MODULE
This appendix provides instructions on adapting REST requests for use with cURL. cURL is a command line tool for transfering data across various protocols, including HTTP, and supports multiple platforms such as Linux, Windows, Mac OS and Solaris. Most Linux distributions include cURL as a package.
Installing cURL
A Red Hat Enterprise Linux user installs cURL with the following terminal command:
yum install curl
For other platforms, seek installation instructions on the cURL website (http://curl.haxx.se/).
Using cURL
cURL uses a command line interface to send requests to a HTTP server. Integrating a request requires the following command syntax:
Usage: curl [options] uri
The
uri refers to target HTTP address to send the request. This is a location on your Red Hat Enterprise Virtualization Manager host within the API entry point path (/api).
cURL options
- -X
COMMAND, --requestCOMMAND - The request command to use. In the context of the REST API, use
GET,POST,PUTorDELETE.Example:-X GET - -H
LINE, --headerLINE - HTTP header to include with the request. Use multiple header options if more than one header is required.Example:
-H "Accept: application/xml" -H "Content-Type: application/xml" - -u
USERNAME:PASSWORD, --userUSERNAME:PASSWORD - The username and password of the Red Hat Enterprise Virtualization user. This attribute acts as a convenient replacement for the
Authorization:header.Example:-u admin@internal:p@55w0rd! - --cacert
CERTIFICATE - The location of the certificate file for SSL communication to the REST API. The certificate file is saved locally on the client machine. Use the
-kattribute to bypass SSL. See Chapter 2, Authentication and Security for more information on obtaining a certificate.Example:--cacert ~/Certificates/rhevm.cer - -d
BODY, --dataBODY - The body to send for requests. Use with
POST,PUTandDELETErequests. Ensure to specify theContent-Type: application/xmlheader if a body exists in the request.Example:-d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>"
Examples
The following examples show how to adapt REST requests to cURL command syntax:
Example A.1. GET request
The following
GET request lists the virtual machines in the vms collection. Note that a GET request does not contain a body.
GET /api/vms HTTP/1.1 Accept: application/xml
Adapt the method (
GET), header (Accept: application/xml) and URI (https://[RHEVM-Host]:8443/api/vms) into the following cURL command:
$ curl -X GET -H "Accept: application/xml" -u[USER:PASS]--cacert[CERT]https://[RHEVM-Host]:8443/api/vms
An XML representation of the
vms collection displays.
Example A.2. POST request
The following
POST request creates a virtual machine in the vms collection. Note that a POST request requires a body.
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm1</name>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot dev="hd"/>
</os>
</vm>
Adapt the method (
POST), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:8443/api/vms) and request body into the following cURL command:
$ curl -X POST -H "Accept: application/xml" -H "Content-type: application/xml" -u[USER:PASS]--cacert[CERT]-d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os></vm>" https://[RHEVM-Host]:8443/api/vms
The REST API creates a new virtual machine and displays an XML representation of the resource.
Example A.3. PUT request
The following
PUT request updates the memory of a virtual machine resource. Note that a PUT request requires a body.
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<memory>1073741824</memory>
</vm>
Adapt the method (
PUT), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) and request body into the following cURL command:
$ curl -X PUT -H "Accept: application/xml" -H "Content-type: application/xml" -u[USER:PASS]--cacert[CERT]-d "<vm><memory>1073741824</memory></vm>" https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API updates the virtual machine with a new memory configuration.
Example A.4. DELETE request
The following
DELETE request removes a virtual machine resource.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Adapt the method (
DELETE) and URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) into the following cURL command:
$ curl -X DELETE -u[USER:PASS]--cacert[CERT]https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API removes the virtual machine. Note the
Accept: application/xml request header is optional due to the empty result of DELETE requests.
Example A.5. DELETE request with body
The following
DELETE request force removes a virtual machine resource as indicated with the optional body.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <force>true</force> </action>
Adapt the method (
DELETE), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:8443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) and request body into the following cURL command:
$ curl -X DELETE -H "Accept: application/xml" -H "Content-type: application/xml" -u[USER:PASS]--cacert[CERT]-d "<action><force>true</force></action>" https://[RHEVM-Host]:8443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API force removes the virtual machine.
cURL Library (libcurl)
In addition the the standard command line tools, cURL also features libcurl, a library for programming language integration. For more information on supported programming languages and integration methods, see the libcurl website (http://curl.haxx.se/libcurl/).
The following appendix provides examples for importing certificates for clients.
Network Security Services (NSS) is an set of open-source cryptography libraries that support SSL. Several Linux tools, such as cURL, use NSS to verify trusted SSL communication. This process helps a user import the
rhevm.cer certificate from Section 2.1, “TLS/SSL Certification” into the local NSS Database.
For an individual user, import the
rhevm.cer certificate using the following command:
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "Red Hat Enterprise Virtualization Manager" -i rhevm.cer
For all users on a system, import the
rhevm.cer certificate as root using the following command:
# certutil -d sql:/etc/pki/nssdb -A -t TC -n "Red Hat Enterprise Virtualization Manager" -i rhevm.cer
This appendix demonstrates how to import the X.509 certificate exported from the Red Hat Enterprise Virtualization server (See Section 2.1, “TLS/SSL Certification” for information on certificate exports) into a new Java keystore file.
Procedure B.1. Import a certificate into a new Java keystore
This process helps a user import the
rhevm.cer certificate from Section 2.1, “TLS/SSL Certification” into a Java keystore. This procedure requires the keytool management utility from the Java Development Kit (JDK) available for Linux and Windows systems.
- Access your client machine and locate the
rhevm.cercertificate. - Import the
rhevm.cercertificate using the Java keytool management utility.keytool -importcert -v -trustcacerts -keystore restapi.jks -noprompt -alias rhevm -file rhevm.cer
The keytool utility creates a new keystore file namedrestapi.jks. - keytool asks for the keystore password. Enter a password and keytool asks to verify it.
- keytool adds the
rhevm.cercertificate to therestapi.jkskeystore. Use keytool -list command to view the certificate's entry in the keystore:keytool -list -keystore restapi.jks -storepass [password]
Important
Some versions of keytool parse the certificate incorrectly. If keytool does not recognise the certificate, convert it to a different X.509 format with the openssl tool:
openssl x509 -in rhevm.cer -out rhevm.new -outform [pem|der]This creates a file called
rhevm.new to use in place of rhevm.cer.
The API uses Red Hat Enterprise Virtualization Query Language to perform search queries. For more information on the Queyr Language, read the full specification in Appendix F.1. Search of the Red Hat Enterprise Virtualization Administration Guide 3.1.
Please note that certain enumerated values in the API require a different search query when using the Query Language. The following table provides a translation for these key enumerated values.
Table C.1. Enumerated value translations
|
Resource Type
|
API Enumerable Type
|
API Enumerable Value
|
Query Language Property
|
Query Language Value
|
|---|---|---|---|---|
|
Data Centers
|
data_center_states
|
not_operational
|
status
|
notoperational
|
|
Network
|
network_states
|
non_operational
|
status
|
nonoperational
|
|
Hosts
|
host_states
|
non_responsive
|
status
|
nonresponsive
|
install_failed
|
installfailed
| |||
preparing_for_maintenance
|
preparingformaintenance
| |||
non_operational
|
nonoperational
| |||
pending_approval
|
pendingapproval
| |||
|
Virtual Machines
|
vm_states
|
powering_up
|
status
|
poweringup
|
powered_down
|
powereddown
| |||
migrating
|
migratingfrom
| |||
migrating
|
migratingto
| |||
not_responding
|
notresponding
| |||
wait_for_launch
|
waitforlaunch
| |||
reboot_in_progress
|
rebootinprogress
| |||
saving_state
|
savingstate
| |||
restoring_state
|
restoringstate
| |||
image_locked
|
imagelocked
| |||
powering_down
|
poweringdown
| |||
os_types
|
windows_xp
|
os
|
windowsxp
| |
windows_2003
|
windows2003
| |||
windows_2008
|
windows2008
| |||
other_linux
|
otherlinux
| |||
rhel_5
|
rhel5
| |||
rhel_4
|
rhel4
| |||
rhel_3
|
rhel3
| |||
windows_7
|
windows7
| |||
windows_7x64
|
windows7x64
| |||
rhel_5x64
|
rhel5x64
| |||
rhel_4x64
|
rhel4x64
| |||
rhel_3x64
|
rhel3x64
| |||
windows_2008x64
|
windows2008x64
| |||
windows_2008r2
|
windows2008r2x64
| |||
rhel_6
|
rhel6
| |||
rhel_6x64
|
rhel6x64
|
This table lists all event codes for Chapter 23, Events.
Table D.1. Event codes
| Code | Description |
|---|---|
0
|
UNASSIGNED
|
1
|
VDC_START
|
2
|
VDC_STOP
|
12
|
HOST_FAILURE
|
13
|
HOST_DETECTED
|
14
|
HOST_RECOVER
|
15
|
HOST_MAINTENANCE
|
16
|
HOST_ACTIVATE
|
17
|
HOST_MAINTENANCE_FAILED
|
18
|
HOST_ACTIVATE_FAILED
|
19
|
HOST_RECOVER_FAILED
|
20
|
USER_HOST_START
|
21
|
USER_HOST_STOP
|
22
|
IRS_FAILURE
|
26
|
IRS_DISK_SPACE_LOW
|
30
|
USER_VDC_LOGIN
|
31
|
USER_VDC_LOGOUT
|
32
|
USER_RUN_VM
|
33
|
USER_STOP_VM
|
34
|
USER_ADD_VM
|
35
|
USER_UPDATE_VM
|
36
|
USER_REMOVE_VM
|
37
|
USER_ADD_VM_STARTED
|
38
|
USER_CHANGE_DISK_VM
|
39
|
USER_PAUSE_VM
|
40
|
USER_RESUME_VM
|
41
|
USER_HOST_RESTART
|
42
|
USER_ADD_HOST
|
43
|
USER_UPDATE_HOST
|
44
|
USER_REMOVE_HOST
|
45
|
USER_CREATE_SNAPSHOT
|
46
|
USER_TRY_BACK_TO_SNAPSHOT
|
47
|
USER_RESTORE_FROM_SNAPSHOT
|
48
|
USER_ADD_VM_TEMPLATE
|
49
|
USER_UPDATE_VM_TEMPLATE
|
50
|
USER_REMOVE_VM_TEMPLATE
|
51
|
USER_ADD_VM_TEMPLATE_FINISHED_SUCCESS
|
52
|
USER_ADD_VM_TEMPLATE_FINISHED_FAILURE
|
53
|
USER_ADD_VM_FINISHED_SUCCESS
|
54
|
USER_FAILED_RUN_VM
|
55
|
USER_FAILED_PAUSE_VM
|
56
|
USER_FAILED_STOP_VM
|
57
|
USER_FAILED_ADD_VM
|
58
|
USER_FAILED_UPDATE_VM
|
59
|
USER_FAILED_REMOVE_VM
|
60
|
USER_ADD_VM_FINISHED_FAILURE
|
61
|
VM_DOWN
|
62
|
VM_MIGRATION_START
|
63
|
VM_MIGRATION_DONE
|
64
|
VM_MIGRATION_ABORT
|
65
|
VM_MIGRATION_FAILED
|
66
|
VM_FAILURE
|
68
|
USER_CREATE_SNAPSHOT_FINISHED_SUCCESS
|
69
|
USER_CREATE_SNAPSHOT_FINISHED_FAILURE
|
70
|
USER_RUN_VM_AS_STATELESS_FINISHED_FAILURE
|
71
|
USER_TRY_BACK_TO_SNAPSHOT_FINISH_SUCCESS
|
72
|
USER_CHANGE_FLOPPY_VM
|
73
|
USER_INITIATED_SHUTDOWN_VM
|
74
|
USER_FAILED_SHUTDOWN_VM
|
75
|
USER_FAILED_CHANGE_FLOPPY_VM
|
76
|
USER_STOPPED_VM_INSTEAD_OF_SHUTDOWN
|
77
|
USER_FAILED_STOPPING_VM_INSTEAD_OF_SHUTDOWN
|
78
|
USER_ADD_DISK_TO_VM
|
79
|
USER_FAILED_ADD_DISK_TO_VM
|
80
|
USER_REMOVE_DISK_FROM_VM
|
81
|
USER_FAILED_REMOVE_DISK_FROM_VM
|
82
|
USER_MOVED_VM
|
83
|
USER_FAILED_MOVE_VM
|
84
|
USER_MOVED_TEMPLATE
|
85
|
USER_FAILED_MOVE_TEMPLATE
|
86
|
USER_COPIED_TEMPLATE
|
87
|
USER_FAILED_COPY_TEMPLATE
|
88
|
USER_UPDATE_VM_DISK
|
89
|
USER_FAILED_UPDATE_VM_DISK
|
90
|
USER_HOST_SHUTDOWN
|
91
|
USER_MOVED_VM_FINISHED_SUCCESS
|
92
|
USER_MOVED_VM_FINISHED_FAILURE
|
93
|
USER_MOVED_TEMPLATE_FINISHED_SUCCESS
|
94
|
USER_MOVED_TEMPLATE_FINISHED_FAILURE
|
95
|
USER_COPIED_TEMPLATE_FINISHED_SUCCESS
|
96
|
USER_COPIED_TEMPLATE_FINISHED_FAILURE
|
97
|
USER_ADD_DISK_TO_VM_FINISHED_SUCCESS
|
98
|
USER_ADD_DISK_TO_VM_FINISHED_FAILURE
|
99
|
USER_TRY_BACK_TO_SNAPSHOT_FINISH_FAILURE
|
100
|
USER_RESTORE_FROM_SNAPSHOT_FINISH_SUCCESS
|
101
|
USER_RESTORE_FROM_SNAPSHOT_FINISH_FAILURE
|
102
|
USER_FAILED_CHANGE_DISK_VM
|
103
|
USER_FAILED_RESUME_VM
|
104
|
USER_FAILED_ADD_HOST
|
105
|
USER_FAILED_UPDATE_HOST
|
106
|
USER_FAILED_REMOVE_HOST
|
107
|
USER_FAILED_HOST_RESTART
|
108
|
USER_FAILED_ADD_VM_TEMPLATE
|
109
|
USER_FAILED_UPDATE_VM_TEMPLATE
|
110
|
USER_FAILED_REMOVE_VM_TEMPLATE
|
111
|
USER_STOP_SUSPENDED_VM
|
112
|
USER_STOP_SUSPENDED_VM_FAILED
|
113
|
USER_REMOVE_VM_FINISHED
|
114
|
USER_VDC_LOGIN_FAILED
|
115
|
USER_FAILED_TRY_BACK_TO_SNAPSHOT
|
116
|
USER_FAILED_RESTORE_FROM_SNAPSHOT
|
117
|
USER_FAILED_CREATE_SNAPSHOT
|
118
|
USER_FAILED_HOST_START
|
119
|
VM_DOWN_ERROR
|
120
|
VM_MIGRATION_FAILED_FROM_TO
|
121
|
SYSTEM_HOST_RESTART
|
122
|
SYSTEM_FAILED_HOST_RESTART
|
123
|
HOST_SLOW_STORAGE_RESPONSE_TIME
|
124
|
VM_IMPORT
|
125
|
VM_IMPORT_FAILED
|
126
|
VM_NOT_RESPONDING
|
127
|
HOST_RUN_IN_NO_KVM_MODE
|
128
|
VM_MIGRATION_TRYING_RERUN
|
129
|
VM_CLEARED
|
130
|
USER_FAILED_HOST_SHUTDOWN
|
131
|
USER_EXPORT_VM
|
132
|
USER_EXPORT_VM_FAILED
|
133
|
USER_EXPORT_TEMPLATE
|
134
|
USER_EXPORT_TEMPLATE_FAILED
|
135
|
TEMPLATE_IMPORT
|
136
|
TEMPLATE_IMPORT_FAILED
|
137
|
USER_FAILED_HOST_STOP
|
138
|
VM_PAUSED_ENOSPC
|
139
|
VM_PAUSED_ERROR
|
140
|
VM_MIGRATION_FAILED_DURING_MOVE_TO_MAINTANANCE
|
141
|
HOST_VERSION_NOT_SUPPORTED_FOR_CLUSTER
|
142
|
VM_SET_TO_UNKNOWN_STATUS
|
143
|
VM_WAS_SET_DOWN_DUE_TO_HOST_REBOOT_OR_MANUAL_FENCE
|
144
|
VM_IMPORT_INFO
|
145
|
VM_BLK_VIRTIO_NO_CACHE
|
149
|
USER_ADD
|
150
|
USER_INITIATED_RUN_VM
|
151
|
USER_INITIATED_RUN_VM_FAILED
|
152
|
USER_RUN_VM_ON_NON_DEFAULT_HOST
|
153
|
USER_STARTED_VM
|
182
|
USER_FAILED_ATTACH_USER_TO_VM
|
201
|
IRS_DISK_SPACE_LOW_ERROR
|
204
|
IRS_HOSTED_ON_HOST
|
250
|
USER_UPDATE_VM_CLUSTER_DEFAULT_HOST_CLEARED
|
251
|
USER_REMOVE_VM_TEMPLATE_FINISHED
|
300
|
USER_ADD_VM_POOL
|
301
|
USER_ADD_VM_POOL_FAILED
|
302
|
USER_ADD_VM_POOL_WITH_VMS
|
303
|
USER_ADD_VM_POOL_WITH_VMS_FAILED
|
304
|
USER_REMOVE_VM_POOL
|
305
|
USER_REMOVE_VM_POOL_FAILED
|
306
|
USER_ADD_VM_TO_POOL
|
307
|
USER_ADD_VM_TO_POOL_FAILED
|
308
|
USER_REMOVE_VM_FROM_POOL
|
309
|
USER_REMOVE_VM_FROM_POOL_FAILED
|
310
|
USER_ATTACH_USER_TO_POOL
|
311
|
USER_ATTACH_USER_TO_POOL_FAILED
|
312
|
USER_DETACH_USER_FROM_POOL
|
313
|
USER_DETACH_USER_FROM_POOL_FAILED
|
314
|
USER_UPDATE_VM_POOL
|
315
|
USER_UPDATE_VM_POOL_FAILED
|
316
|
USER_ATTACH_USER_TO_VM_FROM_POOL
|
317
|
USER_ATTACH_USER_TO_VM_FROM_POOL_FAILED
|
318
|
USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_SUCCESS
|
319
|
USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_FAILURE
|
320
|
USER_ADD_VM_POOL_WITH_VMS_ADD_HOST_FAILED
|
325
|
USER_REMOVE_ADUSER
|
326
|
USER_FAILED_REMOVE_ADUSER
|
327
|
USER_FAILED_ADD_ADUSER
|
328
|
USER_ATTACH_USER_TO_TIME_LEASED_POOL
|
329
|
USER_ATTACH_USER_TO_TIME_LEASED_POOL_FAILED
|
330
|
USER_DETACH_USER_FROM_TIME_LEASED_POOL
|
331
|
USER_DETACH_USER_FROM_TIME_LEASED_POOL_FAILED
|
332
|
USER_ATTACH_AD_GROUP_TO_TIME_LEASED_POOL
|
333
|
USER_ATTACH_AD_GROUP_TO_TIME_LEASED_POOL_FAILED
|
334
|
USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL
|
335
|
USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL_FAILED
|
336
|
USER_UPDATE_USER_TO_TIME_LEASED_POOL
|
337
|
USER_UPDATE_USER_TO_TIME_LEASED_POOL_FAILED
|
338
|
USER_UPDATE_AD_GROUP_TO_TIME_LEASED_POOL
|
339
|
USER_UPDATE_AD_GROUP_TO_TIME_LEASED_POOL_FAILED
|
342
|
USER_MERGE_SNAPSHOT
|
343
|
USER_FAILED_MERGE_SNAPSHOT
|
344
|
USER_UPDATE_VM_POOL_WITH_VMS
|
345
|
USER_UPDATE_VM_POOL_WITH_VMS_FAILED
|
346
|
USER_PASSWORD_CHANGED
|
347
|
USER_PASSWORD_CHANGE_FAILED
|
348
|
USER_CLEAR_UNKNOWN_VMS
|
349
|
USER_FAILED_CLEAR_UNKNOWN_VMS
|
350
|
USER_ADD_BOOKMARK
|
351
|
USER_ADD_BOOKMARK_FAILED
|
352
|
USER_UPDATE_BOOKMARK
|
353
|
USER_UPDATE_BOOKMARK_FAILED
|
354
|
USER_REMOVE_BOOKMARK
|
355
|
USER_REMOVE_BOOKMARK_FAILED
|
356
|
USER_MERGE_SNAPSHOT_FINISHED_SUCCESS
|
357
|
USER_MERGE_SNAPSHOT_FINISHED_FAILURE
|
360
|
USER_DETACH_USER_FROM_VM
|
361
|
USER_FAILED_DETACH_USER_FROM_VM
|
400
|
USER_ATTACH_VM_TO_AD_GROUP
|
401
|
USER_ATTACH_VM_TO_AD_GROUP_FAILED
|
402
|
USER_DETACH_VM_TO_AD_GROUP
|
403
|
USER_DETACH_VM_TO_AD_GROUP_FAILED
|
404
|
USER_ATTACH_VM_POOL_TO_AD_GROUP
|
405
|
USER_ATTACH_VM_POOL_TO_AD_GROUP_FAILED
|
406
|
USER_DETACH_VM_POOL_TO_AD_GROUP
|
407
|
USER_DETACH_VM_POOL_TO_AD_GROUP_FAILED
|
408
|
USER_REMOVE_AD_GROUP
|
409
|
USER_REMOVE_AD_GROUP_FAILED
|
430
|
USER_UPDATE_TAG
|
431
|
USER_UPDATE_TAG_FAILED
|
432
|
USER_ADD_TAG
|
433
|
USER_ADD_TAG_FAILED
|
434
|
USER_REMOVE_TAG
|
435
|
USER_REMOVE_TAG_FAILED
|
436
|
USER_ATTACH_TAG_TO_USER
|
437
|
USER_ATTACH_TAG_TO_USER_FAILED
|
438
|
USER_ATTACH_TAG_TO_USER_GROUP
|
439
|
USER_ATTACH_TAG_TO_USER_GROUP_FAILED
|
440
|
USER_ATTACH_TAG_TO_VM
|
441
|
USER_ATTACH_TAG_TO_VM_FAILED
|
442
|
USER_ATTACH_TAG_TO_HOST
|
443
|
USER_ATTACH_TAG_TO_HOST_FAILED
|
444
|
USER_DETACH_HOST_FROM_TAG
|
445
|
USER_DETACH_HOST_FROM_TAG_FAILED
|
446
|
USER_DETACH_VM_FROM_TAG
|
447
|
USER_DETACH_VM_FROM_TAG_FAILED
|
448
|
USER_DETACH_USER_FROM_TAG
|
449
|
USER_DETACH_USER_FROM_TAG_FAILED
|
450
|
USER_DETACH_USER_GROUP_FROM_TAG
|
451
|
USER_DETACH_USER_GROUP_FROM_TAG_FAILED
|
452
|
USER_ATTACH_TAG_TO_USER_EXISTS
|
453
|
USER_ATTACH_TAG_TO_USER_GROUP_EXISTS
|
454
|
USER_ATTACH_TAG_TO_VM_EXISTS
|
455
|
USER_ATTACH_TAG_TO_HOST_EXISTS
|
456
|
USER_LOGGED_IN_VM
|
457
|
USER_LOGGED_OUT_VM
|
458
|
USER_LOCKED_VM
|
459
|
USER_UNLOCKED_VM
|
460
|
USER_DETACH_USER_FROM_TIME_LEASED_POOL_INTERNAL
|
461
|
USER_DETACH_USER_FROM_TIME_LEASED_POOL_FAILED_INTERNAL
|
462
|
USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL_INTERNAL
|
463
|
USER_DETACH_AD_GROUP_FROM_TIME_LEASED_POOL_FAILED_INTERNAL
|
467
|
UPDATE_TAGS_VM_DEFAULT_DISPLAY_TYPE
|
468
|
UPDATE_TAGS_VM_DEFAULT_DISPLAY_TYPE_FAILED
|
470
|
USER_ATTACH_VM_POOL_TO_AD_GROUP_INTERNAL
|
471
|
USER_ATTACH_VM_POOL_TO_AD_GROUP_FAILED_INTERNAL
|
472
|
USER_ATTACH_USER_TO_POOL_INTERNAL
|
473
|
USER_ATTACH_USER_TO_POOL_FAILED_INTERNAL
|
494
|
HOST_MANUAL_FENCE_STATUS
|
495
|
HOST_MANUAL_FENCE_STATUS_FAILED
|
496
|
HOST_FENCE_STATUS
|
497
|
HOST_FENCE_STATUS_FAILED
|
498
|
HOST_APPROVE
|
499
|
HOST_APPROVE_FAILED
|
500
|
HOST_FAILED_TO_RUN_VMS
|
501
|
USER_SUSPEND_VM
|
502
|
USER_FAILED_SUSPEND_VM
|
503
|
USER_SUSPEND_VM_OK
|
504
|
HOST_INSTALL
|
505
|
HOST_INSTALL_FAILED
|
506
|
HOST_INITIATED_RUN_VM
|
507
|
HOST_INITIATED_RUN_VM_FAILED
|
509
|
HOST_INSTALL_IN_PROGRESS
|
510
|
HOST_INSTALL_IN_PROGRESS_WARNING
|
511
|
HOST_INSTALL_IN_PROGRESS_ERROR
|
512
|
USER_SUSPEND_VM_FINISH_SUCCESS
|
513
|
HOST_RECOVER_FAILED_VMS_UNKNOWN
|
514
|
HOST_INITIALIZING
|
515
|
HOST_CPU_LOWER_THAN_CLUSTER
|
516
|
HOST_CPU_RETRIEVE_FAILED
|
517
|
HOST_SET_NONOPERATIONAL
|
518
|
HOST_SET_NONOPERATIONAL_FAILED
|
519
|
HOST_SET_NONOPERATIONAL_NETWORK
|
520
|
USER_ATTACH_USER_TO_VM
|
521
|
USER_SUSPEND_VM_FINISH_FAILURE
|
522
|
HOST_SET_NONOPERATIONAL_DOMAIN
|
523
|
HOST_SET_NONOPERATIONAL_DOMAIN_FAILED
|
524
|
AUTO_SUSPEND_VM
|
524
|
HOST_DOMAIN_DELAY_INTERVAL
|
525
|
AUTO_SUSPEND_VM_FINISH_SUCCESS
|
526
|
AUTO_SUSPEND_VM_FINISH_FAILURE
|
527
|
AUTO_FAILED_SUSPEND_VM
|
528
|
USER_EJECT_VM_DISK
|
529
|
USER_EJECT_VM_FLOPPY
|
530
|
HOST_MANUAL_FENCE_FAILED_CALL_FENCE_SPM
|
531
|
HOST_LOW_MEM
|
555
|
USER_MOVE_TAG
|
556
|
USER_MOVE_TAG_FAILED
|
600
|
USER_HOST_MAINTENANCE
|
601
|
CPU_FLAGS_NX_IS_MISSING
|
602
|
USER_HOST_MAINTENANCE_MIGRATION_FAILED
|
603
|
HOST_SET_NONOPERATIONAL_IFACE_DOWN
|
800
|
IMAGES_SYNCRONIZER_DESKTOP_NOT_EXIST_IN_VDC
|
801
|
IMAGES_SYNCRONIZER_TEMPLATE_NOT_EXIST_IMAGE_EXIST
|
802
|
IMAGES_SYNCRONIZER_SNAPSHOT_NOT_EXIST_IN_VDC
|
803
|
IMAGES_SYNCRONIZER_SNAPSHOTS_NOT_ATTACHED_TO_VM_IN_VDC
|
804
|
IMAGES_SYNCRONIZER_TEMPLATE_NOT_EXIST_IN_VDC
|
805
|
IMAGES_SYNCRONIZER_DESKTOP_NOT_EXIST_IN_IRS
|
806
|
IMAGES_SYNCRONIZER_SNAPSHOT_NOT_EXIST_IN_IRS
|
807
|
IMAGES_SYNCRONIZER_DESKTOP_WITHOUT_TEMPLATE_VDC
|
808
|
IMAGES_SYNCRONIZER_IMAGE_TEMPLATE_NOT_EXIST
|
809
|
USER_ADD_HOST_GROUP
|
810
|
USER_ADD_HOST_GROUP_FAILED
|
811
|
USER_UPDATE_HOST_GROUP
|
812
|
USER_UPDATE_HOST_GROUP_FAILED
|
813
|
USER_REMOVE_HOST_GROUP
|
814
|
USER_REMOVE_HOST_GROUP_FAILED
|
815
|
USER_VDC_LOGOUT_FAILED
|
816
|
MAC_POOL_EMPTY
|
817
|
CERTIFICATE_FILE_NOT_FOUND
|
818
|
RUN_VM_FAILED
|
819
|
HOST_REGISTER_ERROR_UPDATING_HOST
|
820
|
HOST_REGISTER_ERROR_UPDATING_HOST_ALL_TAKEN
|
821
|
HOST_REGISTER_HOST_IS_ACTIVE
|
822
|
HOST_REGISTER_ERROR_UPDATING_NAME
|
823
|
HOST_REGISTER_ERROR_UPDATING_NAMES_ALL_TAKEN
|
824
|
HOST_REGISTER_NAME_IS_ACTIVE
|
825
|
HOST_REGISTER_AUTO_APPROVE_PATTERN
|
826
|
HOST_REGISTER_FAILED
|
827
|
HOST_REGISTER_EXISTING_HOST_UPDATE_FAILED
|
828
|
HOST_REGISTER_SUCCEEDED
|
829
|
VM_MIGRATION_ON_CONNECT_CHECK_FAILED
|
830
|
VM_MIGRATION_ON_CONNECT_CHECK_SUCCEEDED
|
831
|
USER_DEDICATE_VM_TO_POWERCLIENT
|
832
|
USER_DEDICATE_VM_TO_POWERCLIENT_FAILED
|
833
|
MAC_ADDRESS_IS_IN_USE
|
835
|
SYSTEM_UPDATE_HOST_GROUP
|
836
|
SYSTEM_UPDATE_HOST_GROUP_FAILED
|
850
|
USER_ADD_PERMISSION
|
851
|
USER_ADD_PERMISSION_FAILED
|
852
|
USER_REMOVE_PERMISSION
|
853
|
USER_REMOVE_PERMISSION_FAILED
|
854
|
USER_ADD_ROLE
|
855
|
USER_ADD_ROLE_FAILED
|
856
|
USER_UPDATE_ROLE
|
857
|
USER_UPDATE_ROLE_FAILED
|
858
|
USER_REMOVE_ROLE
|
859
|
USER_REMOVE_ROLE_FAILED
|
860
|
USER_ATTACHED_ACTION_GROUP_TO_ROLE
|
861
|
USER_ATTACHED_ACTION_GROUP_TO_ROLE_FAILED
|
862
|
USER_DETACHED_ACTION_GROUP_FROM_ROLE
|
863
|
USER_DETACHED_ACTION_GROUP_FROM_ROLE_FAILED
|
864
|
USER_ADD_ROLE_WITH_ACTION_GROUP
|
865
|
USER_ADD_ROLE_WITH_ACTION_GROUP_FAILED
|
900
|
AD_COMPUTER_ACCOUNT_SUCCEEDED
|
901
|
AD_COMPUTER_ACCOUNT_FAILED
|
920
|
NETWORK_ATTACH_NETWORK_TO_HOST
|
921
|
NETWORK_ATTACH_NETWORK_TO_HOST_FAILED
|
922
|
NETWORK_DETACH_NETWORK_FROM_HOST
|
923
|
NETWORK_DETACH_NETWORK_FROM_HOST_FAILED
|
924
|
NETWORK_ADD_BOND
|
925
|
NETWORK_ADD_BOND_FAILED
|
926
|
NETWORK_REMOVE_BOND
|
927
|
NETWORK_REMOVE_BOND_FAILED
|
928
|
NETWORK_HOST_NETWORK_MATCH_CLUSTER
|
929
|
NETWORK_HOST_NETWORK_NOT_MATCH_CLUSTER
|
930
|
NETWORK_REMOVE_VM_INTERFACE
|
931
|
NETWORK_REMOVE_VM_INTERFACE_FAILED
|
932
|
NETWORK_ADD_VM_INTERFACE
|
933
|
NETWORK_ADD_VM_INTERFACE_FAILED
|
934
|
NETWORK_UPDATE_VM_INTERFACE
|
935
|
NETWORK_UPDATE_VM_INTERFACE_FAILED
|
936
|
NETWORK_ADD_TEMPLATE_INTERFACE
|
937
|
NETWORK_ADD_TEMPLATE_INTERFACE_FAILED
|
938
|
NETWORK_REMOVE_TEMPLATE_INTERFACE
|
939
|
NETWORK_REMOVE_TEMPLATE_INTERFACE_FAILED
|
940
|
NETWORK_UPDATE_TEMPLATE_INTERFACE
|
941
|
NETWORK_UPDATE_TEMPLATE_INTERFACE_FAILED
|
942
|
NETWORK_ADD_NETWORK
|
943
|
NETWORK_ADD_NETWORK_FAILED
|
944
|
NETWORK_REMOVE_NETWORK
|
945
|
NETWORK_REMOVE_NETWORK_FAILED
|
946
|
NETWORK_ATTACH_NETWORK_TO_HOST_GROUP
|
947
|
NETWORK_ATTACH_NETWORK_TO_HOST_GROUP_FAILED
|
948
|
NETWORK_DETACH_NETWORK_TO_HOST_GROUP
|
949
|
NETWORK_DETACH_NETWORK_TO_HOST_GROUP_FAILED
|
950
|
USER_ADD_STORAGE_POOL
|
951
|
USER_ADD_STORAGE_POOL_FAILED
|
952
|
USER_UPDATE_STORAGE_POOL
|
953
|
USER_UPDATE_STORAGE_POOL_FAILED
|
954
|
USER_REMOVE_STORAGE_POOL
|
955
|
USER_REMOVE_STORAGE_POOL_FAILED
|
956
|
USER_ADD_STORAGE_DOMAIN
|
957
|
USER_ADD_STORAGE_DOMAIN_FAILED
|
958
|
USER_UPDATE_STORAGE_DOMAIN
|
959
|
USER_UPDATE_STORAGE_DOMAIN_FAILED
|
960
|
USER_REMOVE_STORAGE_DOMAIN
|
961
|
USER_REMOVE_STORAGE_DOMAIN_FAILED
|
962
|
USER_ATTACH_STORAGE_DOMAIN_TO_POOL
|
963
|
USER_ATTACH_STORAGE_DOMAIN_TO_POOL_FAILED
|
964
|
USER_DETACH_STORAGE_DOMAIN_FROM_POOL
|
965
|
USER_DETACH_STORAGE_DOMAIN_FROM_POOL_FAILED
|
966
|
USER_ACTIVATED_STORAGE_DOMAIN
|
967
|
USER_ACTIVATE_STORAGE_DOMAIN_FAILED
|
968
|
USER_DEACTIVATED_STORAGE_DOMAIN
|
969
|
USER_DEACTIVATE_STORAGE_DOMAIN_FAILED
|
970
|
SYSTEM_DEACTIVATED_STORAGE_DOMAIN
|
971
|
SYSTEM_DEACTIVATE_STORAGE_DOMAIN_FAILED
|
972
|
USER_EXTENDED_STORAGE_DOMAIN
|
973
|
USER_EXTENDED_STORAGE_DOMAIN_FAILED
|
974
|
USER_REMOVE_VG
|
975
|
USER_REMOVE_VG_FAILED
|
976
|
USER_ACTIVATE_STORAGE_POOL
|
977
|
USER_ACTIVATE_STORAGE_POOL_FAILED
|
978
|
SYSTEM_FAILED_CHANGE_STORAGE_POOL_STATUS
|
979
|
SYSTEM_CHANGE_STORAGE_POOL_STATUS_NO_HOST_FOR_SPM
|
980
|
SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC
|
981
|
USER_FORCE_REMOVE_STORAGE_DOMAIN
|
982
|
USER_FORCE_REMOVE_STORAGE_DOMAIN_FAILED
|
983
|
RECONSTRUCT_MASTER_FAILED_NO_MASTER
|
984
|
RECONSTRUCT_MASTER_DONE
|
985
|
RECONSTRUCT_MASTER_FAILED
|
986
|
SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_SEARCHING_NEW_SPM
|
987
|
SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_WITH_ERROR
|
988
|
USER_CONNECT_HOSTS_TO_LUN_FAILED
|
989
|
SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_FROM_NON_OPERATIONAL
|
990
|
SYSTEM_MASTER_DOMAIN_NOT_IN_SYNC
|
991
|
RECOVERY_STORAGE_POOL
|
992
|
RECOVERY_STORAGE_POOL_FAILED
|
993
|
SYSTEM_CHANGE_STORAGE_POOL_STATUS_RESET_IRS
|
994
|
CONNECT_STORAGE_SERVERS_FAILED
|
995
|
CONNECT_STORAGE_POOL_FAILED
|
996
|
STORAGE_DOMAIN_ERROR
|
1100
|
NETWORK_UPDATE_DISPLAY_TO_HOST_GROUP
|
1101
|
NETWORK_UPDATE_DISPLAY_TO_HOST_GROUP_FAILED
|
1102
|
NETWORK_UPDATE_NETWORK_TO_HOST_INTERFACE
|
1103
|
NETWORK_UPDATE_NETWORK_TO_HOST_INTERFACE_FAILED
|
1104
|
NETWORK_COMMINT_NETWORK_CHANGES
|
1105
|
NETWORK_COMMINT_NETWORK_CHANGES_FAILED
|
1106
|
NETWORK_HOST_USING_WRONG_CLUSER_VLAN
|
1107
|
NETWORK_HOST_MISSING_CLUSER_VLAN
|
1150
|
IMPORTEXPORT_EXPORT_VM
|
1151
|
IMPORTEXPORT_EXPORT_VM_FAILED
|
1152
|
IMPORTEXPORT_IMPORT_VM
|
1153
|
IMPORTEXPORT_IMPORT_VM_FAILED
|
1154
|
IMPORTEXPORT_REMOVE_TEMPLATE
|
1155
|
IMPORTEXPORT_REMOVE_TEMPLATE_FAILED
|
1156
|
IMPORTEXPORT_EXPORT_TEMPLATE
|
1157
|
IMPORTEXPORT_EXPORT_TEMPLATE_FAILED
|
1158
|
IMPORTEXPORT_IMPORT_TEMPLATE
|
1159
|
IMPORTEXPORT_IMPORT_TEMPLATE_FAILED
|
1160
|
IMPORTEXPORT_REMOVE_VM
|
1161
|
IMPORTEXPORT_REMOVE_VM_FAILED
|
1162
|
IMPORTEXPORT_STARTING_EXPORT_VM
|
1163
|
IMPORTEXPORT_STARTING_IMPORT_TEMPLATE
|
1164
|
IMPORTEXPORT_STARTING_EXPORT_TEMPLATE
|
1165
|
IMPORTEXPORT_STARTING_IMPORT_VM
|
1166
|
IMPORTEXPORT_STARTING_REMOVE_TEMPLATE
|
1167
|
IMPORTEXPORT_STARTING_REMOVE_VM
|
1168
|
IMPORTEXPORT_FAILED_TO_IMPORT_VM
|
1169
|
IMPORTEXPORT_FAILED_TO_IMPORT_TEMPLATE
|
9000
|
HOST_ALERT_FENCING_IS_NOT_CONFIGURED
|
9001
|
HOST_ALERT_FENCING_TEST_FAILED
|
9002
|
HOST_ALERT_FENCING_OPERATION_FAILED
|
9003
|
HOST_ALERT_FENCING_OPERATION_SKIPPED
|
9004
|
HOST_ALERT_FENCING_NO_PROXY_HOST
|
9500
|
TASK_STOPPING_ASYNC_TASK
|
9501
|
TASK_CLEARING_ASYNC_TASK
|
The API maps Windows Standard Format timezone names to tz database format when specifying a timezone for a virtual machine or VM template. This means the API only accepts certain tz database codes, which the following table lists:
Table E.1. Accepted tz database codes
| tz database Format | Windows Standard Format |
|---|---|
Africa/Cairo
|
Egypt Standard Time
|
Africa/Casablanca
|
Morocco Standard Time
|
Africa/Johannesburg
|
South Africa Standard Time
|
Africa/Lagos
|
W. Central Africa Standard Time
|
Africa/Nairobi
|
E. Africa Standard Time
|
Africa/Reykjavik
|
Greenwich Standard Time
|
Africa/Windhoek
|
Namibia Standard Time
|
America/Anchorage
|
Alaskan Standard Time
|
America/Bogota
|
SA Pacific Standard Time
|
America/Buenos_Aires
|
Argentina Standard Time
|
America/Caracas
|
Venezuela Standard Time
|
America/Chicago
|
Central Standard Time
|
America/Chihuahua
|
Mexico Standard Time
|
America/Chihuahua
|
Mountain Standard Time
|
America/Denver
|
Mountain Standard Time
|
America/Godthab
|
Greenland Standard Time
|
America/Guatemala
|
Central America Standard Time
|
America/Halifax
|
Atlantic Standard Time
|
America/La_Paz
|
SA Western Standard Time
|
America/Los_Angeles
|
Pacific Standard Time
|
America/Manaus
|
Central Brazilian Standard Time
|
America/Mexico_City
|
Central Standard Time
|
America/Mexico_City
|
Mexico Standard Time
|
America/Montevideo
|
Montevideo Standard Time
|
America/New_York
|
Eastern Standard Time
|
America/Phoenix
|
US Mountain Standard Time
|
America/Regina
|
Canada Central Standard Time
|
America/Santiago
|
Pacific SA Standard Time
|
America/Sao_Paulo
|
E. South America Standard Time
|
America/St_Johns
|
Newfoundland Standard Time
|
America/Tijuana
|
Pacific Standard Time
|
Asia/Amman
|
Jordan Standard Time
|
Asia/Baghdad
|
Arabic Standard Time
|
Asia/Baku
|
Azerbaijan Standard Time
|
Asia/Bangkok
|
SE Asia Standard Time
|
Asia/Beirut
|
Middle East Standard Time
|
Asia/Calcutta
|
India Standard Time
|
Asia/Colombo
|
Sri Lanka Standard Time
|
Asia/Dhaka
|
Central Asia Standard Time
|
Asia/Dubai
|
Arabian Standard Time
|
Asia/Irkutsk
|
North Asia East Standard Time
|
Asia/Jerusalem
|
Israel Standard Time
|
Asia/Kabul
|
Afghanistan Standard Time
|
Asia/Karachi
|
Pakistan Standard Time
|
Asia/Katmandu
|
Nepal Standard Time
|
Asia/Krasnoyarsk
|
North Asia Standard Time
|
Asia/Novosibirsk
|
N. Central Asia Standard Time
|
Asia/Rangoon
|
Myanmar Standard Time
|
Asia/Riyadh
|
Arab Standard Time
|
Asia/Seoul
|
Korea Standard Time
|
Asia/Shanghai
|
China Standard Time
|
Asia/Singapore
|
Singapore Standard Time
|
Asia/Taipei
|
Taipei Standard Time
|
Asia/Tashkent
|
West Asia Standard Time
|
Asia/Tehran
|
Iran Standard Time
|
Asia/Tokyo
|
Tokyo Standard Time
|
Asia/Vladivostok
|
Vladivostok Standard Time
|
Asia/Yakutsk
|
Yakutsk Standard Time
|
Asia/Yekaterinburg
|
Ekaterinburg Standard Time
|
Asia/Yerevan
|
Armenian Standard Time
|
Asia/Yerevan
|
Caucasus Standard Time
|
Atlantic/Azores
|
Azores Standard Time
|
Atlantic/Cape_Verde
|
Cape Verde Standard Time
|
Atlantic/South_Georgia
|
Mid-Atlantic Standard Time
|
Australia/Adelaide
|
Cen. Australia Standard Time
|
Australia/Brisbane
|
E. Australia Standard Time
|
Australia/Darwin
|
AUS Central Standard Time
|
Australia/Hobart
|
Tasmania Standard Time
|
Australia/Perth
|
W. Australia Standard Time
|
Australia/Sydney
|
AUS Eastern Standard Time
|
Etc/GMT-3
|
Georgian Standard Time
|
Etc/GMT+12
|
Dateline Standard Time
|
Etc/GMT+3
|
SA Eastern Standard Time
|
Etc/GMT+5
|
US Eastern Standard Time
|
Europe/Berlin
|
W. Europe Standard Time
|
Europe/Budapest
|
Central Europe Standard Time
|
Europe/Istanbul
|
GTB Standard Time
|
Europe/Kiev
|
FLE Standard Time
|
Europe/London
|
GMT Standard Time
|
Europe/Minsk
|
E. Europe Standard Time
|
Europe/Moscow
|
Russian Standard Time
|
Europe/Paris
|
Romance Standard Time
|
Europe/Warsaw
|
Central European Standard Time
|
Indian/Mauritius
|
Mauritius Standard Time
|
Pacific/Apia
|
Samoa Standard Time
|
Pacific/Auckland
|
New Zealand Standard Time
|
Pacific/Fiji
|
Fiji Standard Time
|
Pacific/Guadalcanal
|
Central Pacific Standard Time
|
Pacific/Honolulu
|
Hawaiian Standard Time
|
Pacific/Port_Moresby
|
West Pacific Standard Time
|
Pacific/Tongatapu
|
Tonga Standard Time
|
| Revision History | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Revision 1-81.400 | 2013-10-31 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-81 | Fri 27 Sep 2013 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-79 | Wed 15 Nov 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-78 | Wed 14 Nov 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-77 | Mon 12 Nov 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-76 | Wed 7 Nov 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-75 | Mon 5 Nov 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-74 | Fri 30 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-73 | Fri 26 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-72 | Tue 24 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-71 | Thu Oct 18 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-70 | Wed Oct 17 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-69 | Tue 16 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-68 | Mon 15 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-67 | Fri 12 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-66 | Fri 12 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-65 | Fri 12 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-64 | Thu 11 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-63 | Thu 11 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-61.1 | Wed 4 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-61 | Wed 3 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-60 | Tue 2 Oct 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-59 | Mon 24 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-58 | Fri 21 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-57 | Thu 20 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-56 | Wed 19 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-55 | Wed 19 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-54 | Tue 18 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-53 | Tue 18 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-52 | Tue 5 Sept 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-51 | Thu 29 Aug 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-50 | Thu 29 Aug 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-49 | Mon Apr 2 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-48 | Tues Mar 13 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-47 | Wed Feb 17 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-45 | Wed Feb 15 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-44 | Tue Feb 07 2012 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-39 | Thu Dec 1 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-38 | Thu Nov 24 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-37 | Fri Nov 11 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-36 | Mon Oct 31 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-35 | Thu Oct 27 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-34 | Thu Oct 27 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-33 | Wed Oct 26 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-32 | Tue Oct 25 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-31 | Thu Oct 19 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-30 | Wed Oct 12 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-29 | Tue Oct 4 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-28 | Tue Oct 4 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-27 | Fri Sept 30 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-26 | Wed Sept 28 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-25 | Fri Sept 22 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-23 | Fri Sept 19 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-22 | Fri Sept 9 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-21 | Thu Sept 8 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-18 | Thu Aug 24 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-17 | Thu Aug 04 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-16 | Thu Aug 04 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-15 | Thu Aug 04 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-14 | Thu Aug 04 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-12 | Tue Jul 19 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-11 | Thu Jul 7 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-10 | Thu Jul 7 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-9 | Thu Jul 7 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-8 | Wed Jul 6 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-6 | Thu Jun 30 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-5 | Mon Jun 20 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| Revision 1-4 | Thu Jun 16 2011 | ||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||