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

NameSummary

get

Retrieve the affinity group details.

remove

Remove the affinity group.

update

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

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

group

AffinityGroup

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

NameTypeDirectionSummary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.1.3. update PUT

Update the affinity group.

Table 6.4. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

group

AffinityGroup

In/Out

The affinity group.

6.2. AffinityGroupVm

This service manages a single virtual machine to affinity group assignment.

Table 6.5. Methods summary

NameSummary

remove

Remove this virtual machine from the affinity group.

6.2.1. remove DELETE

Remove this virtual machine from the affinity group.

Table 6.6. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.3. AffinityGroupVms

This service manages a collection of all the virtual machines assigned to an affinity group.

Table 6.7. Methods summary

NameSummary

add

Adds a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

6.3.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.8. Parameters summary

NameTypeDirectionSummary

vm

Vm

In/Out

 

6.3.2. list GET

List all virtual machines assigned to this affinity group.

The order of the returned virtual machines isn’t guaranteed.

Table 6.9. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out

 

6.3.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.3.2.2. max

Sets the maximum number of virtual machines to return. If not specified, all the virtual machines are returned.

6.4. AffinityGroups

The affinity groups service manages virtual machine relationships and dependencies.

Table 6.10. Methods summary

NameSummary

add

Create a new affinity group.

list

List existing affinity groups.

6.4.1. add POST

Create a new affinity group.

Post a request like in the example below to create a new affinity group:

POST /ovirt-engine/api/clusters/000-000/affinitygroups

And use the following example in its body:

<affinity_group>
  <name>AF_GROUP_001</name>
  <hosts_rule>
    <enforcing>true</enforcing>
    <positive>true</positive>
  </hosts_rule>
  <vms_rule>
    <enabled>false</enabled>
  </vms_rule>
</affinity_group>

Table 6.11. Parameters summary

NameTypeDirectionSummary

group

AffinityGroup

In/Out

The affinity group object to create.

6.4.2. list GET

List existing affinity groups.

The order of the affinity groups results isn’t guaranteed.

Table 6.12. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

groups

AffinityGroup[]

Out

The list of existing affinity groups.

max

Integer

In

Sets the maximum number of affinity groups 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 affinity groups to return. If not specified all the affinity groups are returned.

6.5. AffinityLabel

The details of a single affinity label.

Table 6.13. Methods summary

NameSummary

get

Retrieves the details of a label.

remove

Removes a label from the system and clears all assignments of the removed label.

update

Updates a label.

6.5.1. get GET

Retrieves the details of a label.

Table 6.14. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

label

AffinityLabel

Out

 

6.5.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.5.2. remove DELETE

Removes a label from the system and clears all assignments of the removed label.

6.5.3. update PUT

Updates a label. This call will update all metadata, such as the name or description.

Table 6.15. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.6. AffinityLabelHost

This service represents a host that has a specific label when accessed through the affinitylabels/hosts subcollection.

Table 6.16. Methods summary

NameSummary

get

Retrieves details about a host that has this label assigned.

remove

Remove a label from a host.

6.6.1. get GET

Retrieves details about a host that has this label assigned.

Table 6.17. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

host

Host

Out

 

6.6.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.6.2. remove DELETE

Remove a label from a host.

6.7. AffinityLabelHosts

This service represents list of hosts that have a specific label when accessed through the affinitylabels/hosts subcollection.

Table 6.18. Methods summary

NameSummary

add

Add a label to a host.

list

List all hosts with the label.

6.7.1. add POST

Add a label to a host.

Table 6.19. Parameters summary

NameTypeDirectionSummary

host

Host

In/Out

 

6.7.2. list GET

List all hosts with the label.

The order of the returned hosts isn’t guaranteed.

Table 6.20. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

hosts

Host[]

Out

 

6.7.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. AffinityLabelVm

This service represents a vm that has a specific label when accessed through the affinitylabels/vms subcollection.

Table 6.21. Methods summary

NameSummary

get

Retrieves details about a vm that has this label assigned.

remove

Remove a label from a vm.

6.8.1. get GET

Retrieves details about a vm that has this label assigned.

Table 6.22. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

vm

Vm

Out

 

6.8.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.8.2. remove DELETE

Remove a label from a vm.

6.9. AffinityLabelVms

This service represents list of vms that have a specific label when accessed through the affinitylabels/vms subcollection.

Table 6.23. Methods summary

NameSummary

add

Add a label to a vm.

list

List all virtual machines with the label.

6.9.1. add POST

Add a label to a vm.

Table 6.24. Parameters summary

NameTypeDirectionSummary

vm

Vm

In/Out

 

6.9.2. list GET

List all virtual machines with the label.

The order of the returned virtual machines isn’t guaranteed.

Table 6.25. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

vms

Vm[]

Out

 

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.10. AffinityLabels

Manages the affinity labels available in the system.

Table 6.26. Methods summary

NameSummary

add

Creates a new label.

list

Lists all labels present in the system.

6.10.1. add POST

Creates a new label. The label is automatically attached to all entities mentioned in the vms or hosts lists.

Table 6.27. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.10.2. list GET

Lists all labels present in the system.

The order of the returned labels isn’t guaranteed.

Table 6.28. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

labels

AffinityLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels 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 labels to return. If not specified all the labels are returned.

6.11. Area

This annotation is intended to specify what oVirt area is the annotated concept related to. Currently the following areas are in use, and they are closely related to the oVirt teams, but not necessarily the same:

  • Infrastructure
  • Network
  • SLA
  • Storage
  • Virtualization

A concept may be associated to more than one area, or to no area.

The value of this annotation is intended for reporting only, and it doesn’t affect at all the generated code or the validity of the model

6.12. AssignedAffinityLabel

This service represents one label to entity assignment when accessed using the entities/affinitylabels subcollection.

Table 6.29. Methods summary

NameSummary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

6.12.1. get GET

Retrieves details about the attached label.

Table 6.30. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

label

AffinityLabel

Out

 

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

Removes the label from an entity. Does not touch the label itself.

6.13. AssignedAffinityLabels

This service is used to list and manipulate affinity labels that are assigned to supported entities when accessed using entities/affinitylabels.

Table 6.31. Methods summary

NameSummary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

6.13.1. add POST

Attaches a label to an entity.

Table 6.32. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.13.2. list GET

Lists all labels that are attached to an entity.

The order of the returned entities isn’t guaranteed.

Table 6.33. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

label

AffinityLabel[]

Out

 

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. AssignedCpuProfile

Table 6.34. Methods summary

NameSummary

get

 

remove

 

6.14.1. get GET

Table 6.35. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

profile

CpuProfile

Out

 

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

