Red Hat Enterprise Virtualization 3.2

Developer Guide

Using the Red Hat Enterprise Virtualization Application Programming Interfaces

Edition 1

Andrew Burden

Steve Gordon

Dan Macpherson

Legal Notice

Copyright © 2013 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.


This document describes Red Hat Enterprise Virtualization's developer API and SDK.
1. Document Conventions
2. Getting Help and Giving Feedback
I. Introduction
1. Introduction
1.1. Introduction to the Red Hat Enterprise Virtualization REST API
1.2. Representational State Transfer
1.3. Red Hat Enterprise Virtualization REST API Prerequisites
2. Authentication and Security
2.1. TLS/SSL Certification
2.2. HTTP Authentication
2.3. Authentication Sessions
3. REST API Quick Start Example
3.1. REST API Quick Start Introduction
3.2. Example: Access API Entry Point
3.3. Example: List Data Center Collection
3.4. Example: List Host Cluster Collection
3.5. Example: List Logical Networks Collection
3.6. Example: List Host Collection
3.7. Example: Approve Host
3.8. Example: Create NFS Data Storage
3.9. Example: Create NFS ISO Storage
3.10. Example: Attach Storage Domains to Data Center
3.11. Example: Activate Storage Domains
3.12. Example: Create Virtual Machine
3.13. Example: Create Virtual Machine NIC
3.14. Example: Create Virtual Machine Storage Disk
3.15. Example: Attach ISO Image to Virtual Machine
3.16. Example: Start Virtual Machine
3.17. Example: Check System Events
4. Python Quick Start 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
5.1. Accessing the API Entry Point
5.2. Product Information
5.3. Link Elements
5.4. Special Object Elements
5.5. Summary Element
5.6. RESTful Service Description Language (RSDL)
6. Compatibility Level Versions
6.1. Compatibility Level Versions
6.2. Upgrading Compatibility Levels
7. Capabilities
7.1. Capabilities
7.2. Version-Dependent Capabilities
7.3. Current Version
7.4. Features
7.5. CPUs
7.6. Power Managers
7.7. Fence Types
7.8. Storage Types
7.9. Storage Domain Types
7.10. Virtual Machine Types
7.11. Boot Devices
7.12. Display Types
7.13. NIC Interface Types
7.14. OS Types
7.15. Disk Formats
7.16. Disk Interfaces
7.17. Virtual Machine Affinities
7.18. Custom Properties
7.19. Boot Protocols
7.20. Error Handling
7.21. Storage Formats
7.22. Virtual Machine Device Types
7.23. Gluster Volume Types
7.24. Gluster Transport Types
7.25. Guster Access Protocols
7.26. Resource Status States
7.27. Permits
7.28. Scheduling Policies
8. Common Features
8.1. Element Property Icons
8.2. Representations
8.3. Collections
8.4. Resources
9. Data Centers
9.1. Data Center Elements
9.2. XML Representation of a Data Center
9.3. Methods
9.4. Sub-Collections
9.5. Actions
10. Host Clusters
10.1. Host Cluster Elements
10.2. Memory Policy Elements
10.3. Scheduling Policy Elements
10.4. XML Representation of a Host Cluster
10.5. Methods
10.6. Sub-Collections
11. Networks
11.1. Network Elements
11.2. XML Representation of a Network Resource
11.3. Methods
12. Storage Domains
12.1. Storage Domain Elements
12.2. XML Representation of a Storage Domain
12.3. Methods
12.4. Storage Types
12.5. Export Storage Domains
12.6. Sub-Collections
12.7. Actions
13. Hosts
13.1. Host Elements
13.2. XML Representation of a Host
13.3. Power Management Elements
13.4. Memory Management Elements
13.5. Methods
13.6. Sub-Collections
13.7. Actions
14. Virtual Machines
14.1. Virtual Machine Elements
14.2. XML Representation of a Virtual Machine
14.3. Methods
14.4. Sub-Collections
14.5. Actions
15. Floating Disks
15.1. Floating Disk Elements
15.2. XML Representation of a Floating Disk
15.3. Methods
15.4. Sub-Collections
16. Templates
16.1. Virtual Machine Template Elements
16.2. XML Representation of a Virtual Machine Template
16.3. Methods
16.4. Actions
17. Virtual Machine Pools
17.1. Virtual Machine Pool Elements
17.2. XML Representation of a Virtual Machine Pool
17.3. Methods
18. Domains
18.1. Domain Elements
18.2. XML Representation of a Domain Resource
18.3. Sub-Collections
19. Groups
19.1. Imported Group Elements
19.2. XML Representation of a Group Resource
19.3. Adding a Group from a Directory Service
20. Roles
20.1. Role Elements
20.2. XML Representation of the Roles Collection
20.3. Methods
20.4. Roles Permits Sub-Collection
21. Users
21.1. User Elements
21.2. XML representation of a User Resource
21.3. Methods
22. Tags
22.1. Tag Elements
22.2. XML Representation of a Tag Resource
22.3. Associating Tags
22.4. Parent Tags
23. Events
23.1. Event Elements
23.2. XML Representation of the Events Collection
23.3. XML Representation of a Virtual Machine Creation Event
23.4. Searching Events
23.5. Paginating Events
III. Python Sofware Development Kit
24. Software Development Kit Overview
24.1. Introduction to the Red Hat Enterprise Virtualization Software Development Kit
24.2. Software Development Kit Prerequisites
24.3. Installing the Software Development Kit
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
26.1. Python Reference Documentation
A. SDK Examples
A.1. Common Statements
A.2. Common Functions and Wrappers
A.3. Python SDK Example: Hosts
A.4. Python SDK Example: Virtual Machines
A.5. Python SDK Example: Templates
A.6. Python SDK Example: Virtual Machine Pools
A.7. Python SDK Example: Storage
A.8. Python SDK Example: Groups
A.9. Python SDK Example: Permissions
A.10. Python SDK Example: Users
B. API Usage with cURL
B.1. API Usage with cURL
B.2. Installing cURL
B.3. Using cURL
B.4. Examples
C. Certificates
C.1. Creating SSL/TLS Certificates
C.2. Creating an SSL Certificate
C.3. Configuring HTTPS Communication
C.4. Network Security Services (NSS) Database
C.5. Java Keystores
D. Enumerated Value Translation
D.1. Enumerated Value Translation
E. Event Codes
E.1. Event Codes
F. Timezones
F.1. Timezones
G. Revision History