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.
Table 6.1. Methods summary
| 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>
Table 6.2. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | The affinity group. |
6.1.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.1.2. remove DELETE
Remove the affinity group.
DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
Table 6.3. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the removal should be performed asynchronously. |
6.1.3. update PUT
Update the affinity group.
Table 6.4. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the update should be performed asynchronously. | |
|
| In/Out | The affinity group. |
6.2. AffinityGroupHost
This service manages a single host to affinity group assignment.
Table 6.5. Methods summary
| Name | Summary |
|---|---|
|
| Remove host from the affinity group. |
6.2.1. remove DELETE
Remove host from the affinity group.
Table 6.6. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the removal should be performed asynchronously. |
6.3. AffinityGroupHostLabel
This service manages a single host label assigned to an affinity group.
Table 6.7. Methods summary
| Name | Summary |
|---|---|
|
| Remove this label from the affinity group. |
6.3.1. remove DELETE
Remove this label from the affinity group.
Table 6.8. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the removal should be performed asynchronously. |
6.4. AffinityGroupHostLabels
This service manages a collection of all host labels assigned to an affinity group.
Table 6.9. Methods summary
| Name | Summary |
|---|---|
|
| Adds a host label to the affinity group. |
|
| List all host labels assigned to this affinity group. |
6.4.1. add POST
Adds a host label to the affinity group.
For example, to add the label 789 to the affinity group 456 of cluster 123, send a request like this:
POST /ovirt-engine/api/clusters/123/affinitygroups/456/hostlabels
With the following body:
<affinity_label id="789"/>
Table 6.10. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The AffinityLabel object to add to the affinity group. |
6.4.2. list GET
List all host labels assigned to this affinity group.
The order of the returned labels isn’t guaranteed.
Table 6.11. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | Host labels assigned to the affinity group. | |
|
| In | Sets the maximum number of host labels to return. |
6.4.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.4.2.2. max
Sets the maximum number of host labels to return. If not specified, all the labels are returned.
6.5. AffinityGroupHosts
This service manages a collection of all hosts assigned to an affinity group.
Table 6.12. Methods summary
| Name | Summary |
|---|---|
|
| Adds a host to the affinity group. |
|
| List all hosts assigned to this affinity group. |
6.5.1. add POST
Adds a host to the affinity group.
For example, to add the host 789 to the affinity group 456 of cluster 123, send a request like this:
POST /ovirt-engine/api/clusters/123/affinitygroups/456/hosts
With the following body:
<host id="789"/>
Table 6.13. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The host to be added to the affinity group. |
6.5.2. list GET
List all hosts assigned to this affinity group.
The order of the returned hosts isn’t guaranteed.
Table 6.14. Parameters summary
6.5.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.5.2.2. max
Sets the maximum number of hosts to return. If not specified, all the hosts are returned.
6.6. AffinityGroupVm
This service manages a single virtual machine to affinity group assignment.
Table 6.15. Methods summary
| Name | Summary |
|---|---|
|
| Remove this virtual machine from the affinity group. |
6.6.1. remove DELETE
Remove this virtual machine from the affinity group.
Table 6.16. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the removal should be performed asynchronously. |
6.7. AffinityGroupVmLabel
This service manages a single virtual machine label assigned to an affinity group.
Table 6.17. Methods summary
| Name | Summary |
|---|---|
|
| Remove this label from the affinity group. |
6.7.1. remove DELETE
Remove this label from the affinity group.
Table 6.18. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the removal should be performed asynchronously. |
6.8. AffinityGroupVmLabels
This service manages a collection of all virtual machine labels assigned to an affinity group.
Table 6.19. Methods summary
| Name | Summary |
|---|---|
|
| Adds a virtual machine label to the affinity group. |
|
| List all virtual machine labels assigned to this affinity group. |
6.8.1. add POST
Adds a virtual machine label to the affinity group.
For example, to add the label 789 to the affinity group 456 of cluster 123, send a request like this:
POST /ovirt-engine/api/clusters/123/affinitygroups/456/vmlabels
With the following body:
<affinity_label id="789"/>
Table 6.20. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The AffinityLabel object to add to the affinity group. |
6.8.2. list GET
List all virtual machine labels assigned to this affinity group.
The order of the returned labels isn’t guaranteed.
Table 6.21. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | Virtual machine labels assigned to the affinity group. | |
|
| In | Sets the maximum number of virtual machine labels to return. |
6.8.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.8.2.2. max
Sets the maximum number of virtual machine labels to return. If not specified, all the labels are returned.
6.9. AffinityGroupVms
This service manages a collection of all the virtual machines assigned to an affinity group.
Table 6.22. Methods summary
| Name | Summary |
|---|---|
|
| Adds a virtual machine to the affinity group. |
|
| List all virtual machines assigned to this affinity group. |
6.9.1. add POST
Adds a virtual machine to the affinity group.
For example, to add the virtual machine 789 to the affinity group 456 of cluster 123, send a request like this:
POST /ovirt-engine/api/clusters/123/affinitygroups/456/vms
With the following body:
<vm id="789"/>
Table 6.23. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.9.2. list GET
List all virtual machines assigned to this affinity group.
The order of the returned virtual machines isn’t guaranteed.
Table 6.24. Parameters summary
6.9.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.9.2.2. max
Sets the maximum number of virtual machines to return. If not specified, all the virtual machines are returned.
6.10. AffinityGroups
The affinity groups service manages virtual machine relationships and dependencies.
Table 6.25. Methods summary
| Name | Summary |
|---|---|
|
| Create a new affinity group. |
|
| List existing affinity groups. |
6.10.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>
<hosts_rule>
<enforcing>true</enforcing>
<positive>true</positive>
</hosts_rule>
<vms_rule>
<enabled>false</enabled>
</vms_rule>
</affinity_group>Table 6.26. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The affinity group object to create. |
6.10.2. list GET
List existing affinity groups.
The order of the affinity groups results isn’t guaranteed.
Table 6.27. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | The list of existing affinity groups. | |
|
| In | Sets the maximum number of affinity groups to return. |
6.10.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.10.2.2. max
Sets the maximum number of affinity groups to return. If not specified all the affinity groups are returned.
6.11. AffinityLabel
The details of a single affinity label.
Table 6.28. Methods summary
| 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.11.1. get GET
Retrieves the details of a label.
Table 6.29. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.11.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.11.2. remove DELETE
Removes a label from the system and clears all assignments of the removed label.
6.11.3. update PUT
Updates a label. This call will update all metadata, such as the name or description.
Table 6.30. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.12. AffinityLabelHost
This service represents a host that has a specific label when accessed through the affinitylabels/hosts subcollection.
Table 6.31. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves details about a host that has this label assigned. |
|
| Remove a label from a host. |
6.12.1. get GET
Retrieves details about a host that has this label assigned.
Table 6.32. Parameters summary
6.12.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.12.2. remove DELETE
Remove a label from a host.
6.13. AffinityLabelHosts
This service represents list of hosts that have a specific label when accessed through the affinitylabels/hosts subcollection.
Table 6.33. Methods summary
| Name | Summary |
|---|---|
|
| Add a label to a host. |
|
| List all hosts with the label. |
6.13.1. add POST
Add a label to a host.
Table 6.34. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.13.2. list GET
List all hosts with the label.
The order of the returned hosts isn’t guaranteed.
Table 6.35. Parameters summary
6.13.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.14. AffinityLabelVm
This service represents a vm that has a specific label when accessed through the affinitylabels/vms subcollection.
Table 6.36. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves details about a vm that has this label assigned. |
|
| Remove a label from a vm. |
6.14.1. get GET
Retrieves details about a vm that has this label assigned.
Table 6.37. Parameters summary
6.14.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.14.2. remove DELETE
Remove a label from a vm.
6.15. AffinityLabelVms
This service represents list of vms that have a specific label when accessed through the affinitylabels/vms subcollection.
Table 6.38. Methods summary
| Name | Summary |
|---|---|
|
| Add a label to a vm. |
|
| List all virtual machines with the label. |
6.15.1. add POST
Add a label to a vm.
Table 6.39. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.15.2. list GET
List all virtual machines with the label.
The order of the returned virtual machines isn’t guaranteed.
Table 6.40. Parameters summary
6.15.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.16. AffinityLabels
Manages the affinity labels available in the system.
Table 6.41. Methods summary
| Name | Summary |
|---|---|
|
| Creates a new label. |
|
| Lists all labels present in the system. |
6.16.1. add POST
Creates a new label. The label is automatically attached to all entities mentioned in the vms or hosts lists.
Table 6.42. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.16.2. list GET
Lists all labels present in the system.
The order of the returned labels isn’t guaranteed.
Table 6.43. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | ||
|
| In | Sets the maximum number of labels to return. |
6.16.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.16.2.2. max
Sets the maximum number of labels to return. If not specified all the labels are returned.
6.17. 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
6.18. AssignedAffinityLabel
This service represents one label to entity assignment when accessed using the entities/affinitylabels subcollection.
Table 6.44. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves details about the attached label. |
|
| Removes the label from an entity. |
6.18.1. get GET
Retrieves details about the attached label.
Table 6.45. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.18.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.18.2. remove DELETE
Removes the label from an entity. Does not touch the label itself.
6.19. AssignedAffinityLabels
This service is used to list and manipulate affinity labels that are assigned to supported entities when accessed using entities/affinitylabels.
Table 6.46. Methods summary
| Name | Summary |
|---|---|
|
| Attaches a label to an entity. |
|
| Lists all labels that are attached to an entity. |
6.19.1. add POST
Attaches a label to an entity.
Table 6.47. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.19.2. list GET
Lists all labels that are attached to an entity.
The order of the returned entities isn’t guaranteed.
Table 6.48. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.19.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.20. AssignedCpuProfile
Table 6.49. Methods summary
| Name | Summary |
|---|---|
|
| |
|
|
6.20.1. get GET
Table 6.50. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.20.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.20.2. remove DELETE
Table 6.51. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.21. AssignedCpuProfiles
Table 6.52. Methods summary
| Name | Summary |
|---|---|
|
| Add a new cpu profile for the cluster. |
|
| List the CPU profiles assigned to the cluster. |
6.21.1. add POST
Add a new cpu profile for the cluster.
Table 6.53. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.21.2. list GET
List the CPU profiles assigned to the cluster.
The order of the returned CPU profiles isn’t guaranteed.
Table 6.54. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of profiles to return. | |
|
| Out |
6.21.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.21.2.2. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.22. AssignedDiskProfile
Table 6.55. Methods summary
| Name | Summary |
|---|---|
|
| |
|
|
6.22.1. get GET
Table 6.56. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | ||
|
| In | Indicates which inner links should be followed. |
6.22.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.22.2. remove DELETE
Table 6.57. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.23. AssignedDiskProfiles
Table 6.58. Methods summary
| Name | Summary |
|---|---|
|
| Add a new disk profile for the storage domain. |
|
| Returns the list of disk profiles assigned to the storage domain. |
6.23.1. add POST
Add a new disk profile for the storage domain.
Table 6.59. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.23.2. list GET
Returns the list of disk profiles assigned to the storage domain.
The order of the returned disk profiles isn’t guaranteed.
Table 6.60. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of profiles to return. | |
|
| Out |
6.23.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.23.2.2. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.24. AssignedPermissions
Represents a permission sub-collection, scoped by user, group or some entity type.
Table 6.61. Methods summary
| Name | Summary |
|---|---|
|
| Assign a new permission to a user or group for specific entity. |
|
| List all the permissions of the specific entity. |
6.24.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>Table 6.62. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The permission. |
6.24.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>The order of the returned permissions isn’t guaranteed.
Table 6.63. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | The list of permissions. |
6.24.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.25. AssignedRoles
Represents a roles sub-collection, for example scoped by user.
Table 6.64. Methods summary
| Name | Summary |
|---|---|
|
| Returns the roles assigned to the permission. |
6.25.1. list GET
Returns the roles assigned to the permission.
The order of the returned roles isn’t guaranteed.
Table 6.65. Parameters summary
6.25.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.25.1.2. max
Sets the maximum number of roles to return. If not specified all the roles are returned.
6.26. AssignedTag
A service to manage assignment of specific tag to specific entities in system.
Table 6.66. Methods summary
| Name | Summary |
|---|---|
|
| Gets the information about the assigned tag. |
|
| Unassign tag from specific entity in the system. |
6.26.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>
Table 6.67. Parameters summary
6.26.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.26.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
Table 6.68. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.27. AssignedTags
A service to manage collection of assignment of tags to specific entities in system.
Table 6.69. Methods summary
| Name | Summary |
|---|---|
|
| Assign tag to specific entity in the system. |
|
| List all tags assigned to the specific entity. |
6.27.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>
Table 6.70. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The assigned tag. |
6.27.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>The order of the returned tags isn’t guaranteed.
Table 6.71. Parameters summary
6.27.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.27.2.2. max
Sets the maximum number of tags to return. If not specified all the tags are returned.
6.28. AssignedVnicProfile
Table 6.72. Methods summary
| Name | Summary |
|---|---|
|
| |
|
|
6.28.1. get GET
Table 6.73. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.28.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.28.2. remove DELETE
Table 6.74. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.29. AssignedVnicProfiles
Table 6.75. Methods summary
| Name | Summary |
|---|---|
|
| Add a new virtual network interface card profile for the network. |
|
| Returns the list of VNIC profiles assifned to the network. |
6.29.1. add POST
Add a new virtual network interface card profile for the network.
Table 6.76. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.29.2. list GET
Returns the list of VNIC profiles assifned to the network.
The order of the returned VNIC profiles isn’t guaranteed.
Table 6.77. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of profiles to return. | |
|
| Out |
6.29.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.29.2.2. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.30. AttachedStorageDomain
Table 6.78. Methods summary
| Name | Summary |
|---|---|
|
| This operation activates an attached storage domain. |
|
| This operation deactivates an attached storage domain. |
|
| |
|
|
6.30.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/>
Table 6.79. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the activation should be performed asynchronously. |
6.30.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. For example, to deactivate storage domain 456, send the following request:
POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate
With a request body like this:
<action/>
If the force parameter is true then the operation will succeed, even if the OVF update which takes place before the deactivation of the storage domain failed. If the force parameter is false and the OVF update failed, the deactivation of the storage domain will also fail.
Table 6.80. Parameters summary
6.30.2.1. force
Indicates if the operation should succeed and the storage domain should be moved to a deactivated state, even if the OVF update for the storage domain failed. For example, to deactivate storage domain 456 using force flag, send the following request:
POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate
With a request body like this:
<action> <force>true</force> <action>
This parameter is optional, and the default value is false.
6.30.3. get GET
Table 6.81. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.30.3.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.30.4. remove DELETE
Table 6.82. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.31. 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.
Table 6.83. Methods summary
| 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. |
6.31.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.
Table 6.84. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Description of the resulting disk. | |
|
| In | The storage domain where the new disk will be created. |
6.31.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.
Table 6.85. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | The export storage domain where the disk should be exported to. |
6.31.3. get GET
Retrieves the description of the disk.
Table 6.86. Parameters summary
6.31.3.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.31.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.
Table 6.87. Parameters summary
| 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. |
6.31.5. register POST
Registers an unregistered disk.
6.31.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.
6.31.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.
6.31.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.
Table 6.88. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The update to apply to the disk. |
6.32. AttachedStorageDomainDisks
Manages the collection of disks available inside an storage domain that is attached to a data center.
Table 6.89. Methods summary
| Name | Summary |
|---|---|
|
| Adds or registers a disk. |
|
| Retrieve the list of disks that are available in the storage domain. |
6.32.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.
Table 6.90. Parameters summary
6.32.1.1. 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.
6.32.2. list GET
Retrieve the list of disks that are available in the storage domain.
Table 6.91. Parameters summary
6.32.2.1. disks
List of retrieved disks.
The order of the returned disks isn’t guaranteed.
6.32.2.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.32.2.3. max
Sets the maximum number of disks to return. If not specified all the disks are returned.
6.33. AttachedStorageDomains
Manages the storage domains attached to a data center.
Table 6.92. Methods summary
| Name | Summary |
|---|---|
|
| Attaches an existing storage domain to the data center. |
|
| Returns the list of storage domains attached to the data center. |
6.33.1. add POST
Attaches an existing storage domain to the data center.
Table 6.93. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The storage domain to attach to the data center. |
6.33.2. list GET
Returns the list of storage domains attached to the data center.
The order of the returned storage domains isn’t guaranteed.
Table 6.94. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of storage domains to return. | |
|
| Out | A list of storage domains that are attached to the data center. |
6.33.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.33.2.2. max
Sets the maximum number of storage domains to return. If not specified all the storage domains are returned.
6.34. Balance
Table 6.95. Methods summary
| Name | Summary |
|---|---|
|
| |
|
|
6.34.1. get GET
Table 6.96. Parameters summary
6.34.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.34.2. remove DELETE
Table 6.97. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.35. Balances
Table 6.98. Methods summary
| Name | Summary |
|---|---|
|
| Add a balance module to a specified user defined scheduling policy. |
|
| Returns the list of balance modules used by the scheduling policy. |
6.35.1. add POST
Add a balance module to a specified user defined scheduling policy.
Table 6.99. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.35.2. list GET
Returns the list of balance modules used by the scheduling policy.
The order of the returned balance modules isn’t guaranteed.
Table 6.100. Parameters summary
6.35.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.35.2.2. max
Sets the maximum number of balances to return. If not specified all the balances are returned.
6.36. Bookmark
A service to manage a bookmark.
Table 6.101. Methods summary
| Name | Summary |
|---|---|
|
| Get a bookmark. |
|
| Remove a bookmark. |
|
| Update a bookmark. |
6.36.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>
Table 6.102. Parameters summary
6.36.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.36.2. remove DELETE
Remove a bookmark.
An example for removing a bookmark:
DELETE /ovirt-engine/api/bookmarks/123
Table 6.103. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.36.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>
6.37. Bookmarks
A service to manage bookmarks.
Table 6.105. Methods summary
| Name | Summary |
|---|---|
|
| Adding a new bookmark. |
|
| Listing all the available bookmarks. |
6.37.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>
Table 6.106. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The added bookmark. |
6.37.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>The order of the returned bookmarks isn’t guaranteed.
Table 6.107. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | The list of available bookmarks. | |
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of bookmarks to return. |
6.37.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.37.2.2. max
Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned.
6.38. Cluster
A service to manage a specific cluster.
Table 6.108. Methods summary
| Name | Summary |
|---|---|
|
| Gets information about the cluster. |
|
| Refresh the Gluster heal info for all volumes in cluster. |
|
| Removes the cluster from the system. |
|
| |
|
| Synchronizes all networks on the cluster. |
|
| Updates information about the cluster. |
|
| Start or finish upgrade process for the cluster based on the action value. |
6.38.1. get GET
Gets 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 Nehalem 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>
<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>
<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>Table 6.109. Parameters summary
6.38.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.38.2. refreshglusterhealstatus POST
Refresh the Gluster heal info for all volumes in cluster.
For example, Cluster 123, send a request like this:
POST /ovirt-engine/api/clusters/123/refreshglusterhealstatus
6.38.3. remove DELETE
Removes the cluster from the system.
DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Table 6.110. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.38.4. resetemulatedmachine POST
Table 6.111. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the reset should be performed asynchronously. |
6.38.5. syncallnetworks POST
Synchronizes all networks on the cluster.
POST /ovirt-engine/api/clusters/123/syncallnetworks
With a request body like this:
<action/>
Table 6.112. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the action should be performed asynchronously. |
6.38.6. update PUT
Updates information about the cluster.
Only the specified fields are updated; others remain unchanged.
For example, to update the cluster’s CPU:
PUT /ovirt-engine/api/clusters/123
With a request body like this:
<cluster>
<cpu>
<type>Intel Haswell-noTSX Family</type>
</cpu>
</cluster>6.38.7. upgrade POST
Start or finish upgrade process for the cluster based on the action value. This action marks the cluster for upgrade or clears the upgrade running flag on the cluster based on the action value which takes values of start or stop.
POST /ovirt-engine/api/clusters/123/upgrade
With a request body like this to mark the cluster for upgrade:
<action>
<upgrade_action>
start
</upgrade_action>
</action>Table 6.114. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the action should be performed asynchronously. | |
|
| In | The action to be performed. |
6.39. ClusterEnabledFeature
Represents a feature enabled for the cluster.
Table 6.115. Methods summary
| Name | Summary |
|---|---|
|
| Provides the information about the cluster feature enabled. |
|
| Disables a cluster feature. |
6.39.1. get GET
Provides the information about the cluster feature enabled.
For example, to find details of the enabled feature 456 for cluster 123, send a request like this:
GET /ovirt-engine/api/clusters/123/enabledfeatures/456
That will return a ClusterFeature object containing the name:
<cluster_feature id="456"> <name>libgfapi_supported</name> </cluster_feature>
Table 6.116. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | Retrieved cluster feature that’s enabled. | |
|
| In | Indicates which inner links should be followed. |
6.39.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.39.2. remove DELETE
Disables a cluster feature.
For example, to disable the feature 456 of cluster 123 send a request like this:
DELETE /ovirt-engine/api/clusters/123/enabledfeatures/456
6.40. ClusterEnabledFeatures
Provides information about the additional features that are enabled for this cluster. The features that are enabled are the available features for the cluster level
Table 6.117. Methods summary
| Name | Summary |
|---|---|
|
| Enable an additional feature for a cluster. |
|
| Lists the additional features enabled for the cluster. |
6.40.1. add POST
Enable an additional feature for a cluster.
For example, to enable a feature 456 on cluster 123, send a request like this:
POST /ovirt-engine/api/clusters/123/enabledfeatures
The request body should look like this:
<cluster_feature id="456"/>
Table 6.118. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.40.2. list GET
Lists the additional features enabled for the cluster.
For example, to get the features enabled for cluster 123 send a request like this:
GET /ovirt-engine/api/clusters/123/enabledfeatures
This will return a list of features:
<enabled_features>
<cluster_feature id="123">
<name>test_feature</name>
</cluster_feature>
...
</enabled_features>Table 6.119. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | Retrieved features. | |
|
| In | Indicates which inner links should be followed. |
6.40.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.41. ClusterExternalProviders
This service lists external providers.
Table 6.120. Methods summary
| Name | Summary |
|---|---|
|
| Returns the list of external providers. |
6.41.1. list GET
Returns the list of external providers.
The order of the returned list of providers is not guaranteed.
Table 6.121. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.41.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.42. ClusterFeature
Represents a feature enabled for the cluster level
Table 6.122. Methods summary
| Name | Summary |
|---|---|
|
| Provides the information about the a cluster feature supported by a cluster level. |
6.42.1. get GET
Provides the information about the a cluster feature supported by a cluster level.
For example, to find details of the cluster feature 456 for cluster level 4.1, send a request like this:
GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures/456
That will return a ClusterFeature object containing the name:
<cluster_feature id="456"> <name>libgfapi_supported</name> </cluster_feature>
Table 6.123. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | Retrieved cluster feature. | |
|
| In | Indicates which inner links should be followed. |
6.42.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.43. ClusterFeatures
Provides information about the cluster features that are supported by a cluster level.
Table 6.124. Methods summary
| Name | Summary |
|---|---|
|
| Lists the cluster features supported by the cluster level. |
6.43.1. list GET
Lists the cluster features supported by the cluster level.
GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures
This will return a list of cluster features supported by the cluster level:
<cluster_features>
<cluster_feature id="123">
<name>test_feature</name>
</cluster_feature>
...
</cluster_features>Table 6.125. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | Retrieved features. | |
|
| In | Indicates which inner links should be followed. |
6.43.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.44. ClusterLevel
Provides information about a specific cluster level. See the ClusterLevels service for more information.
Table 6.126. Methods summary
| Name | Summary |
|---|---|
|
| Provides the information about the capabilities of the specific cluster level managed by this service. |
6.44.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 Nehalem 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>Table 6.127. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | Retreived cluster level. |
6.44.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.45. 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.
Table 6.128. Methods summary
| Name | Summary |
|---|---|
|
| Lists the cluster levels supported by the system. |
6.45.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>The order of the returned cluster levels isn’t guaranteed.
Table 6.129. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | Retrieved cluster levels. |
6.45.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.46. ClusterNetwork
A service to manage a specific cluster network.
Table 6.130. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves the cluster network details. |
|
| Unassigns the network from a cluster. |
|
| Updates the network in the cluster. |
6.46.1. get GET
Retrieves the cluster network details.
Table 6.131. Parameters summary
6.46.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.46.2. remove DELETE
Unassigns the network from a cluster.
6.46.3. update PUT
Updates the network in the cluster.
Table 6.132. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The cluster network. |
6.47. ClusterNetworks
A service to manage cluster networks.
Table 6.133. Methods summary
| Name | Summary |
|---|---|
|
| Assigns the network to a cluster. |
|
| Lists the networks that are assigned to the cluster. |
6.47.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" />
Table 6.134. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The network object to be assigned to the cluster. |
6.47.2. list GET
Lists the networks that are assigned to the cluster.
The order of the returned clusters isn’t guaranteed.
Table 6.135. Parameters summary
6.47.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.47.2.2. max
Sets the maximum number of networks to return. If not specified, all the networks are returned.
6.48. Clusters
A service to manage clusters.
Table 6.136. Methods summary
| Name | Summary |
|---|---|
|
| Creates a new cluster. |
|
| Returns the list of clusters of the system. |
6.48.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 attribute.
POST /ovirt-engine/api/clusters
With a request body like this:
<cluster>
<name>mycluster</name>
<cpu>
<type>Intel Nehalem Family</type>
</cpu>
<data_center id="123"/>
</cluster>To create a cluster with an external network provider to be deployed on every host that is added to the cluster, send a request like this:
POST /ovirt-engine/api/clusters
With a request body containing a reference to the desired provider:
<cluster>
<name>mycluster</name>
<cpu>
<type>Intel Nehalem Family</type>
</cpu>
<data_center id="123"/>
<external_network_providers>
<external_provider name="ovirt-provider-ovn"/>
</external_network_providers>
</cluster>Table 6.137. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.48.2. list GET
Returns the list of clusters of the system.
The order of the returned clusters is guaranteed only if the sortby clause is included in the search parameter.
Table 6.138. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the search should be performed taking case into account. | |
|
| Out | ||
|
| In | Indicates if the results should be filtered according to the permissions of the user. | |
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of clusters to return. | |
|
| In | A query string used to restrict the returned clusters. |
6.48.2.1. case_sensitive
Indicates if the search should be performed taking case into account. The default value is true, which means that case is taken into account. To search ignoring case, set it to false.
6.48.2.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.48.2.3. max
Sets the maximum number of clusters to return. If not specified, all the clusters are returned.
6.49. Copyable
Table 6.139. Methods summary
| Name | Summary |
|---|---|
|
|
6.49.1. copy POST
Table 6.140. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the copy should be performed asynchronously. |
6.50. CpuProfile
Table 6.141. Methods summary
| Name | Summary |
|---|---|
|
| |
|
| |
|
| Update the specified cpu profile in the system. |
6.50.1. get GET
Table 6.142. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.50.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.50.2. remove DELETE
Table 6.143. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.50.3. update PUT
Update the specified cpu profile in the system.
Table 6.144. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the update should be performed asynchronously. | |
|
| In/Out |
6.51. CpuProfiles
Table 6.145. Methods summary
| Name | Summary |
|---|---|
|
| Add a new cpu profile to the system. |
|
| Returns the list of CPU profiles of the system. |
6.51.1. add POST
Add a new cpu profile to the system.
Table 6.146. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.51.2. list GET
Returns the list of CPU profiles of the system.
The order of the returned list of CPU profiles is random.
Table 6.147. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of profiles to return. | |
|
| Out |
6.51.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.51.2.2. max
Sets the maximum number of profiles to return. If not specified, all the profiles are returned.
6.52. DataCenter
A service to manage a data center.
Table 6.148. Methods summary
| Name | Summary |
|---|---|
|
| Get a data center. |
|
| Removes the data center. |
|
| Updates the data center. |
6.52.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>Table 6.149. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | ||
|
| In | Indicates if the results should be filtered according to the permissions of the user. | |
|
| In | Indicates which inner links should be followed. |
6.52.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.52.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.
Table 6.150. Parameters summary
6.52.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.52.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>
Table 6.151. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the update should be performed asynchronously. | |
|
| In/Out | The data center that is being updated. |
6.53. DataCenterNetwork
A service to manage a specific data center network.
Table 6.152. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves the data center network details. |
|
| Removes the network. |
|
| Updates the network in the data center. |
6.53.1. get GET
Retrieves the data center network details.
Table 6.153. Parameters summary
6.53.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.53.2. remove DELETE
Removes the network.
6.53.3. update PUT
Updates the network in the data center.
Table 6.154. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The data center network. |
6.54. DataCenterNetworks
A service to manage data center networks.
Table 6.155. Methods summary
| Name | Summary |
|---|---|
|
| Create a new network in a data center. |
|
| Lists networks in the data center. |
6.54.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>
Table 6.156. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The network object to be created in the data center. |
6.54.2. list GET
Lists networks in the data center.
The order of the returned list of networks isn’t guaranteed.
Table 6.157. Parameters summary
6.54.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.54.2.2. max
Sets the maximum number of networks to return. If not specified, all the networks are returned.
6.55. DataCenters
A service to manage data centers.
Table 6.158. Methods summary
| Name | Summary |
|---|---|
|
| Creates a new data center. |
|
| Lists the data centers. |
6.55.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>
Table 6.159. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The data center that is being added. |
6.55.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.
The order of the returned list of data centers is guaranteed only if the sortby clause is included in the search parameter.
Table 6.160. Parameters summary
| 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 | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of data centers to return. | |
|
| In | A query string used to restrict the returned data centers. |
6.55.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.55.2.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.55.2.3. max
Sets the maximum number of data centers to return. If not specified all the data centers are returned.
6.56. Disk
Manages a single disk.
Table 6.161. Methods summary
| 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. |
|
| Reduces the size of the disk image. |
|
| Refreshes a direct LUN disk with up-to-date information from the storage. |
|
| Removes a disk. |
|
| Sparsify the disk. |
|
| Updates the parameters of the specified disk. |
6.56.1. copy POST
This operation copies a disk to the specified storage domain.
For example, a disk can be copied 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>If the disk profile or the quota currently used by the disk are not defined for the new storage domain, they can be explicitly specified. If they are not specified, the first available disk profile and the default quota are used.
For example, to specify disk profile 987 and quota 753, send a request body like this:
<action> <storage_domain id="456"/> <disk_profile id="987"/> <quota id="753"/> </action>
Table 6.162. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the copy should be performed asynchronously. | |
|
| In | ||
|
| In | Disk profile for the disk in the new storage domain. | |
|
| In | Indicates if the results should be filtered according to the permissions of the user. | |
|
| In | Quota for the disk in the new storage domain. | |
|
| In | The storage domain where the new disk is created. |
6.56.1.1. disk_profile
Disk profile for the disk in the new storage domain.
Disk profiles are defined for storage domains, so the old disk profile will not exist in the new storage domain. If this parameter is not used, the first disk profile from the new storage domain to which the user has permissions will be assigned to the disk.
6.56.1.2. quota
Quota for the disk in the new storage domain.
This optional parameter can be used to specify new quota for the disk, because the current quota may not be defined for the new storage domain. If this parameter is not used and the old quota is not defined for the new storage domain, the default (unlimited) quota will be assigned to the disk.
6.56.1.3. storage_domain
The storage domain where the new disk is created. This can be specified using the id or name attributes. For example, to copy a disk to the storage domain called 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>6.56.2. export POST
Exports a disk to an export storage domain.
Table 6.163. Parameters summary
| 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 will be exported to. |
6.56.3. get GET
Retrieves the description of the disk.
Table 6.164. Parameters summary
6.56.3.1. all_content
Indicates if all of the attributes of the disk should be included in the response.
By default the following disk attributes are excluded:
-
vms
For example, to retrieve the complete representation of disk '123':
GET /ovirt-engine/api/disks/123?all_content=true
6.56.3.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.56.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>
If the disk profile or the quota used currently by the disk aren’t defined for the new storage domain, then they can be explicitly specified. If they aren’t then the first available disk profile and the default quota are used.
For example, to explicitly use disk profile 987 and quota 753 send a request body like this:
<action> <storage_domain id="456"/> <disk_profile id="987"/> <quota id="753"/> </action>
Table 6.165. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the move should be performed asynchronously. | |
|
| In | Disk profile for the disk in the new storage domain. | |
|
| In | Indicates if the results should be filtered according to the permissions of the user. | |
|
| In | Quota for the disk in the new storage domain. | |
|
| In | The storage domain where the disk will be moved to. |
6.56.4.1. disk_profile
Disk profile for the disk in the new storage domain.
Disk profiles are defined for storage domains, so the old disk profile will not exist in the new storage domain. If this parameter is not used, the first disk profile from the new storage domain to which the user has permissions will be assigned to the disk.
6.56.4.2. quota
Quota for the disk in the new storage domain.
This optional parameter can be used to specify new quota for the disk, because the current quota may not be defined for the new storage domain. If this parameter is not used and the old quota is not defined for the new storage domain, the default (unlimited) quota will be assigned to the disk.
6.56.5. reduce POST
Reduces the size of the disk image.
Invokes reduce on the logical volume (i.e. this is only applicable for block storage domains). This is applicable for floating disks and disks attached to non-running virtual machines. There is no need to specify the size as the optimal size is calculated automatically.
Table 6.166. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.56.6. refreshlun POST
Refreshes a direct LUN disk with up-to-date information from the storage.
Refreshing a direct LUN disk is useful when:
- The LUN was added using the API without the host parameter, and therefore does not contain any information from the storage (see DisksService::add).
- New information about the LUN is available on the storage and you want to update the LUN with it.
To refresh direct LUN disk 123 using host 456, send the following request:
POST /ovirt-engine/api/disks/123/refreshlun
With the following request body:
<action> <host id='456'/> </action>
Table 6.167. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | The host that will be used to refresh the direct LUN disk. |
6.56.7. remove DELETE
Removes a disk.
Table 6.168. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.56.8. 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.56.9. update PUT
Updates the parameters of the specified disk.
This operation allows updating the following floating disk properties:
-
For Image disks:
provisioned_size,alias,description,wipe_after_delete,shareable,backupanddisk_profile. -
For LUN disks:
alias,descriptionandshareable. -
For Cinder and Managed Block disks:
provisioned_size,aliasanddescription. -
For VM attached disks, the
qcow_versioncan also be updated.
For example, a disk’s update can be done by using the following request:
PUT /ovirt-engine/api/disks/123
With a request body like this:
<disk> <qcow_version>qcow2_v3</qcow_version> <alias>new-alias</alias> <description>new-desc</description> </disk>
Since the backend operation is asynchronous, the disk element that is returned to the user might not be synced with the changed properties.
Table 6.169. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The update to apply to the disk. |
6.57. DiskAttachment
This service manages the attachment of a disk to a virtual machine.
Table 6.170. Methods summary
| 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.57.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>
Table 6.171. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | ||
|
| In | Indicates which inner links should be followed. |
6.57.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.57.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
Table 6.172. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the disk should only be detached from the virtual machine, but not removed from the system. |
6.57.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.57.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>Table 6.173. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.58. 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.
Table 6.174. Methods summary
| Name | Summary |
|---|---|
|
| Adds a new disk attachment to the virtual machine. |
|
| List the disk that are attached to the virtual machine. |
6.58.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.
Table 6.175. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The disk attachment to add to the virtual machine. |
6.58.2. list GET
List the disk that are attached to the virtual machine.
The order of the returned list of disks attachments isn’t guaranteed.
Table 6.176. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | A list of disk attachments that are attached to the virtual machine. | |
|
| In | Indicates which inner links should be followed. |
6.58.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.59. DiskProfile
Table 6.177. Methods summary
| Name | Summary |
|---|---|
|
| |
|
| |
|
| Update the specified disk profile in the system. |
6.59.1. get GET
Table 6.178. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.59.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.59.2. remove DELETE
Table 6.179. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.59.3. update PUT
Update the specified disk profile in the system.
Table 6.180. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the update should be performed asynchronously. | |
|
| In/Out |
6.60. DiskProfiles
Table 6.181. Methods summary
| Name | Summary |
|---|---|
|
| Add a new disk profile to the system. |
|
| Returns the list of disk profiles of the system. |
6.60.1. add POST
Add a new disk profile to the system.
Table 6.182. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.60.2. list GET
Returns the list of disk profiles of the system.
The order of the returned list of disk profiles isn’t guaranteed.
Table 6.183. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of profiles to return. | |
|
| Out |
6.60.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.60.2.2. max
Sets the maximum number of profiles to return. If not specified all the profiles are returned.
6.61. DiskSnapshot
Table 6.184. Methods summary
| Name | Summary |
|---|---|
|
| |
|
|
6.61.1. get GET
Table 6.185. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.61.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.61.2. remove DELETE
Table 6.186. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.62. DiskSnapshots
Manages the collection of disk snapshots available in an storage domain.
Table 6.187. Methods summary
| Name | Summary |
|---|---|
|
| Returns the list of disk snapshots of the storage domain. |
6.62.1. list GET
Returns the list of disk snapshots of the storage domain.
The order of the returned list of disk snapshots isn’t guaranteed.
Table 6.188. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | If true return also active snapshots. | |
|
| In | Sets the maximum number of snapshots to return. | |
|
| Out |
6.62.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.62.1.2. include_active
If true return also active snapshots. If not specified active snapshots are not returned.
6.62.1.3. max
Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.
6.63. Disks
Manages the collection of disks available in the system.
Table 6.189. Methods summary
| Name | Summary |
|---|---|
|
| Adds a new floating disk. |
|
| Get list of disks. |
6.63.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.
Note that block storage domains (i.e., storage domains with the storage type of iSCSI or FCP) don’t support the combination of the raw format with sparse=true, so sparse=false must be stated explicitly.
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
hostelement - 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
hostelement - 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>Adding a floating disks in order to upload disk snapshots:
Since version 4.2 of the engine it is possible to upload disks with snapshots. This request should be used to create the base image of the images chain (The consecutive disk snapshots (images), should be created using disk-attachments element when creating a snapshot).
The disk has to be created with the same disk identifier and image identifier of the uploaded image. I.e. the identifiers should be saved as part of the backup process. The image identifier can be also fetched using the qemu-img info command. For example, if the disk image is stored into a file named b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img:
$ qemu-img info b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img image: b548366b-fb51-4b41-97be-733c887fe305 file format: qcow2 virtual size: 1.0G (1073741824 bytes) disk size: 196K cluster_size: 65536 backing file: ad58716a-1fe9-481f-815e-664de1df04eb backing file format: raw
To create a disk with with the disk identifier and image identifier obtained with the qemu-img info command shown above, send a request like this:
POST /ovirt-engine/api/disks
With a request body as follows:
<disk id="b7a4c6c5-443b-47c5-967f-6abc79675e8b">
<image_id>b548366b-fb51-4b41-97be-733c887fe305</image_id>
<storage_domains>
<storage_domain id="123"/>
</storage_domains>
<name>mydisk</name>
<provisioned_size>1048576</provisioned_size>
<format>cow</format>
</disk>Table 6.190. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The disk. |
6.63.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>
The order of the returned list of disks is guaranteed only if the sortby clause is included in the search parameter.
Table 6.191. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In |
Indicates if the search performed using the | |
|
| Out | List of retrieved disks. | |
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of disks to return. | |
|
| In | A query string used to restrict the returned disks. |
6.63.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.63.2.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.63.2.3. max
Sets the maximum number of disks to return. If not specified all the disks are returned.
6.64. Domain
A service to view details of an authentication domain in the system.
Table 6.192. Methods summary
| Name | Summary |
|---|---|
|
| Gets the authentication domain information. |
6.64.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>Table 6.193. Parameters summary
6.64.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.65. DomainGroup
Table 6.194. Methods summary
| Name | Summary |
|---|---|
|
|
6.65.1. get GET
Table 6.195. Parameters summary
6.65.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.66. DomainGroups
Table 6.196. Methods summary
| Name | Summary |
|---|---|
|
| Returns the list of groups. |
6.66.1. list GET
Returns the list of groups.
The order of the returned list of groups isn’t guaranteed.
Table 6.197. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In |
Indicates if the search performed using the | |
|
| In | Indicates which inner links should be followed. | |
|
| Out | ||
|
| In | Sets the maximum number of groups to return. | |
|
| In | A query string used to restrict the returned groups. |
6.66.1.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.66.1.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.66.1.3. max
Sets the maximum number of groups to return. If not specified all the groups are returned.
6.67. DomainUser
A service to view a domain user in the system.
Table 6.198. Methods summary
| Name | Summary |
|---|---|
|
| Gets the domain user information. |
6.67.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>Table 6.199. Parameters summary
6.67.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.68. DomainUserGroups
A service that shows a user’s group membership in the AAA extension.
Table 6.200. Methods summary
| Name | Summary |
|---|---|
|
| Returns the list of groups that the user is a member of. |
6.68.1. list GET
Returns the list of groups that the user is a member of.
Table 6.201. Parameters summary
6.68.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.69. DomainUsers
A service to list all domain users in the system.
Table 6.202. Methods summary
| Name | Summary |
|---|---|
|
| List all the users in the domain. |
6.69.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>The order of the returned list of users isn’t guaranteed.
Table 6.203. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In |
Indicates if the search performed using the | |
|
| In | Indicates which inner links should be followed. | |
|
| 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. |
6.69.1.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.69.1.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.69.1.3. max
Sets the maximum number of users to return. If not specified all the users are returned.
6.70. Domains
A service to list all authentication domains in the system.
Table 6.204. Methods summary
| Name | Summary |
|---|---|
|
| List all the authentication domains in the system. |
6.70.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>The order of the returned list of domains isn’t guaranteed.
Table 6.205. Parameters summary
6.70.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.70.1.2. max
Sets the maximum number of domains to return. If not specified all the domains are returned.
6.71. EngineKatelloErrata
A service to manage Katello errata assigned to the engine. The information is retrieved from Katello.
Table 6.206. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves the representation of the Katello errata. |
6.71.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>The order of the returned list of erratum isn’t guaranteed.
Table 6.207. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | A representation of Katello errata. | |
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of errata to return. |
6.71.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.71.1.2. max
Sets the maximum number of errata to return. If not specified all the errata are returned.
6.72. Event
A service to manage an event in the system.
Table 6.208. Methods summary
| Name | Summary |
|---|---|
|
| Get an event. |
|
| Removes an event from internal audit log. |
6.72.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.
Table 6.209. Parameters summary
6.72.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.72.2. remove DELETE
Removes an event from internal audit log.
An event can be removed by sending following request
DELETE /ovirt-engine/api/events/123
Table 6.210. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.73. EventSubscription
A service to manage a specific event-subscription in the system.
Table 6.211. Methods summary
| Name | Summary |
|---|---|
|
| Gets the information about the event-subscription. |
|
| Removes the event-subscription from the system. |
6.73.1. get GET
Gets the information about the event-subscription.
For example to retrieve the information about the subscription of user '123' to the event 'vm_console_detected':
GET /ovirt-engine/api/users/123/vm_console_detected
<event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_console_detected"> <event>vm_console_detected</event> <notification_method>smtp</notification_method> <user href="/ovirt-engine/api/users/123" id="123"/> <address>a@b.com</address> </event-subscription>
Table 6.212. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | The event-subscription. |
6.73.2. remove DELETE
Removes the event-subscription from the system.
For example to remove user 123’s subscription to vm_console_detected event:
DELETE /ovirt-engine/api/users/123/vm_console_detected
Table 6.213. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.74. EventSubscriptions
Represents a service to manage collection of event-subscription of a user.
Table 6.214. Methods summary
| Name | Summary |
|---|---|
|
| Add a new event-subscription to the system. |
|
| List the event-subscriptions for the provided user. |
6.74.1. add POST
Add a new event-subscription to the system.
An event-subscription is always added in the context of a user. For example, to add new event-subscription for host_high_cpu_use for user 123, and have the notification sent to the e-mail address: a@b.com, send a request like this:
POST /ovirt-engine/api/users/123/eventsubscriptions
With a request body like this:
<event_subscription>
<event>host_high_cpu_use</event>
<address>a@b.com</address>
</event_subscription>The event name will become the ID of the new event-subscription entity: GET …/api/users/123/eventsubscriptions/host_high_cpu_use
Note that no user id is provided in the request body. This is because the user-id (in this case 123) is already known to the API from the context. Note also that event-subscription entity contains notification-method field, but it is not provided either in the request body. This is because currently it’s always set to SMTP as SNMP notifications are still unsupported by the API layer.
Table 6.215. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out | The added event-subscription. |
6.74.2. list GET
List the event-subscriptions for the provided user.
For example to list event-subscriptions for user 123:
GET /ovirt-engine/api/users/123/event-subscriptions
<event-subscriptions>
<event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/host_install_failed">
<event>host_install_failed</event>
<notification_method>smtp</notification_method>
<user href="/ovirt-engine/api/users/123" id="123"/>
<address>a@b.com</address>
</event-subscription>
<event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_paused">
<event>vm_paused</event>
<notification_method>smtp</notification_method>
<user href="/ovirt-engine/api/users/123" id="123"/>
<address>a@b.com</address>
</event-subscription>
</event-subscriptions>Table 6.216. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | List of the event-subscriptions for the specified user | |
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of event-subscriptions to return. |
6.74.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.74.2.2. max
Sets the maximum number of event-subscriptions to return. If not specified all the event-subscriptions are returned.
6.75. Events
A service to manage events in the system.
Table 6.217. Methods summary
| Name | Summary |
|---|---|
|
| Adds an external event to the internal audit log. |
|
| Get list of events. |
|
|
6.75.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.
Table 6.218. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.75.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.
The order of the returned list of events is always garanteed. If the sortby clause is included in the search parameter, then the events will be ordered according to that clause. If the sortby clause isn’t included, then the events will be sorted by the numeric value of the id attribute, starting with the highest value. This, combined with the max parameter, simplifies obtaining the most recent event:
GET /ovirt-engine/api/events?max=1
Table 6.219. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In |
Indicates if the search performed using the | |
|
| Out | ||
|
| In | Indicates which inner links should be followed. | |
|
| In | Indicates the event index after which events should be returned. | |
|
| In | Sets the maximum number of events to return. | |
|
| In | The events service provides search queries similar to other resource services. |
6.75.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.75.2.2. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.75.2.3. from
Indicates the event index after which events should be returned. The indexes of events are strictly increasing, so when this parameter is used only the events with greater indexes will be returned. For example, the following request will return only the events with indexes greater 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.
6.75.2.4. max
Sets the maximum number of events to return. If not specified all the events are returned.
6.75.2.5. 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
6.75.3. undelete POST
Table 6.220. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the un-delete should be performed asynchronously. |
6.76. ExternalComputeResource
Manages a single external compute resource.
Compute resource is a term of host external provider. The external provider also needs to know to where the provisioned host needs to register. The login details of the engine are saved as a compute resource in the external provider side.
Table 6.221. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves external compute resource details. |
6.76.1. get GET
Retrieves external compute resource details.
For example, to get the details of compute resource 234 of provider 123, send a request like this:
GET /ovirt-engine/api/externalhostproviders/123/computeresources/234
It will return a response like this:
<external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234"> <name>hostname</name> <provider>oVirt</provider> <url>https://hostname/api</url> <user>admin@internal</user> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_compute_resource>
Table 6.222. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | External compute resource information |
6.76.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.77. ExternalComputeResources
Manages a collection of external compute resources.
Compute resource is a term of host external provider. The external provider also needs to know to where the provisioned host needs to register. The login details of the engine is saved as a compute resource in the external provider side.
Table 6.223. Methods summary
| Name | Summary |
|---|---|
|
| Retrieves a list of external compute resources. |
6.77.1. list GET
Retrieves a list of external compute resources.
For example, to retrieve the compute resources of external host provider 123, send a request like this:
GET /ovirt-engine/api/externalhostproviders/123/computeresources
It will return a response like this:
<external_compute_resources>
<external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234">
<name>hostname</name>
<provider>oVirt</provider>
<url>https://address/api</url>
<user>admin@internal</user>
<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_compute_resource>
...
</external_compute_resources>The order of the returned list of compute resources isn’t guaranteed.
Table 6.224. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of resources to return. | |
|
| Out | List of external computer resources. |
6.77.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.77.1.2. max
Sets the maximum number of resources to return. If not specified all the resources are returned.
6.78. ExternalDiscoveredHost
This service manages a single discovered host.
Table 6.225. Methods summary
| Name | Summary |
|---|---|
|
| Get discovered host info. |
6.78.1. get GET
Get discovered host info.
Retrieves information about an host that is managed in external provider management system, such as Foreman. The information includes hostname, address, subnet, base image and more.
For example, to get the details of host 234 from provider 123, send a request like this:
GET /ovirt-engine/api/externalhostproviders/123/discoveredhosts/234
The result will be like this:
<external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/234" id="234"> <name>mac001a4ad04040</name> <ip>10.34.67.43</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:40</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host>
Table 6.226. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | Host’s hardware and config information. |
6.78.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.79. ExternalDiscoveredHosts
This service manages external discovered hosts.
Table 6.227. Methods summary
| Name | Summary |
|---|---|
|
| Get list of discovered hosts' information. |
6.79.1. list GET
Get list of discovered hosts' information.
Discovered hosts are fetched from third-party providers such as Foreman.
To list all discovered hosts for provider 123 send the following:
GET /ovirt-engine/api/externalhostproviders/123/discoveredhost
<external_discovered_hosts> <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/456" id="456"> <name>mac001a4ad04031</name> <ip>10.34.67.42</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:31</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/789" id="789"> <name>mac001a4ad04040</name> <ip>10.34.67.43</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:40</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> ... </external_discovered_hosts>
The order of the returned list of hosts isn’t guaranteed.
Table 6.228. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | List of discovered hosts | |
|
| In | Sets the maximum number of hosts to return. |
6.79.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.79.1.2. max
Sets the maximum number of hosts to return. If not specified all the hosts are returned.
6.80. ExternalHost
Table 6.229. Methods summary
| Name | Summary |
|---|---|
|
|
6.80.1. get GET
Table 6.230. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.80.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.81. ExternalHostGroup
This service manages a single host group information.
Host group is a term of host provider - the host group includes provision details that are applied to new discovered host. Information such as subnet, operating system, domain, etc.
Table 6.231. Methods summary
| Name | Summary |
|---|---|
|
| Get host group information. |
6.81.1. get GET
Get host group information.
For example, to get the details of hostgroup 234 of provider 123, send a request like this:
GET /ovirt-engine/api/externalhostproviders/123/hostgroups/234
It will return a response like this:
<external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234"> <name>rhel7</name> <architecture_name>x86_64</architecture_name> <domain_name>s.com</domain_name> <operating_system_name>RedHat 7.3</operating_system_name> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_host_group>
Table 6.232. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | Host group information. |
6.81.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.82. ExternalHostGroups
This service manages hostgroups.
Table 6.233. Methods summary
| Name | Summary |
|---|---|
|
| Get host groups list from external host provider. |
6.82.1. list GET
Get host groups list from external host provider.
Host group is a term of host providers - the host group includes provision details. This API returns all possible hostgroups exposed by the external provider.
For example, to get the details of all host groups of provider 123, send a request like this:
GET /ovirt-engine/api/externalhostproviders/123/hostgroups
The response will be like this:
<external_host_groups>
<external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234">
<name>rhel7</name>
<architecture_name>x86_64</architecture_name>
<domain_name>example.com</domain_name>
<operating_system_name>RedHat 7.3</operating_system_name>
<subnet_name>sat0</subnet_name>
<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_host_group>
...
</external_host_groups>The order of the returned list of host groups isn’t guaranteed.
Table 6.234. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | List of all hostgroups available for external host provider | |
|
| In | Sets the maximum number of groups to return. |
6.82.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.82.1.2. max
Sets the maximum number of groups to return. If not specified all the groups are returned.
6.83. ExternalHostProvider
Represents an external host provider, such as Foreman or Satellite.
See https://www.theforeman.org/ for more details on Foreman. See https://access.redhat.com/products/red-hat-satellite for more details on Red Hat Satellite.
Table 6.235. Methods summary
| Name | Summary |
|---|---|
|
| Get external host provider information Host provider, Foreman or Satellite, can be set as an external provider in ovirt. |
|
| Import the SSL certificates of the external host provider. |
|
| |
|
| In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. |
|
| Update the specified external host provider in the system. |
6.83.1. get GET
Get external host provider information
Host provider, Foreman or Satellite, can be set as an external provider in ovirt. To see details about specific host providers attached to ovirt use this API.
For example, to get the details of host provider 123, send a request like this:
GET /ovirt-engine/api/externalhostproviders/123
The response will be like this:
<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"> <name>mysatellite</name> <requires_authentication>true</requires_authentication> <url>https://mysatellite.example.com</url> <username>admin</username> </external_host_provider>
Table 6.236. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out |
6.83.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.83.2. importcertificates POST
Import the SSL certificates of the external host provider.
Table 6.237. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In |
6.83.3. remove DELETE
Table 6.238. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the remove should be performed asynchronously. |
6.83.4. testconnectivity POST
In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.
POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Table 6.239. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the test should be performed asynchronously. |
6.83.5. update PUT
Update the specified external host provider in the system.
Table 6.240. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates if the update should be performed asynchronously. | |
|
| In/Out |
6.84. ExternalHostProviders
Table 6.241. Methods summary
| Name | Summary |
|---|---|
|
| Add a new external host provider to the system. |
|
| Returns the list of external host providers. |
6.84.1. add POST
Add a new external host provider to the system.
Table 6.242. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In/Out |
6.84.2. list GET
Returns the list of external host providers.
The order of the returned list of host providers isn’t guaranteed.
Table 6.243. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| In | Sets the maximum number of providers to return. | |
|
| Out | ||
|
| In | A query string used to restrict the returned external host providers. |
6.84.2.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.84.2.2. max
Sets the maximum number of providers to return. If not specified all the providers are returned.
6.85. ExternalHosts
Table 6.244. Methods summary
| Name | Summary |
|---|---|
|
| Return the list of external hosts. |
6.85.1. list GET
Return the list of external hosts.
The order of the returned list of hosts isn’t guaranteed.
Table 6.245. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| In | Indicates which inner links should be followed. | |
|
| Out | ||
|
| In | Sets the maximum number of hosts to return. |
6.85.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.85.1.2. max
Sets the maximum number of hosts to return. If not specified all the hosts are returned.
6.86. ExternalNetworkProviderConfiguration
Describes how an external network provider is provisioned by the system on the host.
Table 6.246. Methods summary
| Name | Summary |
|---|---|
|
| Returns the information about an external network provider on the host. |
6.86.1. get GET
Returns the information about an external network provider on the host.
Table 6.247. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | ||
|
| In | Indicates which inner links should be followed. |
6.86.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.87. ExternalNetworkProviderConfigurations
A service to list all external network providers provisioned by the system on the host.
Table 6.248. Methods summary
| Name | Summary |
|---|---|
|
| Returns the list of all external network providers on the host. |
6.87.1. list GET
Returns the list of all external network providers on the host.
The order of the returned list of networks is not guaranteed.
Table 6.249. Parameters summary
| Name | Type | Direction | Summary |
|---|---|---|---|
|
| Out | ||
|
| In | Indicates which inner links should be followed. |
6.87.1.1. follow
Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.
6.88. ExternalProvider
Provides capability to manage external providers.
Table 6.250. Methods summary
| Name | Summary |
|---|---|
|
| Import the SSL certificates of the external host provider. |
|
| In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. |
6.88.1. importcertificates POST
Import the SSL certificates of the external host provider.
Table 6.251. Parameters summary
| Name | Type | Direction |
|---|