Table 6.36. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.15. AssignedCpuProfiles

Table 6.37. Methods summary

NameSummary

add

Add a new cpu profile for the cluster.

list

List the CPU profiles assigned to the cluster.

6.15.1. add POST

Add a new cpu profile for the cluster.

Table 6.38. Parameters summary

NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.15.2. list GET

List the CPU profiles assigned to the cluster.

The order of the returned CPU profiles isn’t guaranteed.

Table 6.39. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out

 

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.15.2.2. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

6.16. AssignedDiskProfile

Table 6.40. Methods summary

NameSummary

get

 

remove

 

6.16.1. get GET

Table 6.41. Parameters summary

NameTypeDirectionSummary

disk_profile

DiskProfile

Out

 

follow

String

In

Indicates which inner links should be followed.

6.16.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.16.2. remove DELETE

Table 6.42. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.17. AssignedDiskProfiles

Table 6.43. Methods summary

NameSummary

add

Add a new disk profile for the storage domain.

list

Returns the list of disk profiles assigned to the storage domain.

6.17.1. add POST

Add a new disk profile for the storage domain.

Table 6.44. Parameters summary

NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.17.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.45. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out

 

6.17.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.17.2.2. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

6.18. AssignedPermissions

Represents a permission sub-collection, scoped by user, group or some entity type.

Table 6.46. Methods summary

NameSummary

add

Assign a new permission to a user or group for specific entity.

list

List all the permissions of the specific entity.

6.18.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.47. Parameters summary

NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

6.18.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.48. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

permissions

Permission[]

Out

The list of permissions.

6.18.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.19. AssignedRoles

Represents a roles sub-collection, for example scoped by user.

Table 6.49. Methods summary

NameSummary

list

Returns the roles assigned to the permission.

6.19.1. list GET

Returns the roles assigned to the permission.

The order of the returned roles isn’t guaranteed.

Table 6.50. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

 

6.19.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.19.1.2. max

Sets the maximum number of roles to return. If not specified all the roles are returned.

6.20. AssignedTag

A service to manage assignment of specific tag to specific entities in system.

Table 6.51. Methods summary

NameSummary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

6.20.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.52. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

tag

Tag

Out

The assigned tag.

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

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.53. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.21. AssignedTags

A service to manage collection of assignment of tags to specific entities in system.

Table 6.54. Methods summary

NameSummary

add

Assign tag to specific entity in the system.

list

List all tags assigned to the specific entity.

6.21.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.55. Parameters summary

NameTypeDirectionSummary

tag

Tag

In/Out

The assigned tag.

6.21.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.56. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.

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 tags to return. If not specified all the tags are returned.

6.22. AssignedVnicProfile

Table 6.57. Methods summary

NameSummary

get

 

remove

 

6.22.1. get GET

Table 6.58. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

profile

VnicProfile

Out

 

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.59. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.23. AssignedVnicProfiles

Table 6.60. Methods summary

NameSummary

add

Add a new virtual network interface card profile for the network.

list

Returns the list of VNIC profiles assifned to the network.

6.23.1. add POST

Add a new virtual network interface card profile for the network.

Table 6.61. Parameters summary

NameTypeDirectionSummary

profile

VnicProfile

In/Out

 

6.23.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.62. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

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. AttachedStorageDomain

Table 6.63. Methods summary

NameSummary

activate

This operation activates an attached storage domain.

deactivate

This operation deactivates an attached storage domain.

get

 

remove

 

6.24.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.64. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.24.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.65. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

force

Boolean

In

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.

6.24.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.24.3. get GET

Table 6.66. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

storage_domain

StorageDomain

Out

 

6.24.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.24.4. remove DELETE

Table 6.67. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.25. AttachedStorageDomainDisk

Manages a single disk available in a storage domain attached to a data center.

Important

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.68. Methods summary

NameSummary

copy

Copies a disk to the specified storage domain.

export

Exports a disk to an export storage domain.

get

Retrieves the description of the disk.

move

Moves a disk to another storage domain.

register

Registers an unregistered disk.

remove

Removes a disk.

sparsify

Sparsify the disk.

update

Updates the disk.

6.25.1. copy POST

Copies a disk to the specified storage domain.

Important

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.69. Parameters summary

NameTypeDirectionSummary

disk

Disk

In

Description of the resulting disk.

storage_domain

StorageDomain

In

The storage domain where the new disk will be created.

6.25.2. export POST

Exports a disk to an export storage domain.

Important

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.70. Parameters summary

NameTypeDirectionSummary

storage_domain

StorageDomain

In

The export storage domain where the disk should be exported to.

6.25.3. get GET

Retrieves the description of the disk.

Table 6.71. Parameters summary

NameTypeDirectionSummary

disk

Disk

Out

The description of the disk.

follow

String

In

Indicates which inner links should be followed.

6.25.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.25.4. move POST

Moves a disk to another storage domain.

Important

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.72. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the move should be performed asynchronously.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

storage_domain

StorageDomain

In

The storage domain where the disk will be moved to.

6.25.5. register POST

Registers an unregistered disk.

6.25.6. remove DELETE

Removes a disk.

Important

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.25.7. sparsify POST

Sparsify the disk.

Important

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.25.8. update PUT

Updates the disk.

Important

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.73. Parameters summary

NameTypeDirectionSummary

disk

Disk

In/Out

The update to apply to the disk.

6.26. AttachedStorageDomainDisks

Manages the collection of disks available inside an storage domain that is attached to a data center.

Table 6.74. Methods summary

NameSummary

add

Adds or registers a disk.

list

Retrieve the list of disks that are available in the storage domain.

6.26.1. add POST

Adds or registers a disk.

Important

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.75. Parameters summary

NameTypeDirectionSummary

disk

Disk

In/Out

The disk to add or register.

unregistered

Boolean

In

Indicates if a new disk should be added or if an existing unregistered disk should be registered.

6.26.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.26.2. list GET

Retrieve the list of disks that are available in the storage domain.

Table 6.76. Parameters summary

NameTypeDirectionSummary

disks

Disk[]

Out

List of retrieved disks.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of disks to return.

6.26.2.1. disks

List of retrieved disks.

The order of the returned disks isn’t guaranteed.

6.26.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.26.2.3. max

Sets the maximum number of disks to return. If not specified all the disks are returned.

6.27. AttachedStorageDomains

Manages the storage domains attached to a data center.

Table 6.77. Methods summary

NameSummary

add

Attaches an existing storage domain to the data center.

list

Returns the list of storage domains attached to the data center.

6.27.1. add POST

Attaches an existing storage domain to the data center.

Table 6.78. Parameters summary

NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

The storage domain to attach to the data center.

6.27.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.79. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out

A list of storage domains that are attached to the data center.

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 storage domains to return. If not specified all the storage domains are returned.

6.28. Balance

Table 6.80. Methods summary

NameSummary

get

 

remove

 

6.28.1. get GET

Table 6.81. Parameters summary

NameTypeDirectionSummary

balance

Balance

Out

 

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

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.82. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.29. Balances

Table 6.83. Methods summary

NameSummary

add

Add a balance module to a specified user defined scheduling policy.

list

Returns the list of balance modules used by the scheduling policy.

6.29.1. add POST

Add a balance module to a specified user defined scheduling policy.

Table 6.84. Parameters summary

NameTypeDirectionSummary

balance

Balance

In/Out

 

6.29.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.85. Parameters summary

NameTypeDirectionSummary

balances

Balance[]

Out

 

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of balances to return.

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 balances to return. If not specified all the balances are returned.

6.30. Bookmark

A service to manage a bookmark.

Table 6.86. Methods summary

NameSummary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

6.30.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.87. Parameters summary

NameTypeDirectionSummary

bookmark

Bookmark

Out

The requested bookmark.

follow

String

In

Indicates which inner links should be followed.

6.30.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.30.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123

Table 6.88. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.30.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>

Table 6.89. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

6.31. Bookmarks

A service to manage bookmarks.

Table 6.90. Methods summary

NameSummary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

6.31.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.91. Parameters summary

NameTypeDirectionSummary

bookmark

Bookmark

In/Out

The added bookmark.

6.31.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.92. Parameters summary

NameTypeDirectionSummary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of bookmarks to return.

6.31.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.31.2.2. max

Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned.

6.32. Cluster

A service to manage a specific cluster.

Table 6.93. Methods summary

NameSummary

get

Gets information about the cluster.

remove

Removes the cluster from the system.

resetemulatedmachine

 

syncallnetworks

Synchronizes all networks on the cluster.

update

Updates information about the cluster.

6.32.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 Penryn Family</type>
  </cpu>
  <error_handling>
    <on_error>migrate</on_error>
  </error_handling>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
  </fencing_policy>
  <gluster_service>false</gluster_service>
  <ha_reservation>false</ha_reservation>
  <ksm>
    <enabled>true</enabled>
    <merge_across_nodes>true</merge_across_nodes>
  </ksm>
  <maintenance_reason_required>false</maintenance_reason_required>
  <memory_policy>
    <over_commit>
      <percent>100</percent>
    </over_commit>
    <transparent_hugepages>
      <enabled>true</enabled>
    </transparent_hugepages>
  </memory_policy>
  <migration>
    <auto_converge>inherit</auto_converge>
    <bandwidth>
      <assignment_method>auto</assignment_method>
    </bandwidth>
    <compressed>inherit</compressed>
  </migration>
  <optional_reason>false</optional_reason>
  <required_rng_sources>
    <required_rng_source>random</required_rng_source>
  </required_rng_sources>
  <scheduling_policy href="/ovirt-engine/api/schedulingpolicies/456" id="456"/>
  <threads_as_cores>false</threads_as_cores>
  <trusted_service>false</trusted_service>
  <tunnel_migration>false</tunnel_migration>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <virt_service>true</virt_service>
  <data_center href="/ovirt-engine/api/datacenters/111" id="111"/>
</cluster>

Table 6.94. Parameters summary

NameTypeDirectionSummary

cluster

Cluster

Out

 

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

6.32.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.32.2. remove DELETE

Removes the cluster from the system.

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000

Table 6.95. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.32.3. resetemulatedmachine POST

Table 6.96. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.32.4. syncallnetworks POST

Synchronizes all networks on the cluster.

POST /ovirt-engine/api/clusters/123/syncallnetworks

With a request body like this:

<action/>

Table 6.97. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.32.5. 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>

Table 6.98. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

 

6.33. ClusterEnabledFeature

Represents a feature enabled for the cluster.

Table 6.99. Methods summary

NameSummary

get

Provides the information about the cluster feature enabled.

remove

Disables a cluster feature.

6.33.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.100. Parameters summary

NameTypeDirectionSummary

feature

ClusterFeature

Out

Retrieved cluster feature that’s enabled.

follow

String

In

Indicates which inner links should be followed.

6.33.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.33.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.34. 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.101. Methods summary

NameSummary

add

Enable an additional feature for a cluster.

list

Lists the additional features enabled for the cluster.

6.34.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.102. Parameters summary

NameTypeDirectionSummary

feature

ClusterFeature

In/Out

 

6.34.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.103. Parameters summary

NameTypeDirectionSummary

features

ClusterFeature[]

Out

Retrieved features.

follow

String

In

Indicates which inner links should be followed.

6.34.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. ClusterExternalProviders

This service lists external providers.

Table 6.104. Methods summary

NameSummary

list

Returns the list of external providers.

6.35.1. list GET

Returns the list of external providers.

The order of the returned list of providers is not guaranteed.

Table 6.105. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

providers

ExternalProvider[]

Out

 

6.35.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. ClusterFeature

Represents a feature enabled for the cluster level

Table 6.106. Methods summary

NameSummary

get

Provides the information about the a cluster feature supported by a cluster level.

6.36.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.107. Parameters summary

NameTypeDirectionSummary

feature

ClusterFeature

Out

Retrieved cluster feature.

follow

String

In

Indicates which inner links should be followed.

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.37. ClusterFeatures

Provides information about the cluster features that are supported by a cluster level.

Table 6.108. Methods summary

NameSummary

list

Lists the cluster features supported by the cluster level.

6.37.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.109. Parameters summary

NameTypeDirectionSummary

features

ClusterFeature[]

Out

Retrieved features.

follow

String

In

Indicates which inner links should be followed.

6.37.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. ClusterLevel

Provides information about a specific cluster level. See the ClusterLevels service for more information.

Table 6.110. Methods summary

NameSummary

get

Provides the information about the capabilities of the specific cluster level managed by this service.

6.38.1. get GET

Provides the information about the capabilities of the specific cluster level managed by this service.

For example, to find what CPU types are supported by level 3.6 you can send a request like this:

GET /ovirt-engine/api/clusterlevels/3.6

That will return a ClusterLevel object containing the supported CPU types, and other information which describes the cluster level:

<cluster_level id="3.6">
  <cpu_types>
    <cpu_type>
      <name>Intel Conroe Family</name>
      <level>3</level>
      <architecture>x86_64</architecture>
    </cpu_type>
    ...
  </cpu_types>
  <permits>
    <permit id="1">
      <name>create_vm</name>
      <administrative>false</administrative>
    </permit>
    ...
  </permits>
</cluster_level>

Table 6.111. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

level

ClusterLevel

Out

Retreived cluster level.

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.39. 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.112. Methods summary

NameSummary

list

Lists the cluster levels supported by the system.

6.39.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.113. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

levels

ClusterLevel[]

Out

Retrieved cluster levels.

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.40. ClusterNetwork

A service to manage a specific cluster network.

Table 6.114. Methods summary

NameSummary

get

Retrieves the cluster network details.

remove

Unassigns the network from a cluster.

update

Updates the network in the cluster.

6.40.1. get GET

Retrieves the cluster network details.

Table 6.115. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

network

Network

Out

The cluster network.

6.40.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.40.2. remove DELETE

Unassigns the network from a cluster.

6.40.3. update PUT

Updates the network in the cluster.

Table 6.116. Parameters summary

NameTypeDirectionSummary

network

Network

In/Out

The cluster network.

6.41. ClusterNetworks

A service to manage cluster networks.

Table 6.117. Methods summary

NameSummary

add

Assigns the network to a cluster.

list

Lists the networks that are assigned to the cluster.

6.41.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.118. Parameters summary

NameTypeDirectionSummary

network

Network

In/Out

The network object to be assigned to the cluster.

6.41.2. list GET

Lists the networks that are assigned to the cluster.

The order of the returned clusters isn’t guaranteed.

Table 6.119. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks that are assigned to the cluster.

6.41.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.2.2. max

Sets the maximum number of networks to return. If not specified, all the networks are returned.

6.42. Clusters

A service to manage clusters.

Table 6.120. Methods summary

NameSummary

add

Creates a new cluster.

list

Returns the list of clusters of the system.

6.42.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 Penryn 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 Penryn Family</type>
  </cpu>
  <data_center id="123"/>
  <external_network_providers>
    <external_provider name="ovirt-provider-ovn"/>
  </external_network_providers>
</cluster>

Table 6.121. Parameters summary

NameTypeDirectionSummary

cluster

Cluster

In/Out

 

6.42.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.122. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search should be performed taking case into account.

clusters

Cluster[]

Out

 

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of clusters to return.

search

String

In

A query string used to restrict the returned clusters.

6.42.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.42.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.42.2.3. max

Sets the maximum number of clusters to return. If not specified, all the clusters are returned.

6.43. Copyable

Table 6.123. Methods summary

NameSummary

copy

 

6.43.1. copy POST

Table 6.124. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

6.44. CpuProfile

Table 6.125. Methods summary

NameSummary

get

 

remove

 

update

Update the specified cpu profile in the system.

6.44.1. get GET

Table 6.126. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

profile

CpuProfile

Out

 

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.44.2. remove DELETE

Table 6.127. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.44.3. update PUT

Update the specified cpu profile in the system.

Table 6.128. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

 

6.45. CpuProfiles

Table 6.129. Methods summary

NameSummary

add

Add a new cpu profile to the system.

list

Returns the list of CPU profiles of the system.

6.45.1. add POST

Add a new cpu profile to the system.

Table 6.130. Parameters summary

NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.45.2. list GET

Returns the list of CPU profiles of the system.

The order of the returned list of CPU profiles isn’t guranteed.

Table 6.131. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out

 

6.45.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.45.2.2. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

6.46. DataCenter

A service to manage a data center.

Table 6.132. Methods summary

NameSummary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

6.46.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.133. Parameters summary

NameTypeDirectionSummary

data_center

DataCenter

Out

 

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

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

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.134. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

force

Boolean

In

Indicates if the operation should succeed, and the storage domain removed from the database, even if something fails during the operation.

6.46.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.46.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.135. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

data_center

DataCenter

In/Out

The data center that is being updated.

6.47. DataCenterNetwork

A service to manage a specific data center network.

Table 6.136. Methods summary

NameSummary

get

Retrieves the data center network details.

remove

Removes the network.

update

Updates the network in the data center.

6.47.1. get GET

Retrieves the data center network details.

Table 6.137. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

network

Network

Out

The data center network.

6.47.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.47.2. remove DELETE

Removes the network.

6.47.3. update PUT

Updates the network in the data center.

Table 6.138. Parameters summary

NameTypeDirectionSummary

network

Network

In/Out

The data center network.

6.48. DataCenterNetworks

A service to manage data center networks.

Table 6.139. Methods summary

NameSummary

add

Create a new network in a data center.

list

Lists networks in the data center.

6.48.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.140. Parameters summary

NameTypeDirectionSummary

network

Network

In/Out

The network object to be created in the data center.

6.48.2. list GET

Lists networks in the data center.

The order of the returned list of networks isn’t guaranteed.

Table 6.141. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks which are in the data center.

6.48.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.48.2.2. max

Sets the maximum number of networks to return. If not specified, all the networks are returned.

6.49. DataCenters

A service to manage data centers.

Table 6.142. Methods summary

NameSummary

add

Creates a new data center.

list

Lists the data centers.

6.49.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.143. Parameters summary

NameTypeDirectionSummary

data_center

DataCenter

In/Out

The data center that is being added.

6.49.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.144. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

data_centers

DataCenter[]

Out

 

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of data centers to return.

search

String

In

A query string used to restrict the returned data centers.

6.49.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.49.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.49.2.3. max

Sets the maximum number of data centers to return. If not specified all the data centers are returned.

6.50. Disk

Manages a single disk.

Table 6.145. Methods summary

NameSummary

copy

This operation copies a disk to the specified storage domain.

export

Exports a disk to an export storage domain.

get

Retrieves the description of the disk.

move

Moves a disk to another storage domain.

reduce

Reduces the size of the disk image.

refreshlun

Refreshes a direct LUN disk with up-to-date information from the storage.

remove

Removes a disk.

sparsify

Sparsify the disk.

update

This operation updates the disk with the appropriate parameters.

6.50.1. copy POST

This operation copies a disk to the specified storage domain.

For example, copy of a disk can be facilitated using the following request:

POST /ovirt-engine/api/disks/123/copy

With a request body like this:

<action>
  <storage_domain id="456"/>
  <disk>
    <name>mydisk</name>
  </disk>
</action>

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.146. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

disk

Disk

In

 

disk_profile

DiskProfile

In

Disk profile for the disk in the new storage domain.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

quota

Quota

In

Quota for the disk in the new storage domain.

storage_domain

StorageDomain

In

The storage domain where the new disk will be created.

6.50.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.50.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.50.1.3. storage_domain

The storage domain where the new disk will be created. Can be specified using the id or name attributes. For example, to copy a disk to the storage domain named mydata send a request like this:

POST /ovirt-engine/api/storagedomains/123/disks/789

With a request body like this:

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
</action>

6.50.2. export POST

Exports a disk to an export storage domain.

Table 6.147. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the export should be performed asynchronously.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

storage_domain

StorageDomain

In

 

6.50.3. get GET

Retrieves the description of the disk.

Table 6.148. Parameters summary

NameTypeDirectionSummary

all_content

Boolean

In

Indicates if all of the attributes of the disk should be included in the response.

disk

Disk

Out

The description of the disk.

follow

String

In

Indicates which inner links should be followed.

6.50.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.50.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.50.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.149. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the move should be performed asynchronously.

disk_profile

DiskProfile

In

Disk profile for the disk in the new storage domain.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

quota

Quota

In

Quota for the disk in the new storage domain.

storage_domain

StorageDomain

In

 

6.50.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.50.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.50.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.150. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.50.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.151. Parameters summary

NameTypeDirectionSummary

host

Host

In

The host that will be used to refresh the direct LUN disk.

6.50.7. remove DELETE

Removes a disk.

Table 6.152. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.50.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.50.9. update PUT

This operation updates the disk with the appropriate parameters. The only field that can be updated is qcow_version.

For example, update disk can be facilitated using the following request:

PUT /ovirt-engine/api/disks/123

With a request body like this:

<disk>
  <qcow_version>qcow2_v3</qcow_version>
</disk>

Since the backend operation is asynchronous the disk element which will be returned to the user might not be synced with the changed properties.

Table 6.153. Parameters summary

NameTypeDirectionSummary

disk

Disk

In/Out

The update to apply to the disk.

6.51. DiskAttachment

This service manages the attachment of a disk to a virtual machine.

Table 6.154. Methods summary

NameSummary

get

Returns the details of the attachment, including the bootable flag and link to the disk.

remove

Removes the disk attachment.

update

Update the disk attachment and the disk properties within it.

6.51.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.155. Parameters summary

NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

follow

String

In

Indicates which inner links should be followed.

6.51.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.51.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.156. Parameters summary

NameTypeDirectionSummary

detach_only

Boolean

In

Indicates if the disk should only be detached from the virtual machine, but not removed from the system.

6.51.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.51.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.157. Parameters summary

NameTypeDirectionSummary

disk_attachment

DiskAttachment

In/Out

 

6.52. 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.158. Methods summary

NameSummary

add

Adds a new disk attachment to the virtual machine.

list

List the disk that are attached to the virtual machine.

6.52.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
Important

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.159. Parameters summary

NameTypeDirectionSummary

attachment

DiskAttachment

In/Out

The disk attachment to add to the virtual machine.

6.52.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.160. Parameters summary

NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

A list of disk attachments that are attached to the virtual machine.

follow

String

In

Indicates which inner links should be followed.

6.52.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.53. DiskProfile

Table 6.161. Methods summary

NameSummary

get

 

remove

 

update

Update the specified disk profile in the system.

6.53.1. get GET

Table 6.162. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

profile

DiskProfile

Out

 

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

Table 6.163. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.53.3. update PUT

Update the specified disk profile in the system.

Table 6.164. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

 

6.54. DiskProfiles

Table 6.165. Methods summary

NameSummary

add

Add a new disk profile to the system.

list

Returns the list of disk profiles of the system.

6.54.1. add POST

Add a new disk profile to the system.

Table 6.166. Parameters summary

NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.54.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.167. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profile

DiskProfile[]

Out

 

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 profiles to return. If not specified all the profiles are returned.

6.55. DiskSnapshot

Table 6.168. Methods summary

NameSummary

get

 

remove

 

6.55.1. get GET

Table 6.169. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

snapshot

DiskSnapshot

Out

 

6.55.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.55.2. remove DELETE

Table 6.170. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.56. DiskSnapshots

Manages the collection of disk snapshots available in an storage domain.

Table 6.171. Methods summary

NameSummary

list

Returns the list of disk snapshots of the storage domain.

6.56.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.172. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

DiskSnapshot[]

Out

 

6.56.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.56.1.2. max

Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.

6.57. Disks

Manages the collection of disks available in the system.

Table 6.173. Methods summary

NameSummary

add

Adds a new floating disk.

list

Get list of disks.

6.57.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:

  1. With a host element - in this case, the host is used for sanity checks (e.g., that the LUN is visible) and to retrieve basic information about the LUN (e.g., size and serial).
  2. Without a host element - in this case, the operation is a database-only operation, and the storage is never accessed.

To create a new floating direct LUN disk with a host element with an id 123, specified alias, type and logical_unit with an id 456 (that has the attributes address, port and target), send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <alias>mylun</alias>
  <lun_storage>
    <host id="123"/>
    <type>iscsi</type>
    <logical_units>
      <logical_unit id="456">
        <address>10.35.10.20</address>
        <port>3260</port>
        <target>iqn.2017-01.com.myhost:444</target>
      </logical_unit>
    </logical_units>
  </lun_storage>
</disk>

To create a new floating direct LUN disk without using a host, remove the host element.

Adding a new Cinder disk:

To create a new floating Cinder disk, send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <openstack_volume_type>
    <name>myceph</name>
  </openstack_volume_type>
  <storage_domains>
    <storage_domain>
      <name>cinderDomain</name>
    </storage_domain>
  </storage_domains>
  <provisioned_size>1073741824</provisioned_size>
  <interface>virtio</interface>
  <format>raw</format>
</disk>

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.174. Parameters summary

NameTypeDirectionSummary

disk

Disk

In/Out

The disk.

6.57.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.175. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

disks

Disk[]

Out

List of retrieved disks.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of disks to return.

search

String

In

A query string used to restrict the returned disks.

6.57.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.57.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.57.2.3. max

Sets the maximum number of disks to return. If not specified all the disks are returned.

6.58. Domain

A service to view details of an authentication domain in the system.

Table 6.176. Methods summary

NameSummary

get

Gets the authentication domain information.

6.58.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.177. Parameters summary

NameTypeDirectionSummary

domain

Domain

Out

The authentication domain.

follow

String

In

Indicates which inner links should be followed.

6.58.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. DomainGroup

Table 6.178. Methods summary

NameSummary

get

 

6.59.1. get GET

Table 6.179. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

get

Group

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.60. DomainGroups

Table 6.180. Methods summary

NameSummary

list

Returns the list of groups.

6.60.1. list GET

Returns the list of groups.

The order of the returned list of groups isn’t guaranteed.

Table 6.181. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

follow

String

In

Indicates which inner links should be followed.

groups

Group[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.

6.60.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.60.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.60.1.3. max

Sets the maximum number of groups to return. If not specified all the groups are returned.

6.61. DomainUser

A service to view a domain user in the system.

Table 6.182. Methods summary

NameSummary

get

Gets the domain user information.

6.61.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.183. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

user

User

Out

The domain user.

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.62. DomainUserGroups

A service that shows a user’s group membership in the AAA extension.

Table 6.184. Methods summary

NameSummary

list

Returns the list of groups that the user is a member of.

6.62.1. list GET

Returns the list of groups that the user is a member of.

Table 6.185. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

groups

Group[]

Out

The list of groups that the user is a member of.

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.63. DomainUsers

A service to list all domain users in the system.

Table 6.186. Methods summary

NameSummary

list

List all the users in the domain.

6.63.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.187. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of users to return.

search

String

In

A query string used to restrict the returned users.

users

User[]

Out

The list of users in the domain.

6.63.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.63.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.63.1.3. max

Sets the maximum number of users to return. If not specified all the users are returned.

6.64. Domains

A service to list all authentication domains in the system.

Table 6.188. Methods summary

NameSummary

list

List all the authentication domains in the system.

6.64.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.189. Parameters summary

NameTypeDirectionSummary

domains

Domain[]

Out

The list of domains.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of domains to return.

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.64.1.2. max

Sets the maximum number of domains to return. If not specified all the domains are returned.

6.65. EngineKatelloErrata

A service to manage Katello errata assigned to the engine. The information is retrieved from Katello.

Table 6.190. Methods summary

NameSummary

list

Retrieves the representation of the Katello errata.

6.65.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.191. Parameters summary

NameTypeDirectionSummary

errata

KatelloErratum[]

Out

A representation of Katello errata.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of errata to return.

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.65.1.2. max

Sets the maximum number of errata to return. If not specified all the errata are returned.

6.66. Event

A service to manage an event in the system.

Table 6.192. Methods summary

NameSummary

get

Get an event.

remove

Removes an event from internal audit log.

6.66.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.193. Parameters summary

NameTypeDirectionSummary

event

Event

Out

 

follow

String

In

Indicates which inner links should be followed.

6.66.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.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.194. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.67. Events

A service to manage events in the system.

Table 6.195. Methods summary

NameSummary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

 

6.67.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>
Note

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.196. Parameters summary

NameTypeDirectionSummary

event

Event

In/Out

 

6.67.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.197. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

events

Event[]

Out

 

follow

String

In

Indicates which inner links should be followed.

from

Integer

In

Indicates the event index after which events should be returned.

max

Integer

In

Sets the maximum number of events to return.

search

String

In

The events service provides search queries similar to other resource services.

6.67.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.67.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.67.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.67.2.4. max

Sets the maximum number of events to return. If not specified all the events are returned.

6.67.3. undelete POST

Table 6.198. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

6.68. 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.199. Methods summary

NameSummary

get

Retrieves external compute resource details.

6.68.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.200. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

resource

ExternalComputeResource

Out

External compute resource information

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. 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.201. Methods summary

NameSummary

list

Retrieves a list of external compute resources.

6.69.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.202. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of resources to return.

resources

ExternalComputeResource[]

Out

List of external computer resources.

6.69.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.1.2. max

Sets the maximum number of resources to return. If not specified all the resources are returned.

6.70. ExternalDiscoveredHost

This service manages a single discovered host.

Table 6.203. Methods summary

NameSummary

get

Get discovered host info.

6.70.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.204. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

host

ExternalDiscoveredHost

Out

Host’s hardware and config information.

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.71. ExternalDiscoveredHosts

This service manages external discovered hosts.

Table 6.205. Methods summary

NameSummary

list

Get list of discovered hosts' information.

6.71.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.206. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

hosts

ExternalDiscoveredHost[]

Out

List of discovered hosts

max

Integer

In

Sets the maximum number of hosts 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 hosts to return. If not specified all the hosts are returned.

6.72. ExternalHost

Table 6.207. Methods summary

NameSummary

get

 

6.72.1. get GET

Table 6.208. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

host

ExternalHost

Out

 

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.73. 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.209. Methods summary

NameSummary

get

Get host group information.

6.73.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.210. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

group

ExternalHostGroup

Out

Host group information.

6.73.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.74. ExternalHostGroups

This service manages hostgroups.

Table 6.211. Methods summary

NameSummary

list

Get host groups list from external host provider.

6.74.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.212. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

groups

ExternalHostGroup[]

Out

List of all hostgroups available for external host provider

max

Integer

In

Sets the maximum number of groups to return.

6.74.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.74.1.2. max

Sets the maximum number of groups to return. If not specified all the groups are returned.

6.75. 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.213. Methods summary

NameSummary

get

Get external host provider information

Host provider, Foreman or Satellite, can be set as an external provider in ovirt.

importcertificates

Import the SSL certificates of the external host provider.

remove

 

testconnectivity

In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.

update

Update the specified external host provider in the system.

6.75.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.214. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

provider

ExternalHostProvider

Out

 

6.75.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.75.2. importcertificates POST

Import the SSL certificates of the external host provider.

Table 6.215. Parameters summary

NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.75.3. remove DELETE

Table 6.216. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.75.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.217. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.75.5. update PUT

Update the specified external host provider in the system.

Table 6.218. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

 

6.76. ExternalHostProviders

Table 6.219. Methods summary

NameSummary

add

Adds a new external host provider to the system.

list

Returns the list of external host providers.

6.76.1. add POST

Adds a new external host provider to the system.

Table 6.220. Parameters summary

NameTypeDirectionSummary

provider

ExternalHostProvider

In/Out

 

6.76.2. list GET

Returns the list of external host providers.

The order of the returned list of host providers is not guaranteed.

Table 6.221. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of providers to return.

providers

ExternalHostProvider[]

Out

 

search

String

In

A query string used to restrict the returned external host providers.

6.76.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.76.2.2. max

Sets the maximum number of providers to return. If not specified, all the providers are returned.

6.77. ExternalHosts

Table 6.222. Methods summary

NameSummary

list

Return the list of external hosts.

6.77.1. list GET

Return the list of external hosts.

The order of the returned list of hosts isn’t guaranteed.

Table 6.223. Parameters summary

NameTypeDirectionSummary

follow

String

In

Indicates which inner links should be followed.

hosts

ExternalHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

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 hosts to return. If not specified all the hosts are returned.

6.78. ExternalNetworkProviderConfiguration

Describes how an external network provider is provisioned by the system on the host.

Table 6.224. Methods summary

NameSummary

get

Returns the information about an external network provider on the host.

6.78.1. get GET

Returns the information about an external network provider on the host.

Table 6.225. Parameters summary

NameTypeDirectionSummary

configuration

ExternalNetworkProviderConfiguration

Out

 

follow

String

In

Indicates which inner links should be followed.

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. ExternalNetworkProviderConfigurations

A service to list all external network providers provisioned by the system on the host.

Table 6.226. Methods summary

NameSummary

list

Returns the list of all external network providers on the host.

6.79.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.227. Parameters summary

NameTypeDirectionSummary

configurations

ExternalNetworkProviderConfiguration[]

Out

 

follow

String

In

Indicates which inner links should be followed.

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.80. ExternalProvider

Provides capability to manage external providers.

Table 6.228. Methods summary

NameSummary

importcertificates

Import the SSL certificates of the external host provider.

testconnectivity

In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.

6.80.1. importcertificates POST

Import the SSL certificates of the external host provider.

Table 6.229. Parameters summary

NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.80.2. 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.230. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.81. ExternalProviderCertificate

A service to view specific certificate for external provider.

Table 6.231. Methods summary

NameSummary

get

Get specific certificate.

6.81.1. get GET

Get specific certificate.

GET /ovirt-engine/api/externalhostproviders/123/certificate/0

And here is sample response:

<certificate id="0">
  <organization>provider.example.com</organization>
  <subject>CN=provider.example.com</subject>
  <content>...</content>
</certificate>

Table 6.232. Parameters summary

NameTypeDirectionSummary

certificate

Certificate

Out

The details of the certificate.

follow

String

In

Indicates which inner links should be followed.

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. ExternalProviderCertificates

A service to view certificates for external provider.

Table 6.233. Methods summary

NameSummary

list

Returns the chain of certificates presented by the external provider.

6.82.1. list GET

Returns the chain of certificates presented by the external provider.

GET /ovirt-engine/api/externalhostproviders/123/certificates

And here is sample response:

<certificates>
  <certificate id="789">...</certificate>
  ...
</certificates>

The order of the returned certificates is always guaranteed to be the sign order: the first is the certificate of the server itself, the second the certificate of the CA that signs the first, so on.

Table 6.234. Parameters summary

NameTypeDirectionSummary

certificates

Certificate[]

Out

List containing certificate details.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of certificates 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 certificates to return. If not specified all the certificates are returned.

6.83. ExternalVmImports

Provides capability to import external virtual machines.

Table 6.235. Methods summary

NameSummary

add

This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware.

6.83.1. add POST

This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware.

For example import of a virtual machine from VMware can be facilitated using the following request:

POST /externalvmimports

With request body of type ExternalVmImport, for example:

<external_vm_import>
  <vm>
    <name>my_vm</name>
  </vm>
  <cluster id="360014051136c20574f743bdbd28177fd" />
  <storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
  <name>vm_name_as_is_in_vmware</name>
  <sparse>true</sparse>
  <username>vmware_user</username>
  <password>123456</password>
  <provider>VMWARE</provider>
  <url>vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1</url>
  <drivers_iso id="virtio-win-1.6.7.iso" />
</external_vm_import>

Table 6.236. Parameters summary

NameTypeDirectionSummary

import

ExternalVmImport

In/Out

 

6.84. FenceAgent

A service to manage fence agent for a specific host.

Table 6.237. Methods summary

NameSummary

get

Gets details of this fence agent.

remove

Removes a fence agent for a specific host.

update

Update a fencing-agent.

6.84.1. get GET

Gets details of this fence agent.

GET /ovirt-engine/api/hosts/123/fenceagents/0

And here is sample response:

<agent id="0">
  <type>apc</type>
  <order>1</order>
  <ip>192.168.1.101</ip>
  <user>user</user>
  <password>xxx</password>
  <port>9</port>
  <options>name1=value1, name2=value2</options>
</agent>

Table 6.238. Parameters summary

NameTypeDirectionSummary

agent

Agent

Out

Fence agent details.

follow

String

In

Indicates which inner links should be followed.

6.84.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.84.2. remove DELETE

Removes a fence agent for a specific host.

DELETE /ovirt-engine/api/hosts/123/fenceagents/0

Table 6.239. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.84.3. update PUT

Update a fencing-agent.

Table 6.240. Parameters summary

NameTypeDirectionSummary

agent

Agent

In/Out

Fence agent details.

async

Boolean

In

Indicates if the update should be performed asynchronously.

6.85. FenceAgents

A service to manage fence agents for a specific host.

Table 6.241. Methods summary

NameSummary

add

Add a new fencing-agent to the host.

list

Returns the list of fencing agents configured for the host.

6.85.1. add POST

Add a new fencing-agent to the host.

Table 6.242. Parameters summary

NameTypeDirectionSummary

agent

Agent

In/Out

 

6.85.2. list GET

Returns the list of fencing agents configured for the host.

GET /ovirt-engine/api/hosts/123/fenceagents

And here is sample response:

<agents>
  <agent id="0">
    <type>apc</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>name1=value1, name2=value2</options>
  </agent>
</agents>

The order of the returned list of fencing agents isn’t guaranteed.

Table 6.243. Parameters summary

NameTypeDirectionSummary

agents

Agent[]

Out

List of fence agent details.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of agents to return.

6.85.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.85.2.2. max

Sets the maximum number of agents to return. If not specified all the agents are returned.

6.86. File

Table 6.244. Methods summary

NameSummary

get

 

6.86.1. get GET

Table 6.245. Parameters summary

NameTypeDirectionSummary

file

File

Out

 

follow

String

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. Files

Provides a way for clients to list available files.

This service is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads.

The addition of a CD-ROM device to a virtual machine requires an ISO image from the files of an ISO storage domain.

Table 6.246. Methods summary

NameSummary

list

Returns the list of ISO images and virtual floppy disks available in the storage domain.

6.87.1. list GET

Returns the list of ISO images and virtual floppy disks available in the storage domain. The order of the returned list is not guaranteed.

If the refresh parameter is false, the returned list may not reflect recent changes to the storage domain; for example, it may not contain a new ISO file that was recently added. This is because the server caches the list of files to improve performance. To get the very latest results, set the refresh parameter to true.

The default value of the refresh parameter is true, but it can be changed using the configuration value ForceRefreshDomainFilesByDefault:

# engine-config -s ForceRefreshDomainFilesByDefault=false
Important

Setting the value of the refresh parameter to true has an impact on the performance of the server. Use it only if necessary.

Table 6.247. Parameters summary

NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should take case into account.

file

File[]

Out

 

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of files to return.

refresh

Boolean

In

Indicates whether the list of files should be refreshed from the storage domain, rather than showing cached results that are updated at certain intervals.

search

String

In

A query string used to restrict the returned files.

6.87.1.1. case_sensitive

Indicates if the search performed using the search parameter should take case into account. The default value is true.

6.87.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.87.1.3. max

Sets the maximum number of files to return. If not specified, all the files are returned.

6.88. Filter

Table 6.248. Methods summary

NameSummary

get

 

remove

 

6.88.1. get GET

Table 6.249. Parameters summary

NameTypeDirectionSummary

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

follow

String

In

Indicates which inner links should be followed.

result

Filter

Out

 

6.88.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.2. remove DELETE

Table 6.250. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.89. Filters

Manages the filters used by an scheduling policy.

Table 6.251. Methods summary

NameSummary

add

Add a filter to a specified user defined scheduling policy.

list

Returns the list of filters used by the scheduling policy.

6.89.1. add POST

Add a filter to a specified user defined scheduling policy.

Table 6.252. Parameters summary

NameTypeDirectionSummary

filter

Filter

In/Out

 

6.89.2. list GET

Returns the list of filters used by the scheduling policy.

The order of the returned list of filters isn’t guaranteed.

Table 6.253. Parameters summary

NameTypeDirectionSummary

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

filters

Filter[]

Out

 

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of filters to return.

6.89.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.89.2.2. max

Sets the maximum number of filters to return. If not specified all the filters are returned.

6.90. Follow

6.91. GlusterBrick

This service manages a single gluster brick.

Table 6.254. Methods summary

NameSummary

get

Get details of a brick.

remove

Removes a brick.

replace

Replaces this brick with a new one.

6.91.1. get GET

Get details of a brick.

Retrieves status details of brick from underlying gluster volume with header All-Content set to true. This is the equivalent of running gluster volume status <volumename> <brickname> detail.

For example, to get the details of brick 234 of gluster volume 123, send a request like this:

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234

Which will return a response body like this:

<brick id="234">
  <name>host1:/rhgs/data/brick1</name>
  <brick_dir>/rhgs/data/brick1</brick_dir>
  <server_id>111</server_id>
  <status>up</status>
  <device>/dev/mapper/RHGS_vg1-lv_vmaddldisks</device>
  <fs_name>xfs</fs_name>
  <gluster_clients>
    <gluster_client>
      <bytes_read>2818417648</bytes_read>
      <bytes_written>1384694844</bytes_written>
      <client_port>1011</client_port>
      <host_name>client2</host_name>
    </gluster_client>
  </gluster_clients>
  <memory_pools>
    <memory_pool>
      <name>data-server:fd_t</name>
      <alloc_count>1626348</alloc_count>
      <cold_count>1020</cold_count>
      <hot_count>4</hot_count>
      <max_alloc>23</max_alloc>
      <max_stdalloc>0</max_stdalloc>
      <padded_size>140</padded_size>
      <pool_misses>0</pool_misses>
    </memory_pool>
  </memory_pools>
  <mnt_options>rw,seclabel,noatime,nodiratime,attr2,inode64,sunit=512,swidth=2048,noquota</mnt_options>
  <pid>25589</pid>
  <port>49155</port>
</brick>

Table 6.255. Parameters summary

NameTypeDirectionSummary

brick

GlusterBrick

Out

 

follow

String

In

Indicates which inner links should be followed.

6.91.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.91.2. remove DELETE

Removes a brick.

Removes a brick from the underlying gluster volume and deletes entries from database. This can be used only when removing a single brick without data migration. To remove multiple bricks and with data migration, use migrate instead.

For example, to delete brick 234 from gluster volume 123, send a request like this:

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234

Table 6.256. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.91.3. replace POST

Replaces this brick with a new one.

Important

This operation has been deprecated since version 3.5 of the engine and will be removed in the future. Use add brick(s) and migrate brick(s) instead.

Table 6.257. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the replacement should be performed asynchronously.

force

Boolean

In

 

6.92. GlusterBricks

This service manages the gluster bricks in a gluster volume

Table 6.258. Methods summary

NameSummary

activate

Activate the bricks post data migration of remove brick operation.

add

Adds a list of bricks to gluster volume.

list

Lists the bricks of a gluster volume.

migrate

Start migration of data prior to removing bricks.

remove

Removes bricks from gluster volume.

stopmigrate

Stops migration of data from bricks for a remove brick operation.

6.92.1. activate POST

Activate the bricks post data migration of remove brick operation.

Used to activate brick(s) once the data migration from bricks is complete but user no longer wishes to remove bricks. The bricks that were previously marked for removal will now be used as normal bricks.

For example, to retain the bricks that on glustervolume 123 from which data was migrated, send a request like this:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate

With a request body like this:

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>

Table 6.259. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

bricks

GlusterBrick[]

In

The list of bricks that need to be re-activated.

6.92.2. add POST

Adds a list of bricks to gluster volume.

Used to expand a gluster volume by adding bricks. For replicated volume types, the parameter replica_count needs to be passed. In case the replica count is being increased, then the number of bricks needs to be equivalent to the number of replica sets.

For example, to add bricks to gluster volume 123, send a request like this:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

With a request body like this:

<bricks>
  <brick>
    <server_id>111</server_id>
    <brick_dir>/export/data/brick3</brick_dir>
  </brick>
</bricks>

Table 6.260. Parameters summary

NameTypeDirectionSummary

bricks

GlusterBrick[]

In/Out

The list of bricks to be added to the volume

replica_count

Integer

In

Replica count of volume post add operation.

stripe_count

Integer

In

Stripe count of volume post add operation.

6.92.3. list GET

Lists the bricks of a gluster volume.

For example, to list bricks of gluster volume 123, send a request like this:

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

Provides an output as below:

<bricks>
  <brick id="234">
    <name>host1:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>111</server_id>
    <status>up</status>
  </brick>
  <brick id="233">
    <name>host2:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>222</server_id>
    <status>up</status>
  </brick>
</bricks>

The order of the returned list is based on the brick order provided at gluster volume creation.

Table 6.261. Parameters summary

NameTypeDirectionSummary

bricks

GlusterBrick[]

Out

 

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of bricks to return.

6.92.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.92.3.2. max

Sets the maximum number of bricks to return. If not specified all the bricks are returned.

6.92.4. migrate POST

Start migration of data prior to removing bricks.

Removing bricks is a two-step process, where the data on bricks to be removed, is first migrated to remaining bricks. Once migration is completed the removal of bricks is confirmed via the API remove. If at any point, the action needs to be cancelled stopmigrate has to be called.

For instance, to delete a brick from a gluster volume with id 123, send a request:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate

With a request body like this:

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>

The migration process can be tracked from the job id returned from the API using job and steps in job using step

Table 6.262. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the migration should be performed asynchronously.

bricks

GlusterBrick[]

In

List of bricks for which data migration needs to be started.

6.92.5. remove DELETE

Removes bricks from gluster volume.

The recommended way to remove bricks without data loss is