此内容没有您所选择的语言版本。
Chapter 6. Services
This section enumerates all the services that are available in the API.
6.1. AffinityGroup
This service manages a single affinity group.
Name | Summary |
---|---|
| Retrieve the affinity group details. |
| Remove the affinity group. |
| Update the affinity group. |
6.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. |
6.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 removal should be performed asynchronously. |
6.1.3. update PUT
Update the affinity group.
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the update should be performed asynchronously. | |
| In/Out | The affinity group. |
6.2. AffinityGroupVm
This service manages a single virtual machine to affinity group assignment.
Name | Summary |
---|---|
| Remove this virtual machine from the affinity group. |
6.2.1. remove DELETE
Remove this virtual machine from the affinity group.
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the removal should be performed asynchronously. |
6.3. AffinityGroupVms
This service manages a collection of all the 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. |
6.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 |
6.3.2. list GET
List all virtual machines assigned to this affinity group.
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of virtual machines to return. | |
| Out |
6.3.2.1. max
Sets the maximum number of virtual machines to return. If not specified, all the virtual machines are returned.
6.4. AffinityGroups
The affinity groups service manages virtual machine relationships and dependencies.
Name | Summary |
---|---|
| Create a new affinity group. |
| List existing affinity groups. |
6.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. |
6.4.2. list GET
List existing affinity groups.
Name | Type | Direction | Summary |
---|---|---|---|
| Out | The list of existing affinity groups. | |
| In | Sets the maximum number of affinity groups to return. |
6.4.2.1. max
Sets the maximum number of affinity groups to return. If not specified all the affinity groups are returned.
6.5. AffinityLabel
The details of a single affinity label.
Name | Summary |
---|---|
| Retrieves the details of a label. |
| Removes a label from the system and clears all assignments of the removed label. |
| Updates a label. |
6.5.1. get GET
Retrieves the details of a label.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.5.2. remove DELETE
Removes a label from the system and clears all assignments of the removed label.
6.5.3. update PUT
Updates a label. This call will update all metadata, such as the name or description.
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.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. |
6.6.1. get GET
Retrieves details about a host that has this label assigned.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.6.2. remove DELETE
Remove a label from a host.
6.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. |
6.7.1. add POST
Add a label to a host.
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.7.2. list GET
List all hosts with the label.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.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. |
6.8.1. get GET
Retrieves details about a vm that has this label assigned.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.8.2. remove DELETE
Remove a label from a vm.
6.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. |
6.9.1. add POST
Add a label to a vm.
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.9.2. list GET
List all vms with the label.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.10. AffinityLabels
Manages the affinity labels available in the system.
Name | Summary |
---|---|
| Creates a new label. |
| Lists all labels present in the system. |
6.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 |
6.10.2. list GET
Lists all labels present in the system.
Name | Type | Direction | Summary |
---|---|---|---|
| Out | ||
| In | Sets the maximum number of labels to return. |
6.10.2.1. max
Sets the maximum number of labels to return. If not specified all the labels are returned.
6.11. 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. |
6.11.1. get GET
Retrieves details about the attached label.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.11.2. remove DELETE
Removes the label from an entity. Does not touch the label itself.
6.12. 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. |
6.12.1. add POST
Attaches a label to an entity.
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.12.2. list GET
Lists all labels that are attached to an entity.
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.13. AssignedCpuProfile
Name | Summary |
---|---|
| |
|
6.13.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.13.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.14. AssignedCpuProfiles
Name | Summary |
---|---|
| |
|
6.14.1. add POST
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.14.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of profiles to return. | |
| Out |
6.14.2.1. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.15. AssignedDiskProfile
Name | Summary |
---|---|
| |
|
6.15.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.15.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.16. AssignedDiskProfiles
Name | Summary |
---|---|
| |
|
6.16.1. add POST
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.16.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of profiles to return. | |
| Out |
6.16.2.1. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.17. 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. |
6.17.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. |
6.17.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. |
6.18. AssignedRoles
Represents a roles sub-collection, for example scoped by user.
Name | Summary |
---|---|
|
6.18.1. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of roles to return. | |
| Out |
6.18.1.1. max
Sets the maximum number of roles to return. If not specified all the roles are returned.
6.19. 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. |
6.19.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. |
6.19.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. |
6.20. 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. |
6.20.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. |
6.20.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. |
6.20.2.1. max
Sets the maximum number of tags to return. If not specified all the tags are returned.
6.21. AssignedVnicProfile
Name | Summary |
---|---|
| |
|
6.21.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.21.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.22. AssignedVnicProfiles
Name | Summary |
---|---|
| |
|
6.22.1. add POST
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.22.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of profiles to return. | |
| Out |
6.22.2.1. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.23. AttachedStorageDomain
Name | Summary |
---|---|
| This operation activates an attached storage domain. |
| This operation deactivates an attached storage domain. |
| |
|
6.23.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. |
6.23.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. |
6.23.3. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.23.4. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.24. AttachedStorageDomains
Name | Summary |
---|---|
| |
|
6.24.1. add POST
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.24.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of storage domains to return. | |
| Out |
6.24.2.1. max
Sets the maximum number of storage domains to return. If not specified all the storage domains are returned.
6.25. Balance
Name | Summary |
---|---|
| |
|
6.25.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out | ||
| In | Indicates if the results should be filtered according to the permissions of the user. |
6.25.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.26. Balances
Name | Summary |
---|---|
| |
|
6.26.1. add POST
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.26.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out | ||
| In | Indicates if the results should be filtered according to the permissions of the user. | |
| In | Sets the maximum number of balances to return. |
6.26.2.1. max
Sets the maximum number of balances to return. If not specified all the balances are returned.
6.27. Bookmark
A service to manage a bookmark.
Name | Summary |
---|---|
| Get a bookmark. |
| Remove a bookmark. |
| Update a bookmark. |
6.27.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. |
6.27.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. |
6.27.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. |
6.28. Bookmarks
A service to manage bookmarks.
Name | Summary |
---|---|
| Adding a new bookmark. |
| Listing all the available bookmarks. |
6.28.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. |
6.28.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. |
6.28.2.1. max
Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned.
6.29. Cluster
A service to manage specific cluster.
Name | Summary |
---|---|
| Get information about the cluster. |
| Removes cluster from the system. |
| |
| Updates information about the cluster. |
6.29.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. |
6.29.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. |
6.29.3. resetemulatedmachine POST
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the reset should be performed asynchronously. |
6.29.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 |
6.30. 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. |
6.30.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. |
6.31. 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. |
6.31.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. |
6.32. ClusterNetwork
A service to manage a specific cluster network.
Name | Summary |
---|---|
| Retrieves the cluster network details. |
| Unassigns the network from a cluster. |
| Updates the network in the cluster. |
6.32.1. get GET
Retrieves the cluster network details.
Name | Type | Direction | Summary |
---|---|---|---|
| Out | The cluster network. |
6.32.2. remove DELETE
Unassigns the network from a cluster.
6.32.3. update PUT
Updates the network in the cluster.
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out | The cluster network. |
6.33. ClusterNetworks
A service to manage cluster networks.
Name | Summary |
---|---|
| Assigns the network to a cluster. |
| Lists the networks that are assigned to the cluster. |
6.33.1. add POST
Assigns the network to a cluster.
Post a request like in the example below to assign the network to a cluster:
POST /ovirt-engine/api/clusters/123/networks
Use the following example in its body:
<network id="123" />
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out | The network object to be assigned to the cluster. |
6.33.2. list GET
Lists the networks that are assigned to the cluster.
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of networks to return. | |
| Out | The list of networks that are assigned to the cluster. |
6.33.2.1. max
Sets the maximum number of networks to return. If not specified, all the networks are returned.
6.34. Clusters
A service to manage clusters.
Name | Summary |
---|---|
| Creates a new cluster. |
|
6.34.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 |
6.34.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. |
6.34.2.1. 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
.
6.34.2.2. max
Sets the maximum number of clusters to return. If not specified all the clusters are returned.
6.35. Copyable
Name | Summary |
---|---|
|
6.35.1. copy POST
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the copy should be performed asynchronously. |
6.36. CpuProfile
Name | Summary |
---|---|
| |
| |
|
6.36.1. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.36.2. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.36.3. update PUT
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the update should be performed asynchronously. | |
| In/Out |
6.37. CpuProfiles
Name | Summary |
---|---|
| |
|
6.37.1. add POST
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out |
6.37.2. list GET
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of profiles to return. | |
| Out |
6.37.2.1. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.38. DataCenter
A service to manage a data center.
Name | Summary |
---|---|
| Get a data center. |
| Removes the data center. |
| Updates the data center. |
6.38.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. |
6.38.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. |
6.38.2.1. force
Indicates if the operation should succeed, and the storage domain removed from the database, even if something fails during the operation.
This parameter is optional, and the default value is false
.
6.38.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. |
6.39. DataCenterNetwork
A service to manage a specific data center network.
Name | Summary |
---|---|
| Retrieves the data center network details. |
| Removes the network. |
| Updates the network in the data center. |
6.39.1. get GET
Retrieves the data center network details.
Name | Type | Direction | Summary |
---|---|---|---|
| Out | The data center network. |
6.39.2. remove DELETE
Removes the network.
6.39.3. update PUT
Updates the network in the data center.
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out | The data center network. |
6.40. DataCenterNetworks
A service to manage data center networks.
Name | Summary |
---|---|
| Create a new network in a data center. |
| Lists networks in the data center. |
6.40.1. add POST
Create a new network in a data center.
Post a request like in the example below to create a new network in a data center with an ID of 123
.
POST /ovirt-engine/api/datacenters/123/networks
Use the following example in its body:
<network> <name>mynetwork</name> </network>
Name | Type | Direction | Summary |
---|---|---|---|
| In/Out | The network object to be created in the data center. |
6.40.2. list GET
Lists networks in the data center.
Name | Type | Direction | Summary |
---|---|---|---|
| In | Sets the maximum number of networks to return. | |
| Out | The list of networks which are in the data center. |
6.40.2.1. max
Sets the maximum number of networks to return. If not specified, all the networks are returned.
6.41. DataCenters
A service to manage data centers.
Name | Summary |
---|---|
| Creates a new data center. |
| Lists the data centers. |
6.41.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. |
6.41.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. |
6.41.2.1. 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
.
6.41.2.2. max
Sets the maximum number of data centers to return. If not specified all the data centers are returned.
6.42. Disk
Manages a single disk.
Name | Summary |
---|---|
| This operation copies a disk to the specified storage domain. |
| |
| |
| Moves a disk to another storage domain. |
| |
| Sparsify the disk. |
6.42.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 | ||
| In | Indicates if the results should be filtered according to the permissions of the user. | |
| In |
6.42.2. export POST
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 |
6.42.3. get GET
Name | Type | Direction | Summary |
---|---|---|---|
| Out |
6.42.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 |
6.42.5. remove DELETE
Name | Type | Direction | Summary |
---|---|---|---|
| In | Indicates if the remove should be performed asynchronously. |
6.42.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.
6.43. 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. |
6.43.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 |
6.43.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. |
6.43.2.1. detach_only
Indicates if the disk should only be detached from the virtual machine, but not removed from the system. The default value is true
, which won’t remove the disk from the system.
6.43.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 |
6.44. 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. |
6.44.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> <pa