1. Introduction
The oVirt Engine provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their oVirt environment outside of the standard web interface. The API is useful for developers and administrators to integrate the functionality of a oVirt environment with custom scripts or external applications that access the API via the standard Hypertext Transfer Protocol (HTTP).
The benefits of the 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 oVirt environment with scripts.
This documentation acts as a reference for the oVirt API. It aims to provide developers and administrators with instructions and examples to help harness the functionality of their oVirt environment through the API, either directly or using the provided SDKs.
1.1. Representational State Transfer
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 independently of any
other request, and contains all the information necessary to complete the
request.
1.2. API Prerequisites
Prerequisites for using the oVirt API:
-
A networked installation of oVirt Engine, which includes the API.
-
A client or programming library that initiates and receives HTTP requests from the API server. For example:
-
The oVirt Python SDK.
-
The oVirt Ruby SDK.
-
The oVirt Java SDK.
-
The cURL command line tool.
-
RESTClient, a debugger for RESTful web services.
-
-
Knowledge of Hypertext Transfer Protocol (HTTP), 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.
-
Knowledge of Extensible Markup Language (XML) or JavaScript Object Notation (JSON), which the API uses to construct resource representations. The W3C provides a full specification on XML at http://www.w3.org/TR/xml. ECMA International provide a free publication on JSON at http://www.ecma-international.org.
2. Authentication and Security
2.1. TLS/SSL Certification
The oVirt API requires Hypertext Transfer Protocol Secure (HTTPS) [1] for secure interaction with client software, such as the SDK and CLI components. This involves obtaining the CA certificate used by the server, and importing it into the certificate store of your client.
2.1.1. Obtaining the CA Certificate
You can obtain the CA certificate from the oVirt Engine and transfer it to the client machine using one of these methods:
- Method 1
-
The preferred method for obtaining the CA certificate is to use the
openssl s_client
command line tool to perform a real TLS handshake with the server, and then extract the certificates that it presents. Run a command like this:$ openssl s_client \ -connect myengine.example.com:443 \ -showcerts \ < /dev/null
This command will connect to the server and display output similar to the following:
CONNECTED(00000003) depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416 verify error:num=19:self signed certificate in certificate chain --- Certificate chain 0 s:/C=US/O=Example Inc./CN=myengine.example.com i:/C=US/O=Example Inc./CN=myengine.example.com.23416 -----BEGIN CERTIFICATE----- MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg= -----END CERTIFICATE----- 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416 i:/C=US/O=Example Inc./CN=myengine.example.com.23416 -----BEGIN CERTIFICATE----- MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs Pkyg1rQHR6ebGQ== -----END CERTIFICATE-----
The text between the
-----BEGIN CERTIFICATE-----
and-----END CERTIFICATE-----
marks shows the certificates presented by the server. The first one is the certificate of the server itself, and the last one is the certificate of the CA. Copy the CA certificate, including the marks, to theca.crt
file. The result should look like this:-----BEGIN CERTIFICATE----- MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs Pkyg1rQHR6ebGQ== -----END CERTIFICATE-----
This is the most reliable method to obtain the CA certificate used by the server. The rest of the methods described here will work in most cases, but they will not obtain the correct CA certificate if it has been manually replaced by the administrator of the server. - Method 2
-
If you cannot use the
openssl s_client
method described above, you can instead use a command line tool to download the CA certificate from the oVirt Engine.Examples of command line tools include
curl
andwget
, both of which are available on multiple platforms.If using
curl
:$ curl \ --output ca.crt \ 'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
If using
wget
:$ wget \ --output-document ca.crt \ 'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
- Method 3
-
Use a web browser to navigate to the certificate located at:
https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
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
ca.crt
. -
If the browser imports the certificate: export it from the browser’s certification options and save it as
ca.crt
.
-
- Method 4
-
Log in to the oVirt Engine, export the certificate from the truststore, and copy it to your client machine.
-
Log in to the oVirt Engine machine as
root
. -
Export the certificate from the truststore using the Java
keytool
management utility:# keytool \ -keystore /etc/pki/ovirt-engine/.truststore \ -storepass mypass \ -exportcert \ -alias cacert \ -rfc \ -file ca.crt
This creates a certificate file called
ca.crt
. -
Copy the certificate to the client machine using the
scp
command:$ scp ca.crt myuser@myclient.example.com:/home/myuser/.
-
Each of these methods results in a certificate file named ca.crt
on
your client machine. You must then import this file into the certificate
store of the client.
2.2. Authentication
Any user with a oVirt Engine account has access to the API. All requests must be authenticated using either OAuth or basic authentication, as described below.
2.2.1. OAuth Authentication
Since version 4.0 of oVirt the preferred authentication mechanism is OAuth 2.0, as described in RFC 6749.
OAuth is a sophisticated protocol, with several mechanisms for obtaining authorization and access tokens. For use with the oVirt API, the only supported one is the Resource Owner Password Credentials Grant, as described in section 4.3 of RFC 6749.
You must first obtain a token, sending the user name and password to the oVirt Engine single sign-on service:
POST /ovirt-engine/sso/oauth/token HTTP/1.1 Host: myengine.example.com Content-Type: application/x-www-form-urlencoded Accept: application/json
The request body must contain the grant_type
, scope
, username
,
and password
parameters:
Name | Value |
---|---|
|
|
|
|
|
|
|
|
These parameters must be
URL-encoded. For example,
the @
character in the user name needs to be encoded as %40
. The
resulting request body will be something like this:
grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
The scope parameter is described as optional in the OAuth
RFC, but when using it with the oVirt API it is mandatory, and
its value must be ovirt-app-api .
|
If the user name and password are valid, the oVirt Engine single sign-on service will respond with a JSON document similar to this one:
{ "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=", "token_type": "bearer", "scope": "...", ... }
For API authentication purposes, the only relevant name/value pair is the
access_token
. Do not manipulate this in any way; use it exactly as
provided by the SSO service.
Once the token has been obtained, it can be used to perform requests to
the API by including it in the HTTP Authorization
header, and using the
Bearer
scheme. For example, to get the list of virtual machines,
send a request like this:
GET /ovirt-engine/api/vms HTTP/1.1 Host: myengine.example.com Accept: application/xml Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
The token can be used multiple times, for multiple requests, but it will eventually expire. When it expires, the server will reject the request with the 401 HTTP response code:
HTTP/1.1 401 Unauthorized
When this happens, a new token is needed, as the oVirt Engine single sign-on service does not currently support refreshing tokens. A new token can be requested using the same method described above.
2.2.2. Basic Authentication
Basic authentication is supported only for backwards compatibility; it is deprecated since version 4.0 of oVirt, and will be removed in the future. |
Each request uses HTTP Basic Authentication [2] to
encode the credentials. If a request does not include an appropriate
Authorization
header, the server sends a 401 Authorization Required
response:
HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com HTTP/1.1 401 Authorization Required
Request are issued with an Authorization
header for the specified
realm. Encode an appropriate oVirt Engine domain and user
in the supplied credentials with the username@domain:password
convention.
The following table shows the process for encoding credentials in Base64.
Item | Value |
---|---|
User name |
|
Domain |
|
Password |
|
Unencoded credentials |
|
Base64 encoded credentials |
|
Provide the Base64-encoded credentials as shown:
HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== HTTP/1.1 200 OK
Basic authentication involves potentially sensitive information, such as passwords, sent as plain text. The API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests. |
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.
|
2.2.3. Authentication Sessions
The API also provides authentication session support. Send an initial request with authentication details, then send all subsequent requests using a session cookie to authenticate.
Requesting an Authenticated Session
-
Send a request with the
Authorization
andPrefer: persistent-auth
headers:HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== Prefer: persistent-auth HTTP/1.1 200 OK ...
This returns a response with the following header:
Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure
Take note of the
JSESSIONID=
value. In this example the value is5dQja5ubr4yvI2MM2z+LZxrK
. -
Send all subsequent requests with the
Prefer: persistent-auth
andCookie
headers with theJSESSIONID=
value. TheAuthorization
header is no longer needed when using an authenticated session.HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com 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-auth
header.HEAD /ovirt-engine/api HTTP/1.1 Host: myengine.example.com Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA== HTTP/1.1 200 OK ...
3. Quick start example
This chapter provides an example to demonstrate the REST API’s ability to setup a basic oVirt environment and create a virtual machine. In addition to the standard prerequisites, this example requires the following:
-
A networked and configured oVirt installation;
-
An ISO file containing a desired virtual machine operating system to install. This chapter uses CentOS 7 for our installation ISO example; and
-
oVirt’s
engine-iso-uploader
tool to upload your chosen operating system ISO file.
This example uses curl
to demonstrate API
requests with a client application. Note that any application capable of
HTTP requests can substitute for curl
.
For simplicity, the HTTP request headers in this example omit
the Host and Authorization headers. However, these fields are mandatory
and require data specific to your installation of oVirt.
|
All the curl examples use admin@internal as the user
name, mypassword as the password, /etc/pki/ovirt-engine/ca.pem as the
certificate location and myengine.example.com as the host name. These
are just examples, Make sure to replace them with valid values for your
environment.
|
oVirt generates an unique identifier for the id
attribute for each resource. Identifier codes in this example might
appear different to the identifier codes in your oVirt
environment.
|
In many examples of this section some of the attributes of results
returned by the API have been omitted, to make them shorter. You can
always use the reference to find the complete list of attributes. For
example, if you want to see the complete list of attributes of the
Cluster type, just go here.
|
3.1. Example: Access API entry point
The following request retrieves a representation of the main entry point for version 4 of of the API:
GET /ovirt-engine/api HTTP/1.1 Version: 4 Accept: application/xml
Same request, but using the /v4
URL prefix instead of the Version
header:
GET /ovirt-engine/api/v4 HTTP/1.1 Accept: application/xml
Same request, using the curl
command:
curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --request GET \ --header 'Version: 4' \ --header 'Accept: application/xml' \ --user 'admin@internal:mypassword' \ https://myengine.example.com/ovirt-engine/api
The result will be an object of type Api:
<api>
<link href="/ovirt-engine/api/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters" rel="datacenters"/>
...
<product_info>
<name>oVirt Engine</name>
<vendor>ovirt.org</vendor>
<version>
<build>0</build>
<full_version>4.0.0-0.0.el7</full_version>
<major>4</major>
<minor>0</minor>
<revision>0</revision>
</version>
</product_info>
<special_objects>
<blank_template href="..." id="..."/>
<root_tag href="..." id="..."/>
</special_objects>
<summary>
<hosts>
<active>23</active>
<total>30</total>
</hosts>
<storage_domains>
<active>5</active>
<total>6</total>
</storage_domains>
<users>
<active>12</active>
<total>102</total>
</users>
<vms>
<active>253</active>
<total>545</total>
</vms>
</summary>
<time>2016-10-06T15:38:18.548+02:00</time>
</api>
When neither the header nor the URL prefix are used, the server will
automatically select a version. The default is version # echo "ENGINE_API_DEFAULT_VERSION=3" > \ /etc/ovirt-engine/engine.conf.d/99-set-default-version.conf # systemctl restart ovirt-engine Changing this parameter affects all users of the API that don’t specify the version explicitly. |
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 data center collection, which is available through the
datacenters
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.
3.2. Example: List data centers
oVirt 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 centers:
GET /ovirt-engine/api/datacenters HTTP/1.1 Accept: application/xml
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --request GET \ --header 'Version: 4' \ --header 'Accept: application/xml' \ --user 'admin@internal:mypassword' \ https://myengine.example.com/ovirt-engine/api/datacenters
The result will be a list of objects of type DataCenter:
<data_centers>
<data_center href="/ovirt-engine/api/datacenters/001" id="001">
<name>Default</name>
<description>The default Data Center</description>
<link href="/ovirt-engine/api/datacenters/001/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/>
...
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</data_center>
...
</data_centers>
Note the id
of your Default
data center. It identifies this data
center in relation to other resources of your virtual environment.
The data center also contains a link to the service that manages the storage domains attached to the data center:
<link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/>
That service is used to attach storage domains from the main
storagedomains
collection, which this example covers later.
3.3. Example: List host clusters
oVirt creates a Default
hosts cluster on installation. This
example uses the Default
cluster to group resources in your
oVirt environment.
The following request retrieves a representation of the cluster collection:
GET /ovirt-engine/api/clusters HTTP/1.1 Accept: application/xml
Same request, using the curl
command:
curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --request GET \ --header 'Version: 4' \ --header 'Accept: application/xml' \ --user 'admin@internal:mypassword' \ https://myengine.example.com/ovirt-engine/api/clusters
The result will be a list of objects of type Cluster:
<clusters>
<cluster href="/ovirt-engine/api/clusters/002" id="002">
<name>Default</name>
<description>The default server cluster</description>
<link href="/ovirt-engine/api/clusters/002/networks" rel="networks"/>
<link href="/ovirt-engine/api/clusters/002" rel="permissions"/>
...
<cpu>
<architecture>x86_64</architecture>
<type>Intel Conroe Family</type>
</cpu>
<version>
<major>4</major>
<minor>0</minor>
</version>
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
</cluster>
...
</clusters>
Note the id
of your Default
host cluster. It 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
link:
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
The networks
link is a reference to the service that manages the networks associated to this cluster. The next
section examines the networks collection in more detail.
3.4. Example: List logical networks
oVirt creates a default ovirtmgmt
network on installation.
This network acts as the management network for oVirt Engine to access
hosts.
This network is associated with our Default
cluster and is a member of
the Default
data center. This example uses the ovirtmgmt
network to
connect our virtual machines.
The following request retrieves the list of logical networks:
GET /ovirt-engine/api/networks HTTP/1.1 Accept: application/xml
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --request GET \ --header 'Version: 4' \ --header 'Accept: application/xml' \ --user 'admin@internal:mypassword' \ https://myengine.example.com/ovirt-engine/api/networks
The result will be a list of objects of type Network:
<networks>
<network href="/ovirt-engine/api/networks/003" id="003">
<name>ovirtmgmt</name>
<description>Management Network</description>
<link href="/ovirt-engine/api/networks/003/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/networks/003/vnicprofiles" rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/003/networklabels" rel="networklabels"/>
<mtu>0</mtu>
<stp>false</stp>
<usages>
<usage>vm</usage>
</usages>
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
</network>
...
</networks>
The ovirtmgmt
network is attached to the Default
data center through a
relationship using the data center’s id
.
The ovirtmgmt
network is also attached to the Default
cluster through a
relationship in the cluster’s network sub-collection.
3.5. Example: List hosts
This example retrieves the list of hosts and shows a host named myhost
registered with the virtualization environment:
GET /ovirt-engine/api/hosts HTTP/1.1 Accept: application/xml
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --request GET \ --header 'Version: 4' \ --header 'Accept: application/xml' \ --user 'admin@internal:mypassword' \ https://myengine.example.com/ovirt-engine/api/hosts
The result will be a list of objects of type Host:
<hosts>
<host href="/ovirt-engine/api/hosts/004" id="004">
<name>myhost</name>
<link href="/ovirt-engine/api/hosts/004/nics" rel="nics"/>
...
<address>node40.example.com</address>
<cpu>
<name>Intel Core Processor (Haswell, no TSX)</name>
<speed>3600</speed>
<topology>
<cores>1</cores>
<sockets>2</sockets>
<threads>1</threads>
</topology>
</cpu>
<memory>8371830784</memory>
<os>
<type>RHEL</type>
<version>
<full_version>7 - 2.1511.el7.centos.2.10</full_version>
<major>7</major>
</version>
</os>
<port>54321</port>
<status>up</status>
<cluster href="/ovirt-engine/api/clusters/002" id="002"/>
</host>
...
</hosts>
Note the id
of your host. It 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 ovirtmgmt
network.
3.6. Example: Create NFS data storage
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.
You can enable the wipe after delete option by default on the storage
domain. To configure this specify wipe_after_delete
in the POST
request. This option can be edited after the domain is created, but
doing so will not change the wipe after delete property of disks that
already exist.
The request should be like this:
POST /ovirt-engine/api/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml
And the request body should be like this:
<storage_domain>
<name>mydata</name>
<type>data</type>
<description>My data</description>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>
The same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <storage_domain> <name>mydata</name> <description>My data</description> <type>data</type> <storage> <type>nfs</type> <address>mynfs.example.com</address> <path>/exports/mydata</path> </storage> <host> <name>myhost</name> </host> </storage_domain> ' \ https://myengine.example.com/ovirt-engine/api/storagedomains
The server uses host myhost
to create a NFS data storage domain called
mydata
with an export path of mynfs.example.com:/exports/mydata
. The
API also returns the following representation of the newly created
storage domain resource (of type StorageDomain):
<storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">
<name>mydata</name>
<description>My data</description>
<available>42949672960</available>
<committed>0</committed>
<master>false</master>
<status>unattached</status>
<storage>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
<type>nfs</type>
</storage>
<storage_format>v3</storage_format>
<type>data</type>
<used>9663676416</used>
</storage_domain>
3.7. Example: Create NFS ISO storage
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:
The request should be like this:
POST /ovirt-engine/api/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml
And the request body should be like this:
<storage_domain>
<name>myisos</name>
<description>My ISOs</description>
<type>iso</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>
The same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <storage_domain> <name>myisos</name> <description>My ISOs</description> <type>iso</type> <storage> <type>nfs</type> <address>mynfs.example.com</address> <path>/exports/myisos</path> </storage> <host> <name>myhost</name> </host> </storage_domain> ' \ https://myengine.example.com/ovirt-engine/api/storagedomains
The server uses host myhost
to create a NFS ISO storage domain called
myisos
with an export path of mynfs.example.com:/exports/myisos
. The
API also returns the following representation of the newly created
storage domain resource (of type StorageDomain):
<storage_domain href="/ovirt-engine/api/storagedomains/006" id="006">
<name>myiso</name>
<description>My ISOs</description>
<available>42949672960</available>
<committed>0</committed>
<master>false</master>
<status>unattached</status>
<storage>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
<type>nfs</type>
</storage>
<storage_format>v1</storage_format>
<type>iso</type>
<used>9663676416</used>
</storage_domain>
3.8. Example: Attach storage domains to data center
The following example attaches the mydata
and myisos
storage domains
to the Default
data center.
To attach the mydata
storage domain, send a request like this:
POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml
With a request body like this:
<storage_domain>
<name>mydata</name>
</storage_domain>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <storage_domain> <name>mydata</name> </storage_domain> ' \ https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains
To attach the myisos
storage domain, send a request like this:
POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml
With a request body like this:
<storage_domain>
<name>myisos</name>
</storage_domain>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <storage_domain> <name>myisos</name> </storage_domain> ' \ https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains
3.9. Example: Create virtual machine
The following example creates a virtual machine called myvm
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 MiB and sets the boot device to a virtual hard disk.
The request should be contain an object of type Vm describing the virtual machine to create:
POST /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
And the request body should be like this:
<vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
</vm>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <vm> <name>myvm</name> <description>My VM</description> <cluster> <name>Default</name> </cluster> <template> <name>Blank</name> </template> <memory>536870912</memory> <os> <boot> <devices> <device>hd</device> </devices> </boot> </os> </vm> ' \ https://myengine.example.com/ovirt-engine/api/vms
The response body will be an object of the Vm type:
<vm href="/ovirt-engine/api/vms/007" id="007">
<name>myvm</name>
<link href="/ovirt-engine/api/vms/007/diskattachments" rel="diskattachments"/>
<link href="/ovirt-engine/api/vms/007/nics" rel="nics"/>
...
<cpu>
<architecture>x86_64</architecture>
<topology>
<cores>1</cores>
<sockets>1</sockets>
<threads>1</threads>
</topology>
</cpu>
<memory>1073741824</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
<type>other</type>
</os>
<type>desktop</type>
<cluster href="/ovirt-engine/api/clusters/002" id="002"/>
<status>down</status>
<original_template href="/ovirt-engine/api/templates/000" id="00"/>
<template href="/ovirt-engine/api/templates/000" id="000"/>
</vm>
3.10. Example: Create a virtual machine NIC
The following example creates a virtual network interface to connect the
example virtual machine to the ovirtmgmt
network.
The request should be like this:
POST /ovirt-engine/api/vms/007/nics HTTP/1.1 Content-Type: application/xml Accept: application/xml
The request body should contain an object of type Nic describing the NIC to be created:
<nic>
<name>mynic</name>
<description>My network interface card</description>
</nic>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <nic> <name>mynic</name> <description>My network interface card</description> </nic> ' \ https://myengine.example.com/ovirt-engine/api/vms/007/nics
3.11. Example: Create virtual machine disk
The following example creates an 8 GiB copy-on-write disk for the example virtual machine.
The request should be like this:
POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1 Content-Type: application/xml Accept: application/xml
The request body should be an object of type DiskAttachment describing the disk and how it will be attached to the virtual machine:
<disk_attachment>
<bootable>false</bootable>
<interface>virtio</interface>
<active>true</active>
<disk>
<description>My disk</description>
<format>cow</format>
<name>mydisk</name>
<provisioned_size>8589934592</provisioned_size>
<storage_domains>
<storage_domain>
<name>mydata</name>
</storage_domain>
</storage_domains>
</disk>
</disk_attachment>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <disk_attachment> <bootable>false</bootable> <interface>virtio</interface> <active>true</active> <disk> <description>My disk</description> <format>cow</format> <name>mydisk</name> <provisioned_size>8589934592</provisioned_size> <storage_domains> <storage_domain> <name>mydata</name> </storage_domain> </storage_domains> </disk> </disk_attachment> ' \ https://myengine.example.com/ovirt-engine/api/vms/007/diskattachments
The storage_domains
attribute tells the API to store the disk on the
mydata
storage domain.
3.12. Example: Attach ISO image to virtual machine
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 CentOS 7 image for installation.
ISO images must be available in the myisos
ISO domain for the virtual
machines to use. oVirt 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 can be used to request the list of files from the ISO storage domain:
GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1 Accept: application/xml
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request GET \ --header 'Version: 4' \ --header 'Accept: application/xml' \ https://myengine.example.com/ovirt-engine/api/storagedomains/006/files
The server returns the following list of objects of type File, one for each available ISO (or floppy) image:
<files>
<file href="..." id="CentOS-7-x86_64-Minimal.iso">
<name>CentOS-7-x86_64-Minimal.iso</name>
</file>
...
</files>
An API user attaches the CentOS-7-x86_64-Minimal.iso
to our example
virtual machine. Attaching an ISO image is equivalent to using the
Change CD button in the administration or user portal applications.
The request should be like this:
PUT /ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1 Accept: application/xml Content-type: application/xml
The request body should be an object of type Cdrom
containing an inner file
attribute to indicate the identifier of the
ISO (or floppy) image:
<cdrom>
<file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request PUT \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <cdrom> <file id="CentOS-7-x86_64-Minimal.iso"/> </cdrom> ' \ https://myengine.example.com/ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000
For more details see the documentation of the service that manages virtual machine CD-ROMS.
3.13. Example: Start the virtual machine
The virtual environment is complete and the virtual machine contains all necessary components to function. This example starts the virtual machine using the start method.
The request should be like this:
POST /ovirt-engine/api/vms/007/start HTTP/1.1 Accept: application/xml Content-type: application/xml
The request body should be like this:
<action>
<vm>
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action>
Same request, using the curl
command:
# curl \ --cacert '/etc/pki/ovirt-engine/ca.pem' \ --user 'admin@internal:mypassword' \ --request POST \ --header 'Version: 4' \ --header 'Content-Type: application/xml' \ --header 'Accept: application/xml' \ --data ' <action> <vm> <os> <boot> <devices> <device>cdrom</device> </devices> </boot> </os> </vm> </action> ' \ https://myengine.example.com/ovirt-engine/api/vms/007/start
The additional request body sets the virtual machine’s boot device to CD-ROM for this boot only. This enables the virtual machine to install the operating system from the attached ISO image. The boot device reverts back to disk for all future boots.
4. Requests
This section enumerates all the requests that are available in the API.
-
DELETE /clusters/{cluster:id}/affinitygroups/{group:id}/vms/{vm:id}
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/getprofilestatistics
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks
-
GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks
-
DELETE /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/activate
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/migrate
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/stopmigrate
-
GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}
-
DELETE /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/replace
-
GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics
-
GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics/{statistic:id}
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/rebalance
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/resetalloptions
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/resetoption
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/setoption
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/start
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/startprofile
-
GET /clusters/{cluster:id}/glustervolumes/{volume:id}/statistics
-
GET /clusters/{cluster:id}/glustervolumes/{volume:id}/statistics/{statistic:id}
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/stopprofile
-
POST /clusters/{cluster:id}/glustervolumes/{volume:id}/stoprebalance
-
GET /clusters/{cluster:id}/networkfilters/{networkfilter:id}
-
DELETE /cpuprofiles/{profile:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}
-
PUT /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}/vms
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}/vms
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}/vms/{vm:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles/{profile:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles/{profile:id}
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}/disable
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}/enable
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}/resolve
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/getprofilestatistics
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/activate
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/migrate
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/stopmigrate
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/replace
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics/{statistic:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/rebalance
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/resetalloptions
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/resetoption
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/setoption
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/start
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/startprofile
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/statistics
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/statistics/{statistic:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/stop
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/stopprofile
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/stoprebalance
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networkfilters
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networkfilters/{networkfilter:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/networks
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networks
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networks/{network:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/networks/{network:id}
-
PUT /datacenters/{datacenter:id}/clusters/{cluster:id}/networks/{network:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions
-
GET /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/clusters/{cluster:id}/resetemulatedmachine
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}
-
POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}
-
PUT /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}
-
POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels/{label:id}
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels/{label:id}
-
POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}
-
POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections
-
GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections/{storageconnection:id}
-
PUT /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections/{storageconnection:id}
-
DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections/{storageconnection:id}
-
POST /datacenters/{datacenter:id}/networks/{network:id}/networklabels
-
GET /datacenters/{datacenter:id}/networks/{network:id}/networklabels
-
GET /datacenters/{datacenter:id}/networks/{network:id}/networklabels/{label:id}
-
DELETE /datacenters/{datacenter:id}/networks/{network:id}/networklabels/{label:id}
-
POST /datacenters/{datacenter:id}/networks/{network:id}/permissions
-
GET /datacenters/{datacenter:id}/networks/{network:id}/permissions
-
GET /datacenters/{datacenter:id}/networks/{network:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/networks/{network:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles
-
GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles
-
GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}
-
DELETE /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}
-
POST /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions
-
GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions
-
GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}
-
GET /datacenters/{datacenter:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/quotas/{quota:id}/permissions
-
GET /datacenters/{datacenter:id}/quotas/{quota:id}/permissions
-
GET /datacenters/{datacenter:id}/quotas/{quota:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/quotas/{quota:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits
-
GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits
-
GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits/{limit:id}
-
DELETE /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits/{limit:id}
-
POST /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits
-
GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits
-
GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits/{limit:id}
-
DELETE /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits/{limit:id}
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}
-
DELETE /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/activate
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/deactivate
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks
-
PUT /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}
-
DELETE /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/copy
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/export
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/move
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}
-
DELETE /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/register
-
POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/sparsify
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/statistics
-
GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/statistics/{statistic:id}
-
GET /diskprofiles/{diskprofile:id}/permissions/{permission:id}
-
DELETE /diskprofiles/{diskprofile:id}/permissions/{permission:id}
-
GET /externalhostproviders/{provider:id}/certificates/{certificate:id}
-
GET /externalhostproviders/{provider:id}/computeresources/{resource:id}
-
GET /externalhostproviders/{provider:id}/discoveredhosts/{host:id}
-
GET /externalhostproviders/{provider:id}/hostgroups/{group:id}
-
POST /externalhostproviders/{provider:id}/importcertificates
-
DELETE /groups/{group:id}/roles/{role:id}/permits/{permit:id}
-
GET /hosts/{host:id}/nics/{nic:id}/networkattachments/{attachment:id}
-
PUT /hosts/{host:id}/nics/{nic:id}/networkattachments/{attachment:id}
-
DELETE /hosts/{host:id}/nics/{nic:id}/networkattachments/{attachment:id}
-
DELETE /hosts/{host:id}/nics/{nic:id}/networklabels/{label:id}
-
GET /hosts/{host:id}/nics/{nic:id}/statistics/{statistic:id}
-
POST /hosts/{host:id}/nics/{nic:id}/updatevirtualfunctionsconfiguration
-
POST /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels
-
GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels
-
GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels/{label:id}
-
DELETE /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels/{label:id}
-
POST /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks
-
GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks
-
GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks/{network:id}
-
DELETE /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks/{network:id}
-
GET /hosts/{host:id}/numanodes/{node:id}/statistics/{statistic:id}
-
GET /hosts/{host:id}/storageconnectionextensions/{storageconnectionextension:id}
-
PUT /hosts/{host:id}/storageconnectionextensions/{storageconnectionextension:id}
-
DELETE /hosts/{host:id}/storageconnectionextensions/{storageconnectionextension:id}
-
GET /hosts/{host:id}/unmanagednetworks/{unmanagednetwork:id}
-
DELETE /hosts/{host:id}/unmanagednetworks/{unmanagednetwork:id}
-
GET /instancetypes/{instancetype:id}/graphicsconsoles/{console:id}
-
DELETE /instancetypes/{instancetype:id}/graphicsconsoles/{console:id}
-
GET /instancetypes/{instancetype:id}/watchdogs/{watchdog:id}
-
PUT /instancetypes/{instancetype:id}/watchdogs/{watchdog:id}
-
DELETE /instancetypes/{instancetype:id}/watchdogs/{watchdog:id}
-
GET /jobs/{job:id}/steps/{step:id}/statistics/{statistic:id}
-
POST /networks/{network:id}/vnicprofiles/{profile:id}/permissions
-
GET /networks/{network:id}/vnicprofiles/{profile:id}/permissions
-
GET /networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}
-
DELETE /networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}
-
GET /openstackimageproviders/{provider:id}/certificates/{certificate:id}
-
GET /openstackimageproviders/{provider:id}/images/{image:id}
-
POST /openstackimageproviders/{provider:id}/images/{image:id}/import
-
POST /openstackimageproviders/{provider:id}/importcertificates
-
POST /openstackimageproviders/{provider:id}/testconnectivity
-
GET /openstacknetworkproviders/{provider:id}/certificates/{certificate:id}
-
POST /openstacknetworkproviders/{provider:id}/importcertificates
-
GET /openstacknetworkproviders/{provider:id}/networks/{network:id}
-
POST /openstacknetworkproviders/{provider:id}/networks/{network:id}/import
-
POST /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets
-
GET /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets
-
GET /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets/{subnet:id}
-
DELETE /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets/{subnet:id}
-
POST /openstacknetworkproviders/{provider:id}/testconnectivity
-
POST /openstackvolumeproviders/{provider:id}/authenticationkeys
-
GET /openstackvolumeproviders/{provider:id}/authenticationkeys
-
GET /openstackvolumeproviders/{provider:id}/authenticationkeys/{key:id}
-
PUT /openstackvolumeproviders/{provider:id}/authenticationkeys/{key:id}
-
DELETE /openstackvolumeproviders/{provider:id}/authenticationkeys/{key:id}
-
GET /openstackvolumeproviders/{provider:id}/certificates/{certificate:id}
-
POST /openstackvolumeproviders/{provider:id}/importcertificates
-
POST /openstackvolumeproviders/{provider:id}/testconnectivity
-
GET /openstackvolumeproviders/{provider:id}/volumetypes/{type:id}
-
DELETE /schedulingpolicies/{policy:id}/balances/{balance:id}
-
GET /storagedomains/{storagedomain:id}/diskprofiles/{profile:id}
-
DELETE /storagedomains/{storagedomain:id}/diskprofiles/{profile:id}
-
POST /storagedomains/{storagedomain:id}/disks/{disk:id}/copy
-
POST /storagedomains/{storagedomain:id}/disks/{disk:id}/export
-
POST /storagedomains/{storagedomain:id}/disks/{disk:id}/move
-
POST /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions
-
GET /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions
-
GET /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}
-
DELETE /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}
-
POST /storagedomains/{storagedomain:id}/disks/{disk:id}/sparsify
-
GET /storagedomains/{storagedomain:id}/disks/{disk:id}/statistics
-
GET /storagedomains/{storagedomain:id}/disks/{disk:id}/statistics/{statistic:id}
-
GET /storagedomains/{storagedomain:id}/disksnapshots/{snapshot:id}
-
DELETE /storagedomains/{storagedomain:id}/disksnapshots/{snapshot:id}
-
POST /storagedomains/{storagedomain:id}/images/{image:id}/import
-
GET /storagedomains/{storagedomain:id}/permissions/{permission:id}
-
DELETE /storagedomains/{storagedomain:id}/permissions/{permission:id}
-
GET /storagedomains/{storagedomain:id}/storageconnections/{connection:id}
-
DELETE /storagedomains/{storagedomain:id}/storageconnections/{connection:id}
-
GET /storagedomains/{storagedomain:id}/templates/{template:id}
-
DELETE /storagedomains/{storagedomain:id}/templates/{template:id}
-
GET /storagedomains/{storagedomain:id}/templates/{template:id}/disks
-
GET /storagedomains/{storagedomain:id}/templates/{template:id}/disks/{disk:id}
-
POST /storagedomains/{storagedomain:id}/templates/{template:id}/import
-
POST /storagedomains/{storagedomain:id}/templates/{template:id}/register
-
GET /storagedomains/{storagedomain:id}/vms/{vm:id}/diskattachments
-
GET /storagedomains/{storagedomain:id}/vms/{vm:id}/diskattachments/{attachment:id}
-
GET /storagedomains/{storagedomain:id}/vms/{vm:id}/disks/{disk:id}
-
POST /storagedomains/{storagedomain:id}/vms/{vm:id}/register
-
GET /templates/{template:id}/diskattachments/{attachment:id}
-
DELETE /templates/{template:id}/diskattachments/{attachment:id}
-
DELETE /templates/{template:id}/graphicsconsoles/{console:id}
-
POST /vms/{vm:id}/graphicsconsoles/{console:id}/remoteviewerconnectionfile
-
GET /vms/{vm:id}/nics/{nic:id}/networkfilterparameters/{parameter:id}
-
PUT /vms/{vm:id}/nics/{nic:id}/networkfilterparameters/{parameter:id}
-
DELETE /vms/{vm:id}/nics/{nic:id}/networkfilterparameters/{parameter:id}
-
GET /vms/{vm:id}/nics/{nic:id}/reporteddevices/{reporteddevice:id}
-
DELETE /vnicprofiles/{profile:id}/permissions/{permission:id}
5. Services
This section enumerates all the services that are available in the API.
5.1. AffinityGroup
This service manages a single affinity group.
Name | Summary |
---|---|
|
Retrieve the affinity group details. |
|
Remove the affinity group. |
|
Update the affinity group. |
5.1.1. get GET
Retrieve the affinity group details.
<affinity_group id="00000000-0000-0000-0000-000000000000">
<name>AF_GROUP_001</name>
<cluster id="00000000-0000-0000-0000-000000000000"/>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The affinity group. |
5.1.2. remove DELETE
Remove the affinity group.
DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.2. AffinityGroupVm
This service manages a single virtual machine to affinity group assignment.
Name | Summary |
---|---|
|
Remove this virtual machine from the affinity group. |
5.3. AffinityGroupVms
This service manages a collection of all virtual machines assigned to an affinity group.
Name | Summary |
---|---|
|
Add a virtual machine to the affinity group. |
|
List all virtual machines assigned to this affinity group. |
5.3.1. add POST
Add a virtual machine to the affinity group.
For example to add the virtual machine 000-000 to affinity group 123-456 send a request to:
POST /ovirt-engine/api/clusters/000-000/affinitygroups/123-456/vms
With the following body:
<vm id="000-000"/>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.4. AffinityGroups
Affinity groups service manages virtual machine relationships and dependencies.
Name | Summary |
---|---|
|
Create a new affinity group. |
|
List existing affinity groups. |
5.4.1. add POST
Create a new affinity group.
Post a request like in the example below to create a new affinity group:
POST /ovirt-engine/api/clusters/000-000/affinitygroups
And use the following example in its body:
<affinity_group>
<name>AF_GROUP_001</name>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The affinity group object to create. |
5.5. AffinityLabel
Single affinity label details.
Name | Summary |
---|---|
|
Retrieves details about a label. |
|
Removes a label from system and clears all assignments of the removed label. |
|
Updates a label. |
5.5.1. get GET
Retrieves details about a label.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.6. AffinityLabelHost
This service represents a host that has a specific label when accessed through the affinitylabels/hosts subcollection.
Name | Summary |
---|---|
|
Retrieves details about a host that has this label assigned. |
|
Remove a label from a host. |
5.7. AffinityLabelHosts
This service represents list of hosts that have a specific label when accessed through the affinitylabels/hosts subcollection.
Name | Summary |
---|---|
|
Add a label to a host. |
|
List all hosts with the label. |
5.7.1. add POST
Add a label to a host.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.8. AffinityLabelVm
This service represents a vm that has a specific label when accessed through the affinitylabels/vms subcollection.
Name | Summary |
---|---|
|
Retrieves details about a vm that has this label assigned. |
|
Remove a label from a vm. |
5.9. AffinityLabelVms
This service represents list of vms that have a specific label when accessed through the affinitylabels/vms subcollection.
Name | Summary |
---|---|
|
Add a label to a vm. |
|
List all vms with the label. |
5.9.1. add POST
Add a label to a vm.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.10. AffinityLabels
Manages the affinity labels available in the system.
Name | Summary |
---|---|
|
Creates a new label. |
|
Lists all labels present in the system. |
5.10.1. add POST
Creates a new label. The label is automatically attached to all entities mentioned in the vms or hosts lists.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.11. Area
This annotation is intended to specify what oVirt area is the annotated concept related to. Currently the following areas are in use, and they are closely related to the oVirt teams, but not necessarily the same:
-
Infrastructure
-
Network
-
SLA
-
Storage
-
Virtualization
A concept may be associated to more than one area, or to no area.
The value of this annotation is intended for reporting only, and it doesn’t affect at all the generated code or the validity of the model
5.12. AssignedAffinityLabel
This service represents one label to entity assignment when accessed using the entities/affinitylabels subcollection.
Name | Summary |
---|---|
|
Retrieves details about the attached label. |
|
Removes the label from an entity. |
5.13. AssignedAffinityLabels
This service is used to list and manipulate affinity labels that are assigned to supported entities when accessed using entities/affinitylabels.
Name | Summary |
---|---|
|
Attaches a label to an entity. |
|
Lists all labels that are attached to an entity. |
5.13.1. add POST
Attaches a label to an entity.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.14. AssignedCpuProfile
Name | Summary |
---|---|
|
|
|
5.15. AssignedCpuProfiles
Name | Summary |
---|---|
|
|
|
5.16. AssignedDiskProfile
Name | Summary |
---|---|
|
|
|
5.17. AssignedDiskProfiles
Name | Summary |
---|---|
|
|
|
5.18. AssignedNetwork
Name | Summary |
---|---|
|
|
|
|
|
5.19. AssignedNetworks
Name | Summary |
---|---|
|
|
|
5.20. AssignedPermissions
Represents a permission sub-collection, scoped by user, group or some entity type.
Name | Summary |
---|---|
|
Assign a new permission to a user or group for specific entity. |
|
List all the permissions of the specific entity. |
5.20.1. add POST
Assign a new permission to a user or group for specific entity.
For example, to assign the UserVmManager
role to the virtual machine with id 123
to the user with id 456
send a request like this:
POST /ovirt-engine/api/vms/123/permissions
With a request body like this:
<permission>
<role>
<name>UserVmManager</name>
</role>
<user id="456"/>
</permission>
To assign the SuperUser
role to the system to the user with id 456
send a request like this:
POST /ovirt-engine/api/permissions
With a request body like this:
<permission>
<role>
<name>SuperUser</name>
</role>
<user id="456"/>
</permission>
If you want to assign permission to the group instead of the user please replace the user
element with the
group
element with proper id
of the group. For example to assign the UserRole
role to the cluster with
id 123
to the group with id 789
send a request like this:
POST /ovirt-engine/api/clusters/123/permissions
With a request body like this:
<permission>
<role>
<name>UserRole</name>
</role>
<group id="789"/>
</permission>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The permission. |
5.20.2. list GET
List all the permissions of the specific entity.
For example to list all the permissions of the cluster with id 123
send a request like this:
GET /ovirt-engine/api/clusters/123/permissions
<permissions>
<permission id="456">
<cluster id="123"/>
<role id="789"/>
<user id="451"/>
</permission>
<permission id="654">
<cluster id="123"/>
<role id="789"/>
<group id="127"/>
</permission>
</permissions>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The list of permissions. |
5.21. AssignedRoles
Represents a roles sub-collection, for example scoped by user.
Name | Summary |
---|---|
|
5.22. AssignedTag
A service to manage assignment of specific tag to specific entities in system.
Name | Summary |
---|---|
|
Gets the information about the assigned tag. |
|
Unassign tag from specific entity in the system. |
5.22.1. get GET
Gets the information about the assigned tag.
For example to retrieve the information about the tag with the id 456
which is assigned to virtual machine
with id 123
send a request like this:
GET /ovirt-engine/api/vms/123/tags/456
<tag href="/ovirt-engine/api/tags/456" id="456">
<name>root</name>
<description>root</description>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The assigned tag. |
5.22.2. remove DELETE
Unassign tag from specific entity in the system.
For example to unassign the tag with id 456
from virtual machine with id 123
send a request like this:
DELETE /ovirt-engine/api/vms/123/tags/456
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.23. AssignedTags
A service to manage collection of assignment of tags to specific entities in system.
Name | Summary |
---|---|
|
Assign tag to specific entity in the system. |
|
List all tags assigned to the specific entity. |
5.23.1. add POST
Assign tag to specific entity in the system.
For example to assign tag mytag
to virtual machine with the id 123
send a request like this:
POST /ovirt-engine/api/vms/123/tags
With a request body like this:
<tag>
<name>mytag</name>
</tag>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The assigned tag. |
5.23.2. list GET
List all tags assigned to the specific entity.
For example to list all the tags of the virtual machine with id 123
send a request like this:
GET /ovirt-engine/api/vms/123/tags
<tags>
<tag href="/ovirt-engine/api/tags/222" id="222">
<name>mytag</name>
<description>mytag</description>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>
</tags>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Sets the maximum number of tags to return. |
|
|
Out |
The list of assigned tags. |
5.24. AssignedVnicProfile
Name | Summary |
---|---|
|
|
|
5.25. AssignedVnicProfiles
Name | Summary |
---|---|
|
|
|
5.26. AttachedStorageDomain
Name | Summary |
---|---|
|
This operation activates an attached storage domain. |
|
This operation deactivates an attached storage domain. |
|
|
|
5.26.1. activate POST
This operation activates an attached storage domain. Once the storage domain is activated it is ready for use with the data center.
POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate
The activate action does not take any action specific parameters,
so the request body should contain an empty action
:
<action/>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the activation should be performed asynchronously. |
5.26.2. deactivate POST
This operation deactivates an attached storage domain. Once the storage domain is deactivated it will not be used with the data center.
POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate
The deactivate action does not take any action specific parameters,
so the request body should contain an empty action
:
<action/>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the deactivation should be performed asynchronously. |
5.27. AttachedStorageDomainDisk
Manages a single disk available in a storage domain attached to a data center.
Since version 4.2 of the engine this service is intended only to list disks available in the storage domain, and to register unregistered disks. All the other operations, like copying a disk, moving a disk, etc, have been deprecated and will be removed in the future. To perform those operations use the service that manages all the disks of the system, or the service that manages an specific disk. |
Name | Summary |
---|---|
|
Copies a disk to the specified storage domain. |
|
Exports a disk to an export storage domain. |
|
Retrieves the description of the disk. |
|
Moves a disk to another storage domain. |
|
Registers an unregistered disk. |
|
Removes a disk. |
|
Sparsify the disk. |
|
Updates the disk. |
5.27.1. copy POST
Copies a disk to the specified storage domain.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To copy a disk use the copy operation of the service that manages that disk. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Description of the resulting disk. |
|
|
In |
The storage domain where the new disk will be created. |
5.27.2. export POST
Exports a disk to an export storage domain.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To export a disk use the export operation of the service that manages that disk. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
The export storage domain where the disk should be exported to. |
5.27.3. get GET
Retrieves the description of the disk.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The description of the disk. |
5.27.4. move POST
Moves a disk to another storage domain.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To move a disk use the move operation of the service that manages that disk. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the move should be performed asynchronously. |
|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
In |
The storage domain where the disk will be moved to. |
5.27.6. remove DELETE
Removes a disk.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk. |
5.27.7. sparsify POST
Sparsify the disk.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk. |
5.27.8. update PUT
Updates the disk.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To update a disk use the update operation of the service that manages that disk. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The update to apply to the disk. |
5.28. AttachedStorageDomainDisks
Manages the collection of disks available inside an storage domain that is attached to a data center.
Name | Summary |
---|---|
|
Adds or registers a disk. |
|
Retrieve the list of disks that are available in the storage domain. |
5.28.1. add POST
Adds or registers a disk.
Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To add a new disk use the add operation of the service that manages the disks of the system. To register an unregistered disk use the register operation of the service that manages that disk. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The disk to add or register. |
|
|
In |
Indicates if a new disk should be added or if an existing unregistered disk should be registered. |
unregistered
Indicates if a new disk should be added or if an existing unregistered disk should be registered. If the
value is true
then the identifier of the disk to register needs to be provided. For example, to register
the disk with id 456
send a request like this:
POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true
With a request body like this:
<disk id="456"/>
If the value is false
then a new disk will be created in the storage domain. In that case the
provisioned_size
, format
and name
attributes are mandatory. For example, to create a new
copy on write disk of 1 GiB, send a request like this:
POST /ovirt-engine/api/storagedomains/123/disks
With a request body like this:
<disk>
<name>mydisk</name>
<format>cow</format>
<provisioned_size>1073741824</provisioned_size>
</disk>
The default value is false
.
5.29. AttachedStorageDomains
Name | Summary |
---|---|
|
|
|
5.30. Balance
Name | Summary |
---|---|
|
|
|
5.30.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
||
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
5.31. Balances
Name | Summary |
---|---|
|
|
|
5.32. Bookmark
A service to manage a bookmark.
Name | Summary |
---|---|
|
Get a bookmark. |
|
Remove a bookmark. |
|
Update a bookmark. |
5.32.1. get GET
Get a bookmark.
An example for getting a bookmark:
GET /ovirt-engine/api/bookmarks/123
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
<name>example_vm</name>
<value>vm: name=example*</value>
</bookmark>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The requested bookmark. |
5.32.2. remove DELETE
Remove a bookmark.
An example for removing a bookmark:
DELETE /ovirt-engine/api/bookmarks/123
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.32.3. update PUT
Update a bookmark.
An example for updating a bookmark:
PUT /ovirt-engine/api/bookmarks/123
With the request body:
<bookmark>
<name>new_example_vm</name>
<value>vm: name=new_example*</value>
</bookmark>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
The updated bookmark. |
5.33. Bookmarks
A service to manage bookmarks.
Name | Summary |
---|---|
|
Adding a new bookmark. |
|
Listing all the available bookmarks. |
5.33.1. add POST
Adding a new bookmark.
Example of adding a bookmark:
POST /ovirt-engine/api/bookmarks
<bookmark>
<name>new_example_vm</name>
<value>vm: name=new_example*</value>
</bookmark>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The added bookmark. |
5.33.2. list GET
Listing all the available bookmarks.
Example of listing bookmarks:
GET /ovirt-engine/api/bookmarks
<bookmarks>
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
<name>database</name>
<value>vm: name=database*</value>
</bookmark>
<bookmark href="/ovirt-engine/api/bookmarks/456" id="456">
<name>example</name>
<value>vm: name=example*</value>
</bookmark>
</bookmarks>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The list of available bookmarks. |
|
|
In |
Sets the maximum number of bookmarks to return. |
5.34. Cluster
A service to manage specific cluster.
Name | Summary |
---|---|
|
Get information about the cluster. |
|
Removes cluster from the system. |
|
|
|
Updates information about the cluster. |
5.34.1. get GET
Get information about the cluster.
An example of getting a cluster:
GET /ovirt-engine/api/clusters/123
<cluster href="/ovirt-engine/api/clusters/123" id="123">
<actions>
<link href="/ovirt-engine/api/clusters/123/resetemulatedmachine" rel="resetemulatedmachine"/>
</actions>
<name>Default</name>
<description>The default server cluster</description>
<link href="/ovirt-engine/api/clusters/123/networks" rel="networks"/>
<link href="/ovirt-engine/api/clusters/123/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/clusters/123/glustervolumes" rel="glustervolumes"/>
<link href="/ovirt-engine/api/clusters/123/glusterhooks" rel="glusterhooks"/>
<link href="/ovirt-engine/api/clusters/123/affinitygroups" rel="affinitygroups"/>
<link href="/ovirt-engine/api/clusters/123/cpuprofiles" rel="cpuprofiles"/>
<ballooning_enabled>false</ballooning_enabled>
<cpu>
<architecture>x86_64</architecture>
<type>Intel Penryn Family</type>
</cpu>
<error_handling>
<on_error>migrate</on_error>
</error_handling>
<fencing_policy>
<enabled>true</enabled>
<skip_if_connectivity_broken>
<enabled>false</enabled>
<threshold>50</threshold>
</skip_if_connectivity_broken>
<skip_if_sd_active>
<enabled>false</enabled>
</skip_if_sd_active>
</fencing_policy>
<gluster_service>false</gluster_service>
<ha_reservation>false</ha_reservation>
<ksm>
<enabled>true</enabled>
<merge_across_nodes>true</merge_across_nodes>
</ksm>
<maintenance_reason_required>false</maintenance_reason_required>
<memory_policy>
<over_commit>
<percent>100</percent>
</over_commit>
<transparent_hugepages>
<enabled>true</enabled>
</transparent_hugepages>
</memory_policy>
<migration>
<auto_converge>inherit</auto_converge>
<bandwidth>
<assignment_method>auto</assignment_method>
</bandwidth>
<compressed>inherit</compressed>
</migration>
<optional_reason>false</optional_reason>
<required_rng_sources>
<required_rng_source>random</required_rng_source>
</required_rng_sources>
<scheduling_policy href="/ovirt-engine/api/schedulingpolicies/456" id="456"/>
<threads_as_cores>false</threads_as_cores>
<trusted_service>false</trusted_service>
<tunnel_migration>false</tunnel_migration>
<version>
<major>4</major>
<minor>0</minor>
</version>
<virt_service>true</virt_service>
<data_center href="/ovirt-engine/api/datacenters/111" id="111"/>
</cluster>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
||
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
5.34.2. remove DELETE
Removes cluster from the system.
DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.34.3. resetemulatedmachine POST
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the reset should be performed asynchronously. |
5.34.4. update PUT
Updates information about the cluster.
Only specified fields are updated, others remain unchanged.
E.g. update cluster’s CPU:
PUT /ovirt-engine/api/clusters/123
With request body like:
<cluster>
<cpu>
<type>Intel Haswell-noTSX Family</type>
</cpu>
</cluster>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
5.35. ClusterLevel
Provides information about a specific cluster level. See the ClusterLevels service for more information.
Name | Summary |
---|---|
|
Provides the information about the capabilities of the specific cluster level managed by this service. |
5.35.1. get GET
Provides the information about the capabilities of the specific cluster level managed by this service.
For example, to find what CPU types are supported by level 3.6 you can send a request like this:
GET /ovirt-engine/api/clusterlevels/3.6
That will return a ClusterLevel object containing the supported CPU types, and other information which describes the cluster level:
<cluster_level id="3.6">
<cpu_types>
<cpu_type>
<name>Intel Conroe Family</name>
<level>3</level>
<architecture>x86_64</architecture>
</cpu_type>
...
</cpu_types>
<permits>
<permit id="1">
<name>create_vm</name>
<administrative>false</administrative>
</permit>
...
</permits>
</cluster_level>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Retreived cluster level. |
5.36. ClusterLevels
Provides information about the capabilities of different cluster levels supported by the engine. Version 4.0 of the engine supports levels 4.0 and 3.6. Each of these levels support different sets of CPU types, for example. This service provides that information.
Name | Summary |
---|---|
|
Lists the cluster levels supported by the system. |
5.36.1. list GET
Lists the cluster levels supported by the system.
GET /ovirt-engine/api/clusterlevels
This will return a list of available cluster levels.
<cluster_levels>
<cluster_level id="4.0">
...
</cluster_level>
...
</cluster_levels>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Retrieved cluster levels. |
5.37. Clusters
A service to manage clusters.
Name | Summary |
---|---|
|
Creates a new cluster. |
|
5.37.1. add POST
Creates a new cluster.
This requires the name
, cpu.type
and data_center
attributes. Identify the data center with either the id
or name
attributes.
POST /ovirt-engine/api/clusters
With a request body like this:
<cluster>
<name>mycluster</name>
<cpu>
<type>Intel Penryn Family</type>
</cpu>
<data_center id="123"/>
</cluster>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.37.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
In |
Sets the maximum number of clusters to return. |
|
|
In |
A query string used to restrict the returned clusters. |
5.38. Copyable
Name | Summary |
---|---|
|
5.39. CpuProfile
Name | Summary |
---|---|
|
|
|
|
|
5.39.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.40. CpuProfiles
Name | Summary |
---|---|
|
|
|
5.41. DataCenter
A service to manage a data center.
Name | Summary |
---|---|
|
Get a data center. |
|
Removes the data center. |
|
Updates the data center. |
5.41.1. get GET
Get a data center.
An example of getting a data center:
GET /ovirt-engine/api/datacenters/123
<data_center href="/ovirt-engine/api/datacenters/123" id="123">
<name>Default</name>
<description>The default Data Center</description>
<link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
<link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
<link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
<link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
<link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<storage_format>v3</storage_format>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
<mac_pool href="/ovirt-engine/api/macpools/456" id="456"/>
</data_center>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
||
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
5.41.2. remove DELETE
Removes the data center.
DELETE /ovirt-engine/api/datacenters/123
Without any special parameters, the storage domains attached to the data center are detached and then removed from the storage. If something fails when performing this operation, for example if there is no host available to remove the storage domains from the storage, the complete operation will fail.
If the force
parameter is true
then the operation will always succeed, even if something fails while removing
one storage domain, for example. The failure is just ignored and the data center is removed from the database
anyway.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
|
|
In |
Indicates if the operation should succeed, and the storage domain removed from the database, even if something fails during the operation. |
5.41.3. update PUT
Updates the data center.
The name
, description
, storage_type
, version
, storage_format
and mac_pool
elements are updatable
post-creation. For example, to change the name and description of data center 123
send a request like this:
PUT /ovirt-engine/api/datacenters/123
With a request body like this:
<data_center>
<name>myupdatedname</name>
<description>An updated description for the data center</description>
</data_center>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
The data center that is being updated. |
5.42. DataCenters
A service to manage data centers.
Name | Summary |
---|---|
|
Creates a new data center. |
|
Lists the data centers. |
5.42.1. add POST
Creates a new data center.
Creation of a new data center requires the name
and local
elements. For example, to create a data center
named mydc
that uses shared storage (NFS, iSCSI or fibre channel) send a request like this:
POST /ovirt-engine/api/datacenters
With a request body like this:
<data_center>
<name>mydc</name>
<local>false</local>
</data_center>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The data center that is being added. |
5.42.2. list GET
Lists the data centers.
The following request retrieves a representation of the data centers:
GET /ovirt-engine/api/datacenters
The above request performed with curl
:
curl \
--request GET \
--cacert /etc/pki/ovirt-engine/ca.pem \
--header "Version: 4" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
https://myengine.example.com/ovirt-engine/api/datacenters
This is what an example response could look like:
<data_center href="/ovirt-engine/api/datacenters/123" id="123">
<name>Default</name>
<description>The default Data Center</description>
<link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
<link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
<link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
<link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
<link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</data_center>
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 storage domains collection. The data center uses this collection to attach storage domains from the storage domains main collection.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
In |
Sets the maximum number of data centers to return. |
|
|
In |
A query string used to restrict the returned data centers. |
5.43. Disk
Manages a single disk.
Name | Summary |
---|---|
|
This operation copies a disk to the specified storage domain. |
|
Exports a disk to an export storage domain. |
|
Retrieves the description of the disk. |
|
Moves a disk to another storage domain. |
|
Removes a disk. |
|
Sparsify the disk. |
|
This operation updates the disk with the appropriate parameters. |
5.43.1. copy POST
This operation copies a disk to the specified storage domain.
For example, copy of a disk can be facilitated using the following request:
POST /ovirt-engine/api/disks/123/copy
With a request body like this:
<action>
<storage_domain id="456"/>
<disk>
<name>mydisk</name>
</disk>
</action>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the copy should be performed asynchronously. |
|
|
In |
Description of the resulting disk. |
|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
In |
The storage domain where the new disk will be created. |
disk
Description of the resulting disk. The only accepted value is the name
attribute, which will be the name
used for the new disk. For example, to copy disk 123
using myname
as the name for the new disk, send
a request like this:
POST /ovirt-engine/disks/123
With a request body like this:
<action>
<disk>
<name>mydisk<name>
</disk>
<storage_domain id="456"/>
</action>
storage_domain
The storage domain where the new disk will be created. Can be specified using the id
or name
attributes. For example, to copy a disk to the storage domain named mydata
send a request like this:
POST /ovirt-engine/api/storagedomains/123/disks/789
With a request body like this:
<action>
<storage_domain>
<name>mydata</name>
</storage_domain>
</action>
5.43.2. export POST
Exports a disk to an export storage domain.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the export should be performed asynchronously. |
|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
In |
The export storage domain where the disk should be exported to. |
5.43.3. get GET
Retrieves the description of the disk.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The description of the disk. |
5.43.4. move POST
Moves a disk to another storage domain.
For example, to move the disk with identifier 123
to a storage domain with identifier 456
send the following
request:
POST /ovirt-engine/api/disks/123/move
With the following request body:
<action>
<storage_domain id="456"/>
</action>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the move should be performed asynchronously. |
|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
In |
The storage domain where the disk will be moved to. |
5.43.5. remove DELETE
Removes a disk.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.43.6. sparsify POST
Sparsify the disk.
Sparsification frees space in the disk image that is not used by its filesystem. As a result, the image will occupy less space on the storage.
Currently sparsification works only on disks without snapshots. Disks having derived disks are also not allowed.
5.43.7. update PUT
This operation updates the disk with the appropriate parameters.
The only field that can be updated is qcow_version
.
For example, update disk can be facilitated using the following request:
PUT /ovirt-engine/api/disks/123
With a request body like this:
<disk>
<qcow_version>qcow2_v3</qcow_version>
</disk>
Since the backend operation is asynchronous the disk element which will be returned to the user might not be synced with the changed properties.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The update to apply to the disk. |
5.44. DiskAttachment
This service manages the attachment of a disk to a virtual machine.
Name | Summary |
---|---|
|
Returns the details of the attachment, including the bootable flag and link to the disk. |
|
Removes the disk attachment. |
|
Update the disk attachment and the disk properties within it. |
5.44.1. get GET
Returns the details of the attachment, including the bootable flag and link to the disk.
An example of getting a disk attachment:
GET /ovirt-engine/api/vms/123/diskattachments/456
<disk_attachment href="/ovirt-engine/api/vms/123/diskattachments/456" id="456">
<active>true</active>
<bootable>true</bootable>
<interface>virtio</interface>
<disk href="/ovirt-engine/api/disks/456" id="456"/>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</disk_attachment>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.44.2. remove DELETE
Removes the disk attachment.
This will only detach the disk from the virtual machine, but won’t remove it from
the system, unless the detach_only
parameter is false
.
An example of removing a disk attachment:
DELETE /ovirt-engine/api/vms/123/diskattachments/456?detach_only=true
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the disk should only be detached from the virtual machine, but not removed from the system. |
5.44.3. update PUT
Update the disk attachment and the disk properties within it.
PUT /vms/{vm:id}/disksattachments/{attachment:id}
<disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk>
<name>mydisk</name>
<provisioned_size>1024</provisioned_size>
...
</disk>
</disk_attachment>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.45. DiskAttachments
This service manages the set of disks attached to a virtual machine. Each attached disk is represented by a DiskAttachment, containing the bootable flag, the disk interface and the reference to the disk.
Name | Summary |
---|---|
|
Adds a new disk attachment to the virtual machine. |
|
List the disk that are attached to the virtual machine. |
5.45.1. add POST
Adds a new disk attachment to the virtual machine. The attachment
parameter can contain just a reference, if
the disk already exists:
<disk_attachment>
<bootable>true</bootable>
<pass_discard>true</pass_discard>
<interface>ide</interface>
<active>true</active>
<disk id="123"/>
</disk_attachment>
Or it can contain the complete representation of the disk, if the disk doesn’t exist yet:
<disk_attachment>
<bootable>true</bootable>
<pass_discard>true</pass_discard>
<interface>ide</interface>
<active>true</active>
<disk>
<name>mydisk</name>
<provisioned_size>1024</provisioned_size>
...
</disk>
</disk_attachment>
In this case the disk will be created and then attached to the virtual machine.
In both cases, use the following URL for a virtual machine with an id 345
:
POST /ovirt-engine/api/vms/345/diskattachments
The server accepts requests that don’t contain the active attribute, but the effect is
undefined. In some cases the disk will be automatically activated and in other cases it won’t. To
avoid issues it is strongly recommended to always include the active attribute with the desired
value.
|
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.46. DiskProfile
Name | Summary |
---|---|
|
|
|
|
|
5.46.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.47. DiskProfiles
Name | Summary |
---|---|
|
|
|
5.48. DiskSnapshot
Name | Summary |
---|---|
|
|
|
5.49. DiskSnapshots
Name | Summary |
---|---|
|
5.50. Disks
Manages the collection of disks available in the system.
Name | Summary |
---|---|
|
Adds a new floating disk. |
|
Get list of disks. |
5.50.1. add POST
Adds a new floating disk.
There are three types of disks that can be added - disk image, direct LUN and Cinder disk.
Adding a new image disk:
When creating a new floating image Disk, the API requires the storage_domain
, provisioned_size
and format
attributes.
To create a new floating image disk with specified provisioned_size
, format
and name
on a storage domain
with an id 123
, send a request as follows:
POST /ovirt-engine/api/disks
With a request body as follows:
<disk>
<storage_domains>
<storage_domain id="123"/>
</storage_domains>
<name>mydisk</name>
<provisioned_size>1048576</provisioned_size>
<format>cow</format>
</disk>
Adding a new direct LUN disk:
When adding a new floating direct LUN via the API, there are two flavors that can be used:
-
With a
host
element - in this case, the host is used for sanity checks (e.g., that the LUN is visible) and to retrieve basic information about the LUN (e.g., size and serial). -
Without a
host
element - in this case, the operation is a database-only operation, and the storage is never accessed.
To create a new floating direct LUN disk with a host
element with an id 123
, specified alias
, type
and
logical_unit
with an id 456
(that has the attributes address
, port
and target
),
send a request as follows:
POST /ovirt-engine/api/disks
With a request body as follows:
<disk>
<alias>mylun</alias>
<lun_storage>
<host id="123"/>
<type>iscsi</type>
<logical_units>
<logical_unit id="456">
<address>10.35.10.20</address>
<port>3260</port>
<target>iqn.2017-01.com.myhost:444</target>
</logical_unit>
</logical_units>
</lun_storage>
</disk>
To create a new floating direct LUN disk without using a host, remove the host
element.
Adding a new Cinder disk:
To create a new floating Cinder disk, send a request as follows:
POST /ovirt-engine/api/disks
With a request body as follows:
<disk>
<openstack_volume_type>
<name>myceph</name>
</openstack_volume_type>
<storage_domains>
<storage_domain>
<name>cinderDomain</name>
</storage_domain>
</storage_domains>
<provisioned_size>1073741824</provisioned_size>
<interface>virtio</interface>
<format>raw</format>
</disk>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The disk. |
5.50.2. list GET
Get list of disks.
GET /ovirt-engine/api/disks
You will get a XML response which will look like this one:
<disks>
<disk id="123">
<actions>...</actions>
<name>MyDisk</name>
<description>MyDisk description</description>
<link href="/ovirt-engine/api/disks/123/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/disks/123/statistics" rel="statistics"/>
<actual_size>5345845248</actual_size>
<alias>MyDisk alias</alias>
...
<status>ok</status>
<storage_type>image</storage_type>
<wipe_after_delete>false</wipe_after_delete>
<disk_profile id="123"/>
<quota id="123"/>
<storage_domains>...</storage_domains>
</disk>
...
</disks>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
List of retrieved disks. |
|
|
In |
Sets the maximum number of disks to return. |
|
|
In |
A query string used to restrict the returned disks. |
5.51. Domain
A service to view details of an authentication domain in the system.
Name | Summary |
---|---|
|
Gets the authentication domain information. |
5.51.1. get GET
Gets the authentication domain information.
Usage:
GET /ovirt-engine/api/domains/5678
Will return the domain information:
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
<link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
<link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
<link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/>
<link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/>
</domain>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The authentication domain. |
5.52. DomainGroup
Name | Summary |
---|---|
|
5.53. DomainGroups
Name | Summary |
---|---|
|
5.53.1. list GET
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Sets the maximum number of groups to return. |
|
|
In |
A query string used to restrict the returned groups. |
5.54. DomainUser
A service to view a domain user in the system.
Name | Summary |
---|---|
|
Gets the domain user information. |
5.54.1. get GET
Gets the domain user information.
Usage:
GET /ovirt-engine/api/domains/5678/users/1234
Will return the domain user information:
<user href="/ovirt-engine/api/users/1234" id="1234">
<name>admin</name>
<namespace>*</namespace>
<principal>admin</principal>
<user_name>admin@internal-authz</user_name>
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
</domain>
<groups/>
</user>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The domain user. |
5.55. DomainUsers
A service to list all domain users in the system.
Name | Summary |
---|---|
|
List all the users in the domain. |
5.55.1. list GET
List all the users in the domain.
Usage:
GET /ovirt-engine/api/domains/5678/users
Will return the list of users in the domain:
<users>
<user href="/ovirt-engine/api/domains/5678/users/1234" id="1234">
<name>admin</name>
<namespace>*</namespace>
<principal>admin</principal>
<user_name>admin@internal-authz</user_name>
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
</domain>
<groups/>
</user>
</users>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
In |
Sets the maximum number of users to return. |
|
|
In |
A query string used to restrict the returned users. |
|
|
Out |
The list of users in the domain. |
5.56. Domains
A service to list all authentication domains in the system.
Name | Summary |
---|---|
|
List all the authentication domains in the system. |
5.56.1. list GET
List all the authentication domains in the system.
Usage:
GET /ovirt-engine/api/domains
Will return the list of domains:
<domains>
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
<link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
<link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
<link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/>
<link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/>
</domain>
</domains>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The list of domains. |
|
|
In |
Sets the maximum number of domains to return. |
5.57. EngineKatelloErrata
A service to manage Katello errata assigned to the engine. The information is retrieved from Katello.
Name | Summary |
---|---|
|
Retrieves the representation of the Katello errata. |
5.57.1. list GET
Retrieves the representation of the Katello errata.
GET /ovirt-engine/api/katelloerrata
You will receive response in XML like this one:
<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
...
</katello_errata>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
A representation of Katello errata. |
|
|
In |
Sets the maximum number of errata to return. |
5.58. Event
A service to manage an event in the system.
Name | Summary |
---|---|
|
Get an event. |
|
Removes an event from internal audit log. |
5.58.1. get GET
Get an event.
An example of getting an event:
GET /ovirt-engine/api/events/123
<event href="/ovirt-engine/api/events/123" id="123">
<description>Host example.com was added by admin@internal-authz.</description>
<code>42</code>
<correlation_id>135</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-12-11T11:13:44.654+02:00</time>
<cluster href="/ovirt-engine/api/clusters/456" id="456"/>
<host href="/ovirt-engine/api/hosts/789" id="789"/>
<user href="/ovirt-engine/api/users/987" id="987"/>
</event>
Note that the number of fields changes according to the information that resides on the event. For example, for storage domain related events you will get the storage domain reference, as well as the reference for the data center this storage domain resides in.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.59. Events
A service to manage events in the system.
Name | Summary |
---|---|
|
Adds an external event to the internal audit log. |
|
Get list of events. |
|
5.59.1. add POST
Adds an external event to the internal audit log.
This is intended for integration with external systems that detect or produce events relevant for the administrator of the system. For example, an external monitoring tool may be able to detect that a file system is full inside the guest operating system of a virtual machine. This event can be added to the internal audit log sending a request like this:
POST /ovirt-engine/api/events
<event>
<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
</event>
Events can also be linked to specific objects. For example, the above event could be linked to the specific
virtual machine where it happened, using the vm
link:
POST /ovirt-engine/api/events
<event>
<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
<vm id="aae98225-5b73-490d-a252-899209af17e9"/>
</event>
When using links, like the vm in the previous example, only the id attribute is accepted. The name
attribute, if provided, is simply ignored.
|
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.59.2. list GET
Get list of events.
GET /ovirt-engine/api/events
To the above request we get following response:
<events>
<event href="/ovirt-engine/api/events/2" id="2">
<description>User admin@internal-authz logged out.</description>
<code>31</code>
<correlation_id>1e892ea9</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T12:14:34.541+02:00</time>
<user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
<event href="/ovirt-engine/api/events/1" id="1">
<description>User admin logged in.</description>
<code>30</code>
<correlation_id>1fbd81f4</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T11:54:35.229+02:00</time>
<user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
</events>
The following events occur:
-
id="1" - The API logs in the admin user account.
-
id="2" - The API logs out of the admin user account.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Indicates the identifier of the the first event that should be returned. |
|
|
In |
Sets the maximum number of events to return. |
|
|
In |
The events service provides search queries similar to other resource services. |
case_sensitive
Indicates if the search performed using the search
parameter should be performed taking case into
account. The default value is true
, which means that case is taken into account. If you want to search
ignoring case set it to false
.
from
Indicates the identifier of the the first event that should be returned. The identifiers of events are
strictly increasing, so when this parameter is used only the events with that identifiers equal or greater
than the given value will be returned. For example, the following request will return only the events
with identifiers greater or equal than 123
:
GET /ovirt-engine/api/events?from=123
This parameter is optional, and if not specified then the first event returned will be most recently generated.
search
The events service provides search queries similar to other resource services.
We can search by providing specific severity.
GET /ovirt-engine/api/events?search=severity%3Dnormal
To the above request we get a list of events which severity is equal to normal
:
<events>
<event href="/ovirt-engine/api/events/2" id="2">
<description>User admin@internal-authz logged out.</description>
<code>31</code>
<correlation_id>1fbd81f4</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T11:54:35.229+02:00</time>
<user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
<event href="/ovirt-engine/api/events/1" id="1">
<description>Affinity Rules Enforcement Manager started.</description>
<code>10780</code>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T11:52:18.861+02:00</time>
</event>
</events>
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
Below example paginates event resources. The URL-encoded request is:
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201
Increase the page value to view the next page of results.
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202
5.60. ExternalComputeResource
Name | Summary |
---|---|
|
5.61. ExternalComputeResources
Name | Summary |
---|---|
|
5.62. ExternalDiscoveredHost
Name | Summary |
---|---|
|
5.63. ExternalDiscoveredHosts
Name | Summary |
---|---|
|
5.64. ExternalHost
Name | Summary |
---|---|
|
5.65. ExternalHostGroup
Name | Summary |
---|---|
|
5.66. ExternalHostGroups
Name | Summary |
---|---|
|
5.67. ExternalHostProvider
Name | Summary |
---|---|
|
|
|
|
|
|
|
|
|
5.67.2. importcertificates POST
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
5.67.3. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.67.4. testconnectivity POST
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the test should be performed asynchronously. |
5.68. ExternalHostProviders
Name | Summary |
---|---|
|
|
|
5.69. ExternalHosts
Name | Summary |
---|---|
|
5.70. ExternalProvider
Name | Summary |
---|---|
|
|
|
5.70.1. importcertificates POST
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
5.71. ExternalProviderCertificate
Name | Summary |
---|---|
|
5.72. ExternalProviderCertificates
Name | Summary |
---|---|
|
5.73. ExternalVmImports
Provides capability to import external virtual machines.
Name | Summary |
---|---|
|
This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware. |
5.73.1. add POST
This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware.
For example import of a virtual machine from VMware can be facilitated using the following request:
POST /externalvmimports
With request body of type ExternalVmImport, for example:
<external_vm_import>
<vm>
<name>my_vm</name>
</vm>
<cluster id="360014051136c20574f743bdbd28177fd" />
<storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
<name>vm_name_as_is_in_vmware</name>
<sparse>true</sparse>
<username>vmware_user</username>
<password>123456</password>
<provider>VMWARE</provider>
<url>vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1</url>
<drivers_iso id="virtio-win-1.6.7.iso" />
</external_vm_import>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.74. FenceAgent
Name | Summary |
---|---|
|
|
|
|
|
5.75. FenceAgents
Name | Summary |
---|---|
|
|
|
5.76. File
Name | Summary |
---|---|
|
5.77. Files
Provides a way for clients to list available files.
This services is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads.
The addition of a CDROM device to a virtual machine requires an ISO image from the files of an ISO storage domain.
Name | Summary |
---|---|
|
5.77.1. list GET
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Sets the maximum number of files to return. |
|
|
In |
A query string used to restrict the returned files. |
5.78. Filter
Name | Summary |
---|---|
|
|
|
5.78.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
Out |
5.79. Filters
Name | Summary |
---|---|
|
|
|
5.80. GlusterBrick
This service manages a single gluster brick.
Name | Summary |
---|---|
|
Get details of a brick. |
|
Removes a brick. |
|
Replaces this brick with a new one. |
5.80.1. get GET
Get details of a brick.
Retrieves status details of brick from underlying gluster volume with header All-Content
set to true
. This is
the equivalent of running gluster volume status <volumename> <brickname> detail
.
For example, to get the details of brick 234
of gluster volume 123
, send a request like this:
GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
Which will return a response body like this:
<brick id="234">
<name>host1:/rhgs/data/brick1</name>
<brick_dir>/rhgs/data/brick1</brick_dir>
<server_id>111</server_id>
<status>up</status>
<device>/dev/mapper/RHGS_vg1-lv_vmaddldisks</device>
<fs_name>xfs</fs_name>
<gluster_clients>
<gluster_client>
<bytes_read>2818417648</bytes_read>
<bytes_written>1384694844</bytes_written>
<client_port>1011</client_port>
<host_name>client2</host_name>
</gluster_client>
</gluster_clients>
<memory_pools>
<memory_pool>
<name>data-server:fd_t</name>
<alloc_count>1626348</alloc_count>
<cold_count>1020</cold_count>
<hot_count>4</hot_count>
<max_alloc>23</max_alloc>
<max_stdalloc>0</max_stdalloc>
<padded_size>140</padded_size>
<pool_misses>0</pool_misses>
</memory_pool>
</memory_pools>
<mnt_options>rw,seclabel,noatime,nodiratime,attr2,inode64,sunit=512,swidth=2048,noquota</mnt_options>
<pid>25589</pid>
<port>49155</port>
</brick>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.80.2. remove DELETE
Removes a brick.
Removes a brick from the underlying gluster volume and deletes entries from database. This can be used only when removing a single brick without data migration. To remove multiple bricks and with data migration, use migrate instead.
For example, to delete brick 234
from gluster volume 123
, send a request like this:
DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.80.3. replace POST
Replaces this brick with a new one.
This operation has been deprecated since version 3.5 of the engine and will be removed in the future. Use add brick(s) and migrate brick(s) instead. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the replacement should be performed asynchronously. |
|
|
In |
5.81. GlusterBricks
This service manages the gluster bricks in a gluster volume
Name | Summary |
---|---|
|
Activate the bricks post data migration of remove brick operation. |
|
Adds a list of bricks to gluster volume. |
|
Lists the bricks of a gluster volume. |
|
Start migration of data prior to removing bricks. |
|
Removes bricks from gluster volume. |
|
Stops migration of data from bricks for a remove brick operation. |
5.81.1. activate POST
Activate the bricks post data migration of remove brick operation.
Used to activate brick(s) once the data migration from bricks is complete but user no longer wishes to remove bricks. The bricks that were previously marked for removal will now be used as normal bricks.
For example, to retain the bricks that on glustervolume 123
from which data was migrated, send a request like
this:
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate
With a request body like this:
<action>
<bricks>
<brick>
<name>host1:/rhgs/brick1</name>
</brick>
</bricks>
</action>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the activation should be performed asynchronously. |
|
|
In |
The list of bricks that need to be re-activated. |
5.81.2. add POST
Adds a list of bricks to gluster volume.
Used to expand a gluster volume by adding bricks. For replicated volume types, the parameter replica_count
needs to be passed. In case the replica count is being increased, then the number of bricks needs to be
equivalent to the number of replica sets.
For example, to add bricks to gluster volume 123
, send a request like this:
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
With a request body like this:
<bricks>
<brick>
<server_id>111</server_id>
<brick_dir>/export/data/brick3</brick_dir>
</brick>
</bricks>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The list of bricks to be added to the volume |
|
|
In |
Replica count of volume post add operation. |
|
|
In |
Stripe count of volume post add operation. |
5.81.3. list GET
Lists the bricks of a gluster volume.
For example, to list bricks of gluster volume 123
, send a request like this:
GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
Provides an output as below:
<bricks>
<brick id="234">
<name>host1:/rhgs/data/brick1</name>
<brick_dir>/rhgs/data/brick1</brick_dir>
<server_id>111</server_id>
<status>up</status>
</brick>
<brick id="233">
<name>host2:/rhgs/data/brick1</name>
<brick_dir>/rhgs/data/brick1</brick_dir>
<server_id>222</server_id>
<status>up</status>
</brick>
</bricks>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
||
|
In |
Sets the maximum number of bricks to return. |
5.81.4. migrate POST
Start migration of data prior to removing bricks.
Removing bricks is a two-step process, where the data on bricks to be removed, is first migrated to remaining bricks. Once migration is completed the removal of bricks is confirmed via the API remove. If at any point, the action needs to be cancelled stopmigrate has to be called.
For instance, to delete a brick from a gluster volume with id 123
, send a request:
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate
With a request body like this:
<action>
<bricks>
<brick>
<name>host1:/rhgs/brick1</name>
</brick>
</bricks>
</action>
The migration process can be tracked from the job id returned from the API using job and steps in job using step
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the migration should be performed asynchronously. |
|
|
In |
List of bricks for which data migration needs to be started. |
5.81.5. remove DELETE
Removes bricks from gluster volume.
The recommended way to remove bricks without data loss is to first migrate the data using stopmigrate and then removing them. If migrate was not called on bricks prior to remove, the bricks are removed without data migration which may lead to data loss.
For example, to delete the bricks from gluster volume 123
, send a request like this:
DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
With a request body like this:
<bricks>
<brick>
<name>host:brick_directory</name>
</brick>
</bricks>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
|
|
In |
The list of bricks to be removed |
|
|
In |
Replica count of volume post add operation. |
5.81.6. stopmigrate POST
Stops migration of data from bricks for a remove brick operation.
To cancel data migration that was started as part of the 2-step remove brick process in case the user wishes to continue using the bricks. The bricks that were marked for removal will function as normal bricks post this operation.
For example, to stop migration of data from the bricks of gluster volume 123
, send a request like this:
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate
With a request body like this:
<bricks>
<brick>
<name>host:brick_directory</name>
</brick>
</bricks>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
List of bricks for which data migration needs to be stopped. |
bricks
List of bricks for which data migration needs to be stopped. This list should match the arguments passed to migrate.
5.82. GlusterHook
Name | Summary |
---|---|
|
Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster. |
|
Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster. |
|
|
|
Removes the this Gluster hook from all servers in cluster and deletes it from the database. |
|
Resolves missing hook conflict depending on the resolution type. |
5.82.1. disable POST
Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the
cluster. This updates the hook status to DISABLED
in database.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.82.2. enable POST
Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the
cluster. This updates the hook status to DISABLED
in database.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.82.4. remove DELETE
Removes the this Gluster hook from all servers in cluster and deletes it from the database.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.82.5. resolve POST
Resolves missing hook conflict depending on the resolution type.
For ADD
resolves by copying hook stored in engine database to all servers where the hook is missing. The
engine maintains a list of all servers where hook is missing.
For COPY
resolves conflict in hook content by copying hook stored in engine database to all servers where
the hook is missing. The engine maintains a list of all servers where the content is conflicting. If a host
id is passed as parameter, the hook content from the server is used as the master to copy to other servers
in cluster.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
||
|
In |
5.83. GlusterHooks
Name | Summary |
---|---|
|
5.84. GlusterVolume
This service manages a single gluster volume.
Name | Summary |
---|---|
|
Get the gluster volume details. |
|
Get gluster volume profile statistics. |
|
Rebalance the gluster volume. |
|
Removes the gluster volume. |
|
Resets all the options set in the gluster volume. |
|
Resets a particular option in the gluster volume. |
|
Sets a particular option in the gluster volume. |
|
Starts the gluster volume. |
|
Start profiling the gluster volume. |
|
Stops the gluster volume. |
|
Stop profiling the gluster volume. |
|
Stop rebalancing the gluster volume. |
5.84.1. get GET
Get the gluster volume details.
For example, to get details of a gluster volume with identifier 123
in cluster 456
, send a request like this:
GET /ovirt-engine/api/clusters/456/glustervolumes/123
This GET request will return the following output:
<gluster_volume id="123">
<name>data</name>
<link href="/ovirt-engine/api/clusters/456/glustervolumes/123/glusterbricks" rel="glusterbricks"/>
<disperse_count>0</disperse_count>
<options>
<option>
<name>storage.owner-gid</name>
<value>36</value>
</option>
<option>
<name>performance.io-cache</name>
<value>off</value>
</option>
<option>
<name>cluster.data-self-heal-algorithm</name>
<value>full</value>
</option>
</options>
<redundancy_count>0</redundancy_count>
<replica_count>3</replica_count>
<status>up</status>
<stripe_count>0</stripe_count>
<transport_types>
<transport_type>tcp</transport_type>
</transport_types>
<volume_type>replicate</volume_type>
</gluster_volume>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Representation of the gluster volume. |
5.84.2. getprofilestatistics POST
Get gluster volume profile statistics.
For example, to get profile statistics for a gluster volume with identifier 123
in cluster 456
, send a
request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/getprofilestatistics
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Gluster volume profiling information returned from the action. |
5.84.3. rebalance POST
Rebalance the gluster volume.
Rebalancing a gluster volume helps to distribute the data evenly across all the bricks. After expanding or shrinking a gluster volume (without migrating data), we need to rebalance the data among the bricks. In a non-replicated volume, all bricks should be online to perform the rebalance operation. In a replicated volume, at least one of the bricks in the replica should be online.
For example, to rebalance a gluster volume with identifier 123
in cluster 456
, send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/rebalance
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the rebalance should be performed asynchronously. |
|
|
In |
If set to true, rebalance will only fix the layout so that new data added to the volume is distributed across all the hosts. |
|
|
In |
Indicates if the rebalance should be force started. |
5.84.4. remove DELETE
Removes the gluster volume.
For example, to remove a volume with identifier 123
in cluster 456
, send a request like this:
DELETE /ovirt-engine/api/clusters/456/glustervolumes/123
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.84.5. resetalloptions POST
Resets all the options set in the gluster volume.
For example, to reset all options in a gluster volume with identifier 123
in cluster 456
, send a request like
this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetalloptions
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the reset should be performed asynchronously. |
5.84.6. resetoption POST
Resets a particular option in the gluster volume.
For example, to reset a particular option option1
in a gluster volume with identifier 123
in cluster 456
,
send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetoption
With the following request body:
<action>
<option name="option1"/>
</action>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the reset should be performed asynchronously. |
|
|
In |
||
|
In |
Option to reset. |
5.84.7. setoption POST
Sets a particular option in the gluster volume.
For example, to set option1
with value value1
in a gluster volume with identifier 123
in cluster 456
,
send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/setoption
With the following request body:
<action>
<option name="option1" value="value1"/>
</action>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
Option to set. |
5.84.8. start POST
Starts the gluster volume.
A Gluster Volume should be started to read/write data. For example, to start a gluster volume with identifier
123
in cluster 456
, send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/start
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
Indicates if the volume should be force started. |
5.84.9. startprofile POST
Start profiling the gluster volume.
For example, to start profiling a gluster volume with identifier 123
in cluster 456
, send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/startprofile
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.84.10. stop POST
Stops the gluster volume.
Stopping a volume will make its data inaccessible.
For example, to stop a gluster volume with identifier 123
in cluster 456
, send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/stop
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
5.84.11. stopprofile POST
Stop profiling the gluster volume.
For example, to stop profiling a gluster volume with identifier 123
in cluster 456
, send a request like this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/stopprofile
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.84.12. stoprebalance POST
Stop rebalancing the gluster volume.
For example, to stop rebalancing a gluster volume with identifier 123
in cluster 456
, send a request like
this:
POST /ovirt-engine/api/clusters/456/glustervolumes/123/stoprebalance
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.85. GlusterVolumes
This service manages a collection of gluster volumes available in a cluster.
Name | Summary |
---|---|
|
Creates a new gluster volume. |
|
Lists all gluster volumes in the cluster. |
5.85.1. add POST
Creates a new gluster volume.
The volume is created based on properties of the volume
parameter. The properties name
, volume_type
and
bricks
are required.
For example, to add a volume with name myvolume
to the cluster 123
, send the following request:
POST /ovirt-engine/api/clusters/123/glustervolumes
With the following request body:
<gluster_volume>
<name>myvolume</name>
<volume_type>replicate</volume_type>
<replica_count>3</replica_count>
<bricks>
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<brick>
<server_id>server2</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<brick>
<server_id>server3</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<bricks>
</gluster_volume>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The gluster volume definition from which to create the volume is passed as input and the newly created volume is returned. |
5.85.2. list GET
Lists all gluster volumes in the cluster.
For example, to list all Gluster Volumes in cluster 456
, send a request like
this:
GET /ovirt-engine/api/clusters/456/glustervolumes
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
In |
Sets the maximum number of volumes to return. |
|
|
In |
A query string used to restrict the returned volumes. |
|
|
Out |
5.86. Group
Name | Summary |
---|---|
|
|
|
5.87. Groups
Name | Summary |
---|---|
|
Add group from a directory service. |
|
5.87.1. add POST
Add group from a directory service. Please note that domain name is name of the authorization provider.
For example, to add the Developers
group from the internal-authz
authorization provider send a request
like this:
POST /ovirt-engine/api/groups
With a request body like this:
<group>
<name>Developers</name>
<domain>
<name>internal-authz</name>
</domain>
</group>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.87.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Sets the maximum number of groups to return. |
|
|
In |
A query string used to restrict the returned groups. |
5.88. Host
A service to manage a host.
Name | Summary |
---|---|
|
Activate the host for use, such as running virtual machines. |
|
Approve a pre-installed Hypervisor host for usage in the virtualization environment. |
|
Marks the network configuration as good and persists it inside the host. |
|
Deactivate the host to perform maintenance tasks. |
|
Enroll certificate of the host. |
|
Controls host’s power management device. |
|
Manually set a host as the storage pool manager (SPM). |
|
Get the host details. |
|
Install VDSM and related software on the host. |
|
Discover iSCSI targets on the host, using the initiator details. |
|
Login to iSCSI targets on the host, using the target details. |
|
Refresh the host devices and capabilities. |
|
Remove the host from the system. |
|
This method is used to change the configuration of the network interfaces of a host. |
|
|
|
Update the host properties. |
|
Upgrade VDSM and selected software on the host. |
|
Check if there are upgrades available for the host. |
5.88.1. activate POST
Activate the host for use, such as running virtual machines.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the activation should be performed asynchronously. |
5.88.2. approve POST
Approve a pre-installed Hypervisor host for usage in the virtualization environment.
This action also accepts an optional cluster element to define the target cluster for this host.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the approval should be performed asynchronously. |
|
|
In |
5.88.3. commitnetconfig POST
Marks the network configuration as good and persists it inside the host.
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.
Networking configuration is only committed after the engine 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. |
For example, to commit the network configuration of host with id 123
send a request like this:
POST /ovirt-engine/api/hosts/123/commitnetconfig
With a request body like this:
<action/>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.88.4. deactivate POST
Deactivate the host to perform maintenance tasks.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the deactivation should be performed asynchronously. |
|
|
In |
||
|
In |
Indicates if the gluster service should be stopped as part of deactivating the host. |
5.88.5. enrollcertificate POST
Enroll certificate of the host. Useful in case you get a warning that it is about to, or already expired.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the enrollment should be performed asynchronously. |
5.88.6. fence POST
Controls host’s power management device.
For example, let’s assume you want to start the host. This can be done via:
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<fence_type>start</fence_type>
</action>
' \
"${url}/hosts/123/fence"
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the fencing should be performed asynchronously. |
|
|
In |
||
|
Out |
5.88.7. forceselectspm POST
Manually set a host as the storage pool manager (SPM).
POST /ovirt-engine/api/hosts/123/forceselectspm
With a request body like this:
<action/>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.88.8. get GET
Get the host details.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
Out |
5.88.9. install POST
Install VDSM and related software on the host. The host type defines additional parameters for the action.
Example of installing a host, using curl
and JSON, plain:
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
"root_password": "myrootpassword"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123"
Example of installing a host, using curl
and JSON, with hosted engine components:
curl \
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
"root_password": "myrootpassword"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123?deploy_hosted_engine=true"
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the installation should be performed asynchronously. |
|
|
In |
When set to |
|
|
In |
This |
|
|
In |
When installing an oVirt node a image ISO file is needed. |
|
|
In |
The password of of the |
|
|
In |
The SSH details used to connect to the host. |
|
|
In |
When set to |
deploy_hosted_engine
When set to true
it means this host should deploy also hosted
engine components. Missing value is treated as true
i.e deploy.
Omitting this parameter means false
and will perform no operation
in hosted engine area.
undeploy_hosted_engine
When set to true
it means this host should un-deploy hosted engine
components and this host will not function as part of the High
Availability cluster. Missing value is treated as true
i.e un-deploy
Omitting this parameter means false
and will perform no operation
in hosted engine area.
5.88.10. iscsidiscover POST
Discover iSCSI targets on the host, using the initiator details.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the discovery should be performed asynchronously. |
|
|
In |
The target iSCSI device. |
|
|
Out |
The iSCSI targets. |
5.88.11. iscsilogin POST
Login to iSCSI targets on the host, using the target details.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the login should be performed asynchronously. |
|
|
In |
The target iSCSI device. |
5.88.12. refresh POST
Refresh the host devices and capabilities.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the refresh should be performed asynchronously. |
5.88.13. remove DELETE
Remove the host from the system.
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.88.14. setupnetworks POST
This method is used to change the configuration of the network interfaces of a host.
For example, lets assume that you have a host with three network interfaces eth0
, eth1
and eth2
and that
you want to configure a new bond using eth0
and eth1
, and put a VLAN on top of it. Using a simple shell
script and the curl
command line HTTP client that can be done as follows:
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<modified_bonds>
<host_nic>
<name>bond0</name>
<bonding>
<options>
<option>
<name>mode</name>
<value>4</value>
</option>
<option>
<name>miimon</name>
<value>100</value>
</option>
</options>
<slaves>
<host_nic>
<name>eth1</name>
</host_nic>
<host_nic>
<name>eth2</name>
</host_nic>
</slaves>
</bonding>
</host_nic>
</modified_bonds>
<modified_network_attachments>
<network_attachment>
<network>
<name>myvlan</name>
</network>
<host_nic>
<name>bond0</name>
</host_nic>
<ip_address_assignments>
<assignment_method>static</assignment_method>
<ip_address_assignment>
<ip>
<address>192.168.122.10</address>
<netmask>255.255.255.0</netmask>
</ip>
</ip_address_assignment>
</ip_address_assignments>
<dns_resolver_configuration>
<name_servers>
<name_server>1.1.1.1</name_server>
<name_server>2.2.2.2</name_server>
</name_servers>
</dns_resolver_configuration>
</network_attachment>
</modified_network_attachments>
</action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"
Note that this is valid for version 4 of the API. In previous versions some elements were represented as XML
attributes instead of XML elements. In particular the options
and ip
elements were represented as follows:
<options name="mode" value="4"/>
<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/>
Using the Python SDK the same can be done with the following code:
# Find the service that manages the collection of hosts:
hosts_service = connection.system_service().hosts_service()
# Find the host:
host = hosts_service.list(search='name=myhost')[0]
# Find the service that manages the host:
host_service = hosts_service.host_service(host.id)
# Configure the network adding a bond with two slaves and attaching it to a
# network with an static IP address:
host_service.setup_networks(
modified_bonds=[
types.HostNic(
name='bond0',
bonding=types.Bonding(
options=[
types.Option(
name='mode',
value='4',
),
types.Option(
name='miimon',
value='100',
),
],
slaves=[
types.HostNic(
name='eth1',
),
types.HostNic(
name='eth2',
),
],
),
),
],
modified_network_attachments=[
types.NetworkAttachment(
network=types.Network(
name='myvlan',
),
host_nic=types.HostNic(
name='bond0',
),
ip_address_assignments=[
types.IpAddressAssignment(
assignment_method=types.BootProtocol.STATIC,
ip=types.Ip(
address='192.168.122.10',
netmask='255.255.255.0',
),
),
],
dns_resolver_configuration=types.DnsResolverConfiguration(
name_servers=[
'1.1.1.1',
'2.2.2.2',
],
),
),
],
)
# After modifying the network configuration it is very important to make it
# persistent:
host_service.commit_net_config()
To make sure that the network configuration has been saved in the host, and that it will be applied when the host is rebooted, remember to call commitnetconfig. |
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
||
|
In |
||
|
In |
||
|
In |
||
|
In |
||
|
In |
||
|
In |
||
|
In |
||
|
In |
5.88.15. unregisteredstoragedomainsdiscover POST
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the discovery should be performed asynchronously. |
|
|
In |
||
|
Out |
5.88.16. update PUT
Update the host properties.
For example, to update a the kernel command line of a host send a request like this:
PUT /ovirt-engine/api/hosts/123
With request body like this:
<host>
<os>
<custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
</os>
</host>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
5.88.17. upgrade POST
Upgrade VDSM and selected software on the host.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the upgrade should be performed asynchronously. |
5.88.18. upgradecheck POST
Check if there are upgrades available for the host. If there are upgrades available an icon will be displayed next to host status icon in the webadmin. Audit log messages are also added to indicate the availability of upgrades. The upgrade can be started from the webadmin or by using the upgrade host action.
5.89. HostDevice
A service to access a particular device of a host.
Name | Summary |
---|---|
|
Retrieve information about a particular host’s device. |
5.89.1. get GET
Retrieve information about a particular host’s device.
An example of getting a host device:
GET /ovirt-engine/api/hosts/123/devices/456
<host_device href="/ovirt-engine/api/hosts/123/devices/456" id="456">
<name>usb_1_9_1_1_0</name>
<capability>usb</capability>
<host href="/ovirt-engine/api/hosts/123" id="123"/>
<parent_device href="/ovirt-engine/api/hosts/123/devices/789" id="789">
<name>usb_1_9_1</name>
</parent_device>
</host_device>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.90. HostDevices
A service to access host devices.
Name | Summary |
---|---|
|
List the devices of a host. |
5.91. HostHook
Name | Summary |
---|---|
|
5.93. HostNic
A service to manage a network interface of a host.
Name | Summary |
---|---|
|
|
|
The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC. |
5.93.2. updatevirtualfunctionsconfiguration POST
The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC. The input should be consisted of at least one of the following properties:
-
allNetworksAllowed
-
numberOfVirtualFunctions
Please see the HostNicVirtualFunctionsConfiguration
type for the meaning of the properties.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In |
5.94. HostNics
A service to manage the network interfaces of a host.
Name | Summary |
---|---|
|
5.95. HostNumaNode
Name | Summary |
---|---|
|
5.96. HostNumaNodes
Name | Summary |
---|---|
|
5.97. HostStorage
A service to manage host storages.
Name | Summary |
---|---|
|
Get list of storages. |
5.97.1. list GET
Get list of storages.
GET /ovirt-engine/api/hosts/123/storage
The XML response you get will be like this one:
<host_storages>
<host_storage id="123">
...
</host_storage>
...
</host_storages>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the status of the LUNs in the storage should be checked. |
|
|
Out |
Retrieved list of storages. |
report_status
Indicates if the status of the LUNs in the storage should be checked. Checking the status of the LUN is an heavy weight operation and this data is not always needed by the user. This parameter will give the option to not perform the status check of the LUNs.
The default is true
for backward compatibility.
Here an example with the LUN status :
<host_storage id="123">
<logical_units>
<logical_unit id="123">
<lun_mapping>0</lun_mapping>
<paths>1</paths>
<product_id>lun0</product_id>
<serial>123</serial>
<size>10737418240</size>
<status>used</status>
<vendor_id>LIO-ORG</vendor_id>
<volume_group_id>123</volume_group_id>
</logical_unit>
</logical_units>
<type>iscsi</type>
<host id="123"/>
</host_storage>
Here an example without the LUN status :
<host_storage id="123">
<logical_units>
<logical_unit id="123">
<lun_mapping>0</lun_mapping>
<paths>1</paths>
<product_id>lun0</product_id>
<serial>123</serial>
<size>10737418240</size>
<vendor_id>LIO-ORG</vendor_id>
<volume_group_id>123</volume_group_id>
</logical_unit>
</logical_units>
<type>iscsi</type>
<host id="123"/>
</host_storage>
5.98. Hosts
A service that manages hosts.
Name | Summary |
---|---|
|
Creates a new host. |
|
Get a list of all available hosts. |
5.98.1. add POST
Creates a new host.
The host is created based on the attributes of the host
parameter. The name
, address
and root_password
properties are required.
For example, to add a host send the following request:
POST /ovirt-engine/api/hosts
With the following request body:
<host>
<name>myhost</name>
<address>myhost.example.com</address>
<root_password>myrootpassword</root_password>
</host>
The root_password element is only included in the client-provided initial representation and is not
exposed in the representations returned from subsequent requests.
|
To add a hosted engine host, use the optional deploy_hosted_engine
parameter:
POST /ovirt-engine/api/hosts?deploy_hosted_engine=true
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
When set to |
|
|
In/Out |
The host definition from which to create the new host is passed as parameter, and the newly created host is returned. |
|
|
In |
When set to |
deploy_hosted_engine
When set to true
it means this host should deploy also hosted engine components. Missing value is treated
as true
i.e deploy. Omitting this parameter means false
and will perform no operation in hosted engine
area.
undeploy_hosted_engine
When set to true
it means this host should un-deploy hosted engine components and this host will not
function as part of the High Availability cluster. Missing value is treated as true
i.e un-deploy.
Omitting this parameter means false
and will perform no operation in hosted engine area.
5.98.2. list GET
Get a list of all available hosts.
For example, to list the hosts send the following request:
GET /ovirt-engine/api/hosts
The response body will be something like this:
<hosts>
<host href="/ovirt-engine/api/hosts/123" id="123">
...
</host>
<host href="/ovirt-engine/api/hosts/456" id="456">
...
</host>
...
</host>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
In |
Indicates if the results should be filtered according to the permissions of the user. |
|
|
Out |
||
|
In |
Sets the maximum number of hosts to return. |
|
|
In |
A query string used to restrict the returned hosts. |
5.99. Icon
A service to manage an icon (read-only).
Name | Summary |
---|---|
|
Get an icon. |
5.100. Icons
A service to manage icons.
Name | Summary |
---|---|
|
Get a list of icons. |
5.100.1. list GET
Get a list of icons.
GET /ovirt-engine/api/icons
You will get a XML response which is similar to this one:
<icons>
<icon id="123">
<data>...</data>
<media_type>image/png</media_type>
</icon>
...
</icons>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Retrieved list of icons. |
|
|
In |
Sets the maximum number of icons to return. |
5.101. Image
Name | Summary |
---|---|
|
|
|
5.101.2. import POST
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the import should be performed asynchronously. |
|
|
In |
Cluster where the image should be imported. |
|
|
In |
The disk which should be imported. |
|
|
In |
Specify if template should be created from the imported disk. |
|
|
In |
Storage domain where disk should be imported. |
|
|
In |
Name of the template, which should be created. |
5.102. ImageTransfer
This service provides a mechanism to control an image transfer. The client will have to create a transfer by using add of the ImageTransfers service, stating the image to transfer data to/from.
After doing that, the transfer is managed by this service.
E.g., for uploading to the disk image with id 52cb593f-837c-4633-a444-35a0a0383706
,
the client can use oVirt’s Python’s SDK as follows:
transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
types.ImageTransfer(
image=types.Image(
id='52cb593f-837c-4633-a444-35a0a0383706'
)
)
)
If the user wishes to download a disk rather than upload, he/she should specify
download
as the direction attribute of the transfer.
This will grant a read permission from the image, instead of a write permission.
E.g:
transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
types.ImageTransfer(
image=types.Image(
id='52cb593f-837c-4633-a444-35a0a0383706'
),
direction=types.ImageTransferDirection.DOWNLOAD
)
)
Transfers have phases, which govern the flow of the upload/download. A client implementing such a flow should poll/check the transfer’s phase and act accordingly. All the possible phases can be found in ImageTransferPhase.
After adding a new transfer, its phase will be initializing. The client will have to poll on the transfer’s phase until it changes. When the phase becomes transferring, the session is ready to start the transfer.
For example:
transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
time.sleep(3)
transfer = transfer_service.get()
At that stage, if the transfer’s phase is paused_system, then the session was not successfully established. One possible reason for that is that the ovirt-imageio-daemon is not running in the host that was selected for transfer. The transfer can be resumed by calling resume of the service that manages it.
If the session was successfully established - the returned transfer entity will contain the proxy_url and signed_ticket attributes, which the client needs to use in order to transfer the required data. The client can choose whatever technique and tool for sending the HTTPS request with the image’s data.
-
proxy_url
is the address of a proxy server to the image, to do I/O to. -
signed_ticket
is the content that needs to be added to theAuthentication
header in the HTTPS request, in order to perform a trusted communication.
For example, Python’s HTTPSConnection can be used in order to perform a transfer,
so an transfer_headers
dict is set for the upcoming transfer:
transfer_headers = {
'Authorization' : transfer.signed_ticket,
}
Using Python’s HTTPSConnection
, a new connection is established:
# Extract the URI, port, and path from the transfer's proxy_url.
url = urlparse.urlparse(transfer.proxy_url)
# Create a new instance of the connection.
proxy_connection = HTTPSConnection(
url.hostname,
url.port,
context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)
For upload, the specific content range being sent must be noted in the Content-Range
HTTPS
header. This can be used in order to split the transfer into several requests for
a more flexible process.
For doing that, the client will have to repeatedly extend the transfer session
to keep the channel open. Otherwise, the session will terminate and the transfer will
get into paused_system
phase, and HTTPS requests to the server will be rejected.
E.g., the client can iterate on chunks of the file, and send them to the proxy server while asking the service to extend the session:
path = "/path/to/image"
MB_per_request = 32
with open(path, "rb") as disk:
size = os.path.getsize(path)
chunk_size = 1024*1024*MB_per_request
pos = 0
while (pos < size):
transfer_service.extend()
transfer_headers['Content-Range'] = "bytes %d-%d/%d" % (pos, min(pos + chunk_size, size)-1, size)
proxy_connection.request(
'PUT',
url.path,
disk.read(chunk_size),
headers=transfer_headers
)
r = proxy_connection.getresponse()
print r.status, r.reason, "Completed", "{:.0%}".format(pos/ float(size))
pos += chunk_size
Similarly, for a download transfer, a Range
header must be sent, making the download process
more easily managed by downloading the disk in chunks.
E.g., the client will again iterate on chunks of the disk image, but this time he/she will download it to a local file, rather than uploading its own file to the image:
output_file = "/home/user/downloaded_image"
MiB_per_request = 32
chunk_size = 1024*1024*MiB_per_request
total = disk_size
with open(output_file, "wb") as disk:
pos = 0
while pos < total:
transfer_service.extend()
transfer_headers['Range'] = "bytes=%d-%d" % (pos, min(total, pos + chunk_size) - 1)
proxy_connection.request('GET', proxy_url.path, headers=transfer_headers)
r = proxy_connection.getresponse()
disk.write(r.read())
print "Completed", "{:.0%}".format(pos/ float(total))
pos += chunk_size
When finishing the transfer, the user should call finalize. This will make the final adjustments and verifications for finishing the transfer process.
For example:
transfer_service.finalize()
In case of an error, the transfer’s phase will be changed to
finished_failure, and
the disk’s status will be changed to Illegal
. Otherwise it will be changed to
finished_success, and the disk will be ready
to be used. In both cases, the transfer entity will be removed shortly after.
Name | Summary |
---|---|
|
Extend the image transfer session. |
|
After finishing to transfer the data, finalize the transfer. |
|
Get the image transfer entity. |
|
Pause the image transfer session. |
|
Resume the image transfer session. |
5.102.2. finalize POST
After finishing to transfer the data, finalize the transfer.
This will make sure that the data being transferred is valid and fits the image entity that was targeted in the transfer. Specifically, will verify that if the image entity is a QCOW disk, the data uploaded is indeed a QCOW file, and that the image doesn’t have a backing file.
5.102.3. get GET
Get the image transfer entity.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.102.5. resume POST
Resume the image transfer session. The client will need to poll the transfer’s phase until
it is different than resuming
. For example:
transfer_service = transfers_service.image_transfer_service(transfer.id)
transfer_service.resume()
transfer = transfer_service.get()
while transfer.phase == types.ImageTransferPhase.RESUMING:
time.sleep(1)
transfer = transfer_service.get()
5.103. ImageTransfers
This service manages image transfers, for performing Image I/O API in oVirt. Please refer to image transfer for further documentation.
Name | Summary |
---|---|
|
Add a new image transfer. |
|
Retrieves the list of image transfers that are currently being performed. |
5.103.1. add POST
Add a new image transfer. An image needs to be specified in order to make a new transfer.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.105. InstanceType
Name | Summary |
---|---|
|
Get a specific instance type and it’s attributes. |
|
Removes a specific instance type from the system. |
|
Update a specific instance type and it’s attributes. |
5.105.1. get GET
Get a specific instance type and it’s attributes.
GET /ovirt-engine/api/instancetypes/123
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.105.2. remove DELETE
Removes a specific instance type from the system.
If a virtual machine was created using an instance type X after removal of the instance type
the virtual machine’s instance type will be set to custom
.
DELETE /ovirt-engine/api/instancetypes/123
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.105.3. update PUT
Update a specific instance type and it’s attributes.
All the attributes are editable after creation. If a virtual machine was created using an instance type X and some configuration in instance type X was updated, the virtual machine’s configuration will be updated automatically by the engine.
PUT /ovirt-engine/api/instancetypes/123
For example, to update the memory of instance type 123
to 1 GiB and set the cpu topology
to 2 sockets and 1 core, send a request like this:
<instance_type>
<memory>1073741824</memory>
<cpu>
<topology>
<cores>1</cores>
<sockets>2</sockets>
<threads>1</threads>
</topology>
</cpu>
</instance_type>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
5.106. InstanceTypeGraphicsConsole
Name | Summary |
---|---|
|
Gets graphics console configuration of the instance type. |
|
Remove the graphics console from the instance type. |
5.106.1. get GET
Gets graphics console configuration of the instance type.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The information about the graphics console of the instance type. |
5.107. InstanceTypeGraphicsConsoles
Name | Summary |
---|---|
|
Add new graphics console to the instance type. |
|
Lists all the configured graphics consoles of the instance type. |
5.107.1. add POST
Add new graphics console to the instance type.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.108. InstanceTypeNic
Name | Summary |
---|---|
|
Gets network interface configuration of the instance type. |
|
Remove the network interface from the instance type. |
|
Updates the network interface configuration of the instance type. |
5.108.1. get GET
Gets network interface configuration of the instance type.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.109. InstanceTypeNics
Name | Summary |
---|---|
|
Add new network interface to the instance type. |
|
Lists all the configured network interface of the instance type. |
5.109.1. add POST
Add new network interface to the instance type.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.110. InstanceTypeWatchdog
Name | Summary |
---|---|
|
Gets watchdog configuration of the instance type. |
|
Remove a watchdog from the instance type. |
|
Updates the watchdog configuration of the instance type. |
5.110.1. get GET
Gets watchdog configuration of the instance type.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.111. InstanceTypeWatchdogs
Name | Summary |
---|---|
|
Add new watchdog to the instance type. |
|
Lists all the configured watchdogs of the instance type. |
5.111.1. add POST
Add new watchdog to the instance type.
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.112. InstanceTypes
Name | Summary |
---|---|
|
Creates a new instance type. |
|
Lists all existing instance types in the system. |
5.112.1. add POST
Creates a new instance type.
This requires only a name attribute and can include all hardware configurations of the virtual machine.
POST /ovirt-engine/api/instancetypes
With a request body like this:
<instance_type>
<name>myinstancetype</name>
</template>
Creating an instance type with all hardware configurations with a request body like this:
<instance_type>
<name>myinstancetype</name>
<console>
<enabled>true</enabled>
</console>
<cpu>
<topology>
<cores>2</cores>
<sockets>2</sockets>
<threads>1</threads>
</topology>
</cpu>
<custom_cpu_model>AMD Opteron_G2</custom_cpu_model>
<custom_emulated_machine>q35</custom_emulated_machine>
<display>
<monitors>1</monitors>
<single_qxl_pci>true</single_qxl_pci>
<smartcard_enabled>true</smartcard_enabled>
<type>spice</type>
</display>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<io>
<threads>2</threads>
</io>
<memory>4294967296</memory>
<memory_policy>
<ballooning>true</ballooning>
<guaranteed>268435456</guaranteed>
</memory_policy>
<migration>
<auto_converge>inherit</auto_converge>
<compressed>inherit</compressed>
<policy id="00000000-0000-0000-0000-000000000000"/>
</migration>
<migration_downtime>2</migration_downtime>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
<rng_device>
<rate>
<bytes>200</bytes>
<period>2</period>
</rate>
<source>urandom</source>
</rng_device>
<soundcard_enabled>true</soundcard_enabled>
<usb>
<enabled>true</enabled>
<type>native</type>
</usb>
<virtio_scsi>
<enabled>true</enabled>
</virtio_scsi>
</instance_type>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.112.2. list GET
Lists all existing instance types in the system.
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the search performed using the |
|
|
Out |
||
|
In |
Sets the maximum number of instance types to return. |
|
|
In |
A query string used to restrict the returned templates. |
5.113. IscsiBond
Name | Summary |
---|---|
|
|
|
Removes of an existing iSCSI bond. |
|
Updates an iSCSI bond. |
5.113.2. remove DELETE
Removes of an existing iSCSI bond.
For example, to remove the iSCSI bond 456
send a request like this:
DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.113.3. update PUT
Updates an iSCSI bond.
Updating of an iSCSI bond can be done on the name
and the description
attributes only. For example, to
update the iSCSI bond 456
of data center 123
, send a request like this:
PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234
The request body should look like this:
<iscsi_bond>
<name>mybond</name>
<description>My iSCSI bond</description>
</iscsi_bond>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
5.114. IscsiBonds
Name | Summary |
---|---|
|
Create a new iSCSI bond on a data center. |
|
5.114.1. add POST
Create a new iSCSI bond on a data center.
For example, to create a new iSCSI bond on data center 123
using storage connections 456
and 789
, send a
request like this:
POST /ovirt-engine/api/datacenters/123/iscsibonds
The request body should look like this:
<iscsi_bond>
<name>mybond</name>
<storage_connections>
<storage_connection id="456"/>
<storage_connection id="789"/>
</storage_connections>
<networks>
<network id="abc"/>
</networks>
</iscsi_bond>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.115. Job
A service to manage a job.
Name | Summary |
---|---|
|
Set an external job execution to be cleared by the system. |
|
Marks an external job execution as ended. |
|
Retrieves a job. |
5.115.1. clear POST
Set an external job execution to be cleared by the system.
For example, to set a job with identifier 123
send the following request:
POST /ovirt-engine/api/jobs/clear
With the following request body:
<action/>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
5.115.2. end POST
Marks an external job execution as ended.
For example, to terminate a job with identifier 123
send the following request:
POST /ovirt-engine/api/jobs/end
With the following request body:
<action>
<force>true</force>
<status>finished</status>
</action>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the action should be performed asynchronously. |
|
|
In |
Indicates if the job should be forcibly terminated. |
|
|
In |
Indicates if the job should be marked as successfully finished or as failed. |
5.115.3. get GET
Retrieves a job.
GET /ovirt-engine/api/jobs/123
You will receive response in XML like this one:
<job href="/ovirt-engine/api/jobs/123" id="123">
<actions>
<link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
<link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
</actions>
<description>Adding Disk</description>
<link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
<auto_cleared>true</auto_cleared>
<end_time>2016-12-12T23:07:29.758+02:00</end_time>
<external>false</external>
<last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
<start_time>2016-12-12T23:07:26.593+02:00</start_time>
<status>failed</status>
<owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Retrieves the representation of the job. |
5.116. Jobs
A service to manage jobs.
Name | Summary |
---|---|
|
Add an external job. |
|
Retrieves the representation of the jobs. |
5.116.1. add POST
Add an external job.
For example, to add a job with the following request:
POST /ovirt-engine/api/jobs
With the following request body:
<job>
<description>Doing some work</description>
<auto_cleared>true</auto_cleared>
</job>
The response should look like:
<job href="/ovirt-engine/api/jobs/123" id="123">
<actions>
<link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
<link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
</actions>
<description>Doing some work</description>
<link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
<auto_cleared>true</auto_cleared>
<external>true</external>
<last_updated>2016-12-13T02:15:42.130+02:00</last_updated>
<start_time>2016-12-13T02:15:42.130+02:00</start_time>
<status>started</status>
<owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
Job that will be added. |
5.116.2. list GET
Retrieves the representation of the jobs.
GET /ovirt-engine/api/jobs
You will receive response in XML like this one:
<jobs>
<job href="/ovirt-engine/api/jobs/123" id="123">
<actions>
<link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
<link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
</actions>
<description>Adding Disk</description>
<link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
<auto_cleared>true</auto_cleared>
<end_time>2016-12-12T23:07:29.758+02:00</end_time>
<external>false</external>
<last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
<start_time>2016-12-12T23:07:26.593+02:00</start_time>
<status>failed</status>
<owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
...
</jobs>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
A representation of jobs. |
|
|
In |
Sets the maximum number of jobs to return. |
5.117. KatelloErrata
A service to manage Katello errata. The information is retrieved from Katello.
Name | Summary |
---|---|
|
Retrieves the representation of the Katello errata. |
5.117.1. list GET
Retrieves the representation of the Katello errata.
GET /ovirt-engine/api/katelloerrata
You will receive response in XML like this one:
<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
...
</katello_errata>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
A representation of Katello errata. |
|
|
In |
Sets the maximum number of errata to return. |
5.118. KatelloErratum
A service to manage a Katello erratum.
Name | Summary |
---|---|
|
Retrieves a Katello erratum. |
5.118.1. get GET
Retrieves a Katello erratum.
GET /ovirt-engine/api/katelloerrata/123
You will receive response in XML like this one:
<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
Retrieves the representation of the Katello erratum. |
5.119. MacPool
Name | Summary |
---|---|
|
|
|
Removes a MAC address pool. |
|
Updates a MAC address pool. |
5.119.2. remove DELETE
Removes a MAC address pool.
For example, to remove the MAC address pool having id 123
send a request like this:
DELETE /ovirt-engine/api/macpools/123
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.119.3. update PUT
Updates a MAC address pool.
The name
, description
, allow_duplicates
, and ranges
attributes can be updated.
For example, to update the MAC address pool of id 123
send a request like this:
PUT /ovirt-engine/api/macpools/123
With a request body like this:
<mac_pool>
<name>UpdatedMACPool</name>
<description>An updated MAC address pool</description>
<allow_duplicates>false</allow_duplicates>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:e6</to>
</range>
<range>
<from>02:1A:4A:01:00:00</from>
<to>02:1A:4A:FF:FF:FF</to>
</range>
</ranges>
</mac_pool>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
5.120. MacPools
Name | Summary |
---|---|
|
Creates a new MAC address pool. |
|
5.120.1. add POST
Creates a new MAC address pool.
Creation of a MAC address pool requires values for the name
and ranges
attributes.
For example, to create MAC address pool send a request like this:
POST /ovirt-engine/api/macpools
With a request body like this:
<mac_pool>
<name>MACPool</name>
<description>A MAC address pool</description>
<allow_duplicates>true</allow_duplicates>
<default_pool>false</default_pool>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:e6</to>
</range>
</ranges>
</mac_pool>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
5.122. Moveable
Name | Summary |
---|---|
|
5.123. Network
A service managing a network
Name | Summary |
---|---|
|
Gets a logical network. |
|
Removes a logical network, or the association of a logical network to a data center. |
|
Updates a logical network. |
5.123.1. get GET
Gets a logical network.
For example:
GET /ovirt-engine/api/networks/123
Will respond:
<network href="/ovirt-engine/api/networks/123" id="123">
<name>ovirtmgmt</name>
<description>Default Management Network</description>
<link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/>
<mtu>0</mtu>
<stp>false</stp>
<usages>
<usage>vm</usage>
</usages>
<data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</network>
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
5.123.2. remove DELETE
Removes a logical network, or the association of a logical network to a data center.
For example, to remove the logical network 123
send a request like this:
DELETE /ovirt-engine/api/networks/123
Each network is bound exactly to one data center. So if we disassociate network with data center it has the same
result as if we would just remove that network. However it might be more specific to say we’re removing network
456
of data center 123
.
For example, to remove the association of network 456
to data center 123
send a request like this:
DELETE /ovirt-engine/api/datacenters/123/networks/456
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.123.3. update PUT
Updates a logical network.
The name
, description
, ip
, vlan
, stp
and display
attributes can be updated.
For example, to update the description of the logical network 123
send a request like this:
PUT /ovirt-engine/api/networks/123
With a request body like this:
<network>
<description>My updated description</description>
</network>
The maximum transmission unit of a network is set using a PUT request to
specify the integer value of the mtu
attribute.
For example, to set the maximum transmission unit send a request like this:
PUT /ovirt-engine/api/datacenters/123/networks/456
With a request body like this:
<network>
<mtu>1500</mtu>
</network>
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the update should be performed asynchronously. |
|
|
In/Out |
5.124. NetworkAttachment
Name | Summary |
---|---|
|
|
|
|
|
5.124.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
|
In |
Indicates if the remove should be performed asynchronously. |
5.125. NetworkAttachments
Name | Summary |
---|---|
|
|
|
5.126. NetworkFilter
Manages a network filter.
<network_filter id="00000019-0019-0019-0019-00000000026b">
<name>example-network-filter-b</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>
Please note that version is referring to the minimal support version for the specific filter.
Name | Summary |
---|---|
|
Retrieves a representation of the network filter. |
5.127. NetworkFilterParameter
This service manages a parameter for a network filter.
Name | Summary |
---|---|
|
Retrieves a representation of the network filter parameter. |
|
Removes the filter parameter. |
|
Updates the network filter parameter. |
5.127.1. get GET
Retrieves a representation of the network filter parameter.
Name | Type | Direction | Summary |
---|---|---|---|
|
Out |
The representation of the network filter parameter. |
5.127.2. remove DELETE
Removes the filter parameter.
For example, to remove the filter parameter with id 123
on NIC 456
of virtual machine 789
send a request like this:
DELETE /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123
5.127.3. update PUT
Updates the network filter parameter.
For example, to update the network filter parameter having with with id 123
on NIC 456
of
virtual machine 789
send a request like this:
PUT /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123
With a request body like this:
<network_filter_parameter>
<name>updatedName</name>
<value>updatedValue</value>
</network_filter_parameter>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The network filter parameter that is being updated. |
5.128. NetworkFilterParameters
This service manages a collection of parameters for network filters.
Name | Summary |
---|---|
|
Add a network filter parameter. |
|
Retrieves the representations of the network filter parameters. |
5.128.1. add POST
Add a network filter parameter.
For example, to add the parameter for the network filter on NIC 456
of
virtual machine 789
send a request like this:
POST /ovirt-engine/api/vms/789/nics/456/networkfilterparameters
With a request body like this:
<network_filter_parameter>
<name>IP</name>
<value>10.0.1.2</value>
</network_filter_parameter>
Name | Type | Direction | Summary |
---|---|---|---|
|
In/Out |
The network filter parameter that is being added. |
5.129. NetworkFilters
Represents a readonly network filters sub-collection.
The network filter enables to filter packets send to/from the VM’s nic according to defined rules. For more information please refer to NetworkFilter service documentation
Network filters are supported in different versions, starting from version 3.0.
A network filter is defined for each vnic profile.
A vnic profile is defined for a specific network.
A network can be assigned to several different clusters. In the future, each network will be defined in cluster level.
Currently, each network is being defined at data center level. Potential network filters for each network are determined by the network’s data center compatibility version V. V must be >= the network filter version in order to configure this network filter for a specific network. Please note, that if a network is assigned to cluster with a version supporting a network filter, the filter may not be available due to the data center version being smaller then the network filter’s version.
Example of listing all of the supported network filters for a specific cluster:
GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters
Output:
<network_filters>
<network_filter id="00000019-0019-0019-0019