搜索

此内容没有您所选择的语言版本。

Chapter 6. Services

download PDF

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

group

AffinityGroup

Out

The affinity group.

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

Add a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

6.3.1. add POST

Add a virtual machine to the affinity group.

For example, to add the virtual machine 000-000 to affinity group 123-456 send a request to:

POST /ovirt-engine/api/clusters/000-000/affinitygroups/123-456/vms

With the following body:

<vm id="000-000"/>
Table 6.8. Parameters summary
NameTypeDirectionSummary

vm

Vm

In/Out

 

6.3.2. list GET

List all virtual machines assigned to this affinity group.

Table 6.9. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out

 

6.3.2.1. max

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

6.4. AffinityGroups

The affinity groups service manages virtual machine relationships and dependencies.

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>
  <positive>true</positive>
  <enforcing>true</enforcing>
</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.

Table 6.12. Parameters summary
NameTypeDirectionSummary

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

label

AffinityLabel

Out

 

6.5.2. remove DELETE

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

6.5.3. update PUT

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

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

host

Host

Out

 

6.6.2. remove DELETE

Remove a label from a host.

6.7. AffinityLabelHosts

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

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.

Table 6.20. Parameters summary
NameTypeDirectionSummary

hosts

Host[]

Out

 

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

vm

Vm

Out

 

6.8.2. remove DELETE

Remove a label from a vm.

6.9. AffinityLabelVms

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

Table 6.23. Methods summary
NameSummary

add

Add a label to a vm.

list

List all vms 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 vms with the label.

Table 6.25. Parameters summary
NameTypeDirectionSummary

vms

Vm[]

Out

 

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.

Table 6.28. Parameters summary
NameTypeDirectionSummary

labels

AffinityLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels to return.

6.10.2.1. max

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

6.11. AssignedAffinityLabel

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

Table 6.29. Methods summary
NameSummary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

6.11.1. get GET

Retrieves details about the attached label.

Table 6.30. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

Out

 

6.11.2. remove DELETE

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

6.12. AssignedAffinityLabels

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

Table 6.31. Methods summary
NameSummary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

6.12.1. add POST

Attaches a label to an entity.

Table 6.32. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.12.2. list GET

Lists all labels that are attached to an entity.

Table 6.33. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel[]

Out

 

6.13. AssignedCpuProfile

Table 6.34. Methods summary
NameSummary

get

 

remove

 

6.13.1. get GET

Table 6.35. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

Out

 

6.13.2. remove DELETE

Table 6.36. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.14. AssignedCpuProfiles

Table 6.37. Methods summary
NameSummary

add

 

list

 

6.14.1. add POST

Table 6.38. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.14.2. list GET

Table 6.39. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out

 

6.14.2.1. max

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

6.15. AssignedDiskProfile

Table 6.40. Methods summary
NameSummary

get

 

remove

 

6.15.1. get GET

Table 6.41. Parameters summary
NameTypeDirectionSummary

disk_profile

DiskProfile

Out

 

6.15.2. remove DELETE

Table 6.42. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.16. AssignedDiskProfiles

Table 6.43. Methods summary
NameSummary

add

 

list

 

6.16.1. add POST

Table 6.44. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.16.2. list GET

Table 6.45. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out

 

6.16.2.1. max

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

6.17. AssignedPermissions

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

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.17.1. add POST

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

For example, to assign the UserVmManager role to the virtual machine with id 123 to the user with id 456 send a request like this:

POST /ovirt-engine/api/vms/123/permissions

With a request body like this:

<permission>
  <role>
    <name>UserVmManager</name>
  </role>
  <user id="456"/>
</permission>

To assign the SuperUser role to the system to the user with id 456 send a request like this:

POST /ovirt-engine/api/permissions

With a request body like this:

<permission>
  <role>
    <name>SuperUser</name>
  </role>
  <user id="456"/>
</permission>

If you want to assign permission to the group instead of the user please replace the user element with the group element with proper id of the group. For example to assign the UserRole role to the cluster with id 123 to the group with id 789 send a request like this:

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

With a request body like this:

<permission>
  <role>
    <name>UserRole</name>
  </role>
  <group id="789"/>
</permission>
Table 6.47. Parameters summary
NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

6.17.2. list GET

List all the permissions of the specific entity.

For example to list all the permissions of the cluster with id 123 send a request like this:

GET /ovirt-engine/api/clusters/123/permissions
<permissions>
  <permission id="456">
    <cluster id="123"/>
    <role id="789"/>
    <user id="451"/>
  </permission>
  <permission id="654">
    <cluster id="123"/>
    <role id="789"/>
    <group id="127"/>
  </permission>
</permissions>
Table 6.48. Parameters summary
NameTypeDirectionSummary

permissions

Permission[]

Out

The list of permissions.

6.18. AssignedRoles

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

Table 6.49. Methods summary
NameSummary

list

 

6.18.1. list GET

Table 6.50. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

 

6.18.1.1. max

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

6.19. AssignedTag

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

Table 6.51. Methods summary
NameSummary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

6.19.1. get GET

Gets the information about the assigned tag.

For example to retrieve the information about the tag with the id 456 which is assigned to virtual machine with id 123 send a request like this:

GET /ovirt-engine/api/vms/123/tags/456
<tag href="/ovirt-engine/api/tags/456" id="456">
  <name>root</name>
  <description>root</description>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>
Table 6.52. Parameters summary
NameTypeDirectionSummary

tag

Tag

Out

The assigned tag.

6.19.2. remove DELETE

Unassign tag from specific entity in the system.

For example to unassign the tag with id 456 from virtual machine with id 123 send a request like this:

DELETE /ovirt-engine/api/vms/123/tags/456
Table 6.53. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.20. AssignedTags

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

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.20.1. add POST

Assign tag to specific entity in the system.

For example to assign tag mytag to virtual machine with the id 123 send a request like this:

POST /ovirt-engine/api/vms/123/tags

With a request body like this:

<tag>
  <name>mytag</name>
</tag>
Table 6.55. Parameters summary
NameTypeDirectionSummary

tag

Tag

In/Out

The assigned tag.

6.20.2. list GET

List all tags assigned to the specific entity.

For example to list all the tags of the virtual machine with id 123 send a request like this:

GET /ovirt-engine/api/vms/123/tags
<tags>
  <tag href="/ovirt-engine/api/tags/222" id="222">
    <name>mytag</name>
    <description>mytag</description>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </tag>
</tags>
Table 6.56. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.

6.20.2.1. max

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

6.21. AssignedVnicProfile

Table 6.57. Methods summary
NameSummary

get

 

remove

 

6.21.1. get GET

Table 6.58. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

Out

 

6.21.2. remove DELETE

Table 6.59. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.22. AssignedVnicProfiles

Table 6.60. Methods summary
NameSummary

add

 

list

 

6.22.1. add POST

Table 6.61. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

In/Out

 

6.22.2. list GET

Table 6.62. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

 

6.22.2.1. max

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

6.23. AttachedStorageDomain

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.23.1. activate POST

This operation activates an attached storage domain. Once the storage domain is activated it is ready for use with the data center.

POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate

The activate action does not take any action specific parameters, so the request body should contain an empty action:

<action/>
Table 6.64. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.23.2. deactivate POST

This operation deactivates an attached storage domain. Once the storage domain is deactivated it will not be used with the data center.

POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate

The deactivate action does not take any action specific parameters, so the request body should contain an empty action:

<action/>
Table 6.65. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.23.3. get GET

Table 6.66. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

Out

 

6.23.4. remove DELETE

Table 6.67. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.24. AttachedStorageDomains

Table 6.68. Methods summary
NameSummary

add

 

list

 

6.24.1. add POST

Table 6.69. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

 

6.24.2. list GET

Table 6.70. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out

 

6.24.2.1. max

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

6.25. Balance

Table 6.71. Methods summary
NameSummary

get

 

remove

 

6.25.1. get GET

Table 6.72. Parameters summary
NameTypeDirectionSummary

balance

Balance

Out

 

filter

Boolean

In

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

6.25.2. remove DELETE

Table 6.73. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.26. Balances

Table 6.74. Methods summary
NameSummary

add

 

list

 

6.26.1. add POST

Table 6.75. Parameters summary
NameTypeDirectionSummary

balance

Balance

In/Out

 

6.26.2. list GET

Table 6.76. Parameters summary
NameTypeDirectionSummary

balances

Balance[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of balances to return.

6.26.2.1. max

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

6.27. Bookmark

A service to manage a bookmark.

Table 6.77. Methods summary
NameSummary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

6.27.1. get GET

Get a bookmark.

An example for getting a bookmark:

GET /ovirt-engine/api/bookmarks/123
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
  <name>example_vm</name>
  <value>vm: name=example*</value>
</bookmark>
Table 6.78. Parameters summary
NameTypeDirectionSummary

bookmark

Bookmark

Out

The requested bookmark.

6.27.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123
Table 6.79. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.27.3. update PUT

Update a bookmark.

An example for updating a bookmark:

PUT /ovirt-engine/api/bookmarks/123

With the request body:

<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>
Table 6.80. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

6.28. Bookmarks

A service to manage bookmarks.

Table 6.81. Methods summary
NameSummary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

6.28.1. add POST

Adding a new bookmark.

Example of adding a bookmark:

POST /ovirt-engine/api/bookmarks
<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>
Table 6.82. Parameters summary
NameTypeDirectionSummary

bookmark

Bookmark

In/Out

The added bookmark.

6.28.2. list GET

Listing all the available bookmarks.

Example of listing bookmarks:

GET /ovirt-engine/api/bookmarks
<bookmarks>
  <bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
    <name>database</name>
    <value>vm: name=database*</value>
  </bookmark>
  <bookmark href="/ovirt-engine/api/bookmarks/456" id="456">
    <name>example</name>
    <value>vm: name=example*</value>
  </bookmark>
</bookmarks>
Table 6.83. Parameters summary
NameTypeDirectionSummary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

max

Integer

In

Sets the maximum number of bookmarks to return.

6.28.2.1. max

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

6.29. Cluster

A service to manage specific cluster.

Table 6.84. Methods summary
NameSummary

get

Get information about the cluster.

remove

Removes cluster from the system.

resetemulatedmachine

 

update

Updates information about the cluster.

6.29.1. get GET

Get information about the cluster.

An example of getting a cluster:

GET /ovirt-engine/api/clusters/123
<cluster href="/ovirt-engine/api/clusters/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/clusters/123/resetemulatedmachine" rel="resetemulatedmachine"/>
  </actions>
  <name>Default</name>
  <description>The default server cluster</description>
  <link href="/ovirt-engine/api/clusters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/clusters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/clusters/123/glustervolumes" rel="glustervolumes"/>
  <link href="/ovirt-engine/api/clusters/123/glusterhooks" rel="glusterhooks"/>
  <link href="/ovirt-engine/api/clusters/123/affinitygroups" rel="affinitygroups"/>
  <link href="/ovirt-engine/api/clusters/123/cpuprofiles" rel="cpuprofiles"/>
  <ballooning_enabled>false</ballooning_enabled>
  <cpu>
    <architecture>x86_64</architecture>
    <type>Intel Penryn Family</type>
  </cpu>
  <error_handling>
    <on_error>migrate</on_error>
  </error_handling>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
  </fencing_policy>
  <gluster_service>false</gluster_service>
  <ha_reservation>false</ha_reservation>
  <ksm>
    <enabled>true</enabled>
    <merge_across_nodes>true</merge_across_nodes>
  </ksm>
  <maintenance_reason_required>false</maintenance_reason_required>
  <memory_policy>
    <over_commit>
      <percent>100</percent>
    </over_commit>
    <transparent_hugepages>
      <enabled>true</enabled>
    </transparent_hugepages>
  </memory_policy>
  <migration>
    <auto_converge>inherit</auto_converge>
    <bandwidth>
      <assignment_method>auto</assignment_method>
    </bandwidth>
    <compressed>inherit</compressed>
  </migration>
  <optional_reason>false</optional_reason>
  <required_rng_sources>
    <required_rng_source>random</required_rng_source>
  </required_rng_sources>
  <scheduling_policy href="/ovirt-engine/api/schedulingpolicies/456" id="456"/>
  <threads_as_cores>false</threads_as_cores>
  <trusted_service>false</trusted_service>
  <tunnel_migration>false</tunnel_migration>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <virt_service>true</virt_service>
  <data_center href="/ovirt-engine/api/datacenters/111" id="111"/>
</cluster>
Table 6.85. Parameters summary
NameTypeDirectionSummary

cluster

Cluster

Out

 

filter

Boolean

In

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

6.29.2. remove DELETE

Removes cluster from the system.

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Table 6.86. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.29.3. resetemulatedmachine POST

Table 6.87. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.29.4. update PUT

Updates information about the cluster.

Only specified fields are updated, others remain unchanged.

E.g. update cluster’s CPU:

PUT /ovirt-engine/api/clusters/123

With request body like:

<cluster>
  <cpu>
    <type>Intel Haswell-noTSX Family</type>
  </cpu>
</cluster>
Table 6.88. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

 

6.30. ClusterLevel

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

Table 6.89. Methods summary
NameSummary

get

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

6.30.1. get GET

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

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

GET /ovirt-engine/api/clusterlevels/3.6

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

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

level

ClusterLevel

Out

Retreived cluster level.

6.31. ClusterLevels

Provides information about the capabilities of different cluster levels supported by the engine. Version 4.0 of the engine supports levels 4.0 and 3.6. Each of these levels support different sets of CPU types, for example. This service provides that information.

Table 6.91. Methods summary
NameSummary

list

Lists the cluster levels supported by the system.

6.31.1. list GET

Lists the cluster levels supported by the system.

GET /ovirt-engine/api/clusterlevels

This will return a list of available cluster levels.

<cluster_levels>
  <cluster_level id="4.0">
     ...
  </cluster_level>
  ...
</cluster_levels>
Table 6.92. Parameters summary
NameTypeDirectionSummary

levels

ClusterLevel[]

Out

Retrieved cluster levels.

6.32. ClusterNetwork

A service to manage a specific cluster network.

Table 6.93. Methods summary
NameSummary

get

Retrieves the cluster network details.

remove

Unassigns the network from a cluster.

update

Updates the network in the cluster.

6.32.1. get GET

Retrieves the cluster network details.

Table 6.94. Parameters summary
NameTypeDirectionSummary

network

Network

Out

The cluster network.

6.32.2. remove DELETE

Unassigns the network from a cluster.

6.32.3. update PUT

Updates the network in the cluster.

Table 6.95. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The cluster network.

6.33. ClusterNetworks

A service to manage cluster networks.

Table 6.96. Methods summary
NameSummary

add

Assigns the network to a cluster.

list

Lists the networks that are assigned to the cluster.

6.33.1. add POST

Assigns the network to a cluster.

Post a request like in the example below to assign the network to a cluster:

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

Use the following example in its body:

<network id="123" />
Table 6.97. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The network object to be assigned to the cluster.

6.33.2. list GET

Lists the networks that are assigned to the cluster.

Table 6.98. Parameters summary
NameTypeDirectionSummary

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

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

6.34. Clusters

A service to manage clusters.

Table 6.99. Methods summary
NameSummary

add

Creates a new cluster.

list

 

6.34.1. add POST

Creates a new cluster.

This requires the name, cpu.type and data_center attributes. Identify the data center with either the id or name attributes.

POST /ovirt-engine/api/clusters

With a request body like this:

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Penryn Family</type>
  </cpu>
  <data_center id="123"/>
</cluster>
Table 6.100. Parameters summary
NameTypeDirectionSummary

cluster

Cluster

In/Out

 

6.34.2. list GET

Table 6.101. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter 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.

max

Integer

In

Sets the maximum number of clusters to return.

search

String

In

A query string used to restrict the returned clusters.

6.34.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into account. The default value is true, which means that case is taken into account. If you want to search ignoring case set it to false.

6.34.2.2. max

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

6.35. Copyable

Table 6.102. Methods summary
NameSummary

copy

 

6.35.1. copy POST

Table 6.103. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

6.36. CpuProfile

Table 6.104. Methods summary
NameSummary

get

 

remove

 

update

 

6.36.1. get GET

Table 6.105. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

Out

 

6.36.2. remove DELETE

Table 6.106. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.36.3. update PUT

Table 6.107. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

 

6.37. CpuProfiles

Table 6.108. Methods summary
NameSummary

add

 

list

 

6.37.1. add POST

Table 6.109. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.37.2. list GET

Table 6.110. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out

 

6.37.2.1. max

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

6.38. DataCenter

A service to manage a data center.

Table 6.111. Methods summary
NameSummary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

6.38.1. get GET

Get a data center.

An example of getting a data center:

GET /ovirt-engine/api/datacenters/123
<data_center href="/ovirt-engine/api/datacenters/123" id="123">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
  <link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
  <link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
  <link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
  <local>false</local>
  <quota_mode>disabled</quota_mode>
  <status>up</status>
  <storage_format>v3</storage_format>
  <supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
   </version>
  </supported_versions>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <mac_pool href="/ovirt-engine/api/macpools/456" id="456"/>
</data_center>
Table 6.112. Parameters summary
NameTypeDirectionSummary

data_center

DataCenter

Out

 

filter

Boolean

In

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

6.38.2. remove DELETE

Removes the data center.

DELETE /ovirt-engine/api/datacenters/123

Without any special parameters, the storage domains attached to the data center are detached and then removed from the storage. If something fails when performing this operation, for example if there is no host available to remove the storage domains from the storage, the complete operation will fail.

If the force parameter is true then the operation will always succeed, even if something fails while removing one storage domain, for example. The failure is just ignored and the data center is removed from the database anyway.

Table 6.113. 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.38.2.1. force

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

This parameter is optional, and the default value is false.

6.38.3. update PUT

Updates the data center.

The name, description, storage_type, version, storage_format and mac_pool elements are updatable post-creation. For example, to change the name and description of data center 123 send a request like this:

PUT /ovirt-engine/api/datacenters/123

With a request body like this:

<data_center>
  <name>myupdatedname</name>
  <description>An updated description for the data center</description>
</data_center>
Table 6.114. 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.39. DataCenterNetwork

A service to manage a specific data center network.

Table 6.115. Methods summary
NameSummary

get

Retrieves the data center network details.

remove

Removes the network.

update

Updates the network in the data center.

6.39.1. get GET

Retrieves the data center network details.

Table 6.116. Parameters summary
NameTypeDirectionSummary

network

Network

Out

The data center network.

6.39.2. remove DELETE

Removes the network.

6.39.3. update PUT

Updates the network in the data center.

Table 6.117. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The data center network.

6.40. DataCenterNetworks

A service to manage data center networks.

Table 6.118. Methods summary
NameSummary

add

Create a new network in a data center.

list

Lists networks in the data center.

6.40.1. add POST

Create a new network in a data center.

Post a request like in the example below to create a new network in a data center with an ID of 123.

POST /ovirt-engine/api/datacenters/123/networks

Use the following example in its body:

<network>
  <name>mynetwork</name>
</network>
Table 6.119. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The network object to be created in the data center.

6.40.2. list GET

Lists networks in the data center.

Table 6.120. Parameters summary
NameTypeDirectionSummary

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

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

6.41. DataCenters

A service to manage data centers.

Table 6.121. Methods summary
NameSummary

add

Creates a new data center.

list

Lists the data centers.

6.41.1. add POST

Creates a new data center.

Creation of a new data center requires the name and local elements. For example, to create a data center named mydc that uses shared storage (NFS, iSCSI or Fibre Channel) send a request like this:

POST /ovirt-engine/api/datacenters

With a request body like this:

<data_center>
  <name>mydc</name>
  <local>false</local>
</data_center>
Table 6.122. Parameters summary
NameTypeDirectionSummary

data_center

DataCenter

In/Out

The data center that is being added.

6.41.2. list GET

Lists the data centers.

The following request retrieves a representation of the data centers:

GET /ovirt-engine/api/datacenters

The above request performed with curl:

curl \
--request GET \
--cacert /etc/pki/ovirt-engine/ca.pem \
--header "Version: 4" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
https://myengine.example.com/ovirt-engine/api/datacenters

This is what an example response could look like:

<data_center href="/ovirt-engine/api/datacenters/123" id="123">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
  <link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
  <link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
  <link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
  <local>false</local>
  <quota_mode>disabled</quota_mode>
  <status>up</status>
  <supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
    </version>
  </supported_versions>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
</data_center>

Note the id code of your Default data center. This code identifies this data center in relation to other resources of your virtual environment.

The data center also contains a link to the storage domains collection. The data center uses this collection to attach storage domains from the storage domains main collection.

Table 6.123. 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.

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.41.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into account. The default value is true, which means that case is taken into account. If you want to search ignoring case set it to false.

6.41.2.2. max

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

6.42. Disk

Manages a single disk.

Table 6.124. Methods summary
NameSummary

copy

This operation copies a disk to the specified storage domain.

export

 

get

 

move

Moves a disk to another storage domain.

remove

 

sparsify

Sparsify the disk.

6.42.1. copy POST

This operation copies a disk to the specified storage domain.

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

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

With a request body like this:

<action>
  <storage_domain id="456"/>
  <disk>
    <name>mydisk</name>
  </disk>
</action>
Table 6.125. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

disk

Disk

In

 

filter

Boolean

In

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

storage_domain

StorageDomain

In

 

6.42.2. export POST

Table 6.126. 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.42.3. get GET

Table 6.127. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.42.4. move POST

Moves a disk to another storage domain.

For example, to move the disk with identifier 123 to a storage domain with identifier 456 send the following request:

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

With the following request body:

<action>
  <storage_domain id="456"/>
</action>
Table 6.128. 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

 

6.42.5. remove DELETE

Table 6.129. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.42.6. sparsify POST

Sparsify the disk.

Sparsification frees space in the disk image that is not used by its filesystem. As a result, the image will occupy less space on the storage.

Currently sparsification works only on disks without snapshots. Disks having derived disks are also not allowed.

6.43. DiskAttachment

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

Table 6.130. 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.43.1. get GET

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

An example of getting a disk attachment:

GET /ovirt-engine/api/vms/123/diskattachments/456
<disk_attachment href="/ovirt-engine/api/vms/123/diskattachments/456" id="456">
  <active>true</active>
  <bootable>true</bootable>
  <interface>virtio</interface>
  <disk href="/ovirt-engine/api/disks/456" id="456"/>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</disk_attachment>
Table 6.131. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

6.43.2. remove DELETE

Removes the disk attachment.

This will only detach the disk from the virtual machine, but won’t remove it from the system, unless the detach_only parameter is false.

An example of removing a disk attachment:

DELETE /ovirt-engine/api/vms/123/diskattachments/456?detach_only=true
Table 6.132. 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.43.2.1. detach_only

Indicates if the disk should only be detached from the virtual machine, but not removed from the system. The default value is true, which won’t remove the disk from the system.

6.43.3. update PUT

Update the disk attachment and the disk properties within it.

PUT /vms/{vm:id}/disksattachments/{attachment:id}
<disk_attachment>
  <bootable>true</bootable>
  <interface>ide</interface>
  <active>true</active>
  <disk>
    <name>mydisk</name>
    <provisioned_size>1024</provisioned_size>
    ...
  </disk>
</disk_attachment>
Table 6.133. Parameters summary
NameTypeDirectionSummary

disk_attachment

DiskAttachment

In/Out

 

6.44. DiskAttachments

This service manages the set of disks attached to a virtual machine. Each attached disk is represented by a DiskAttachment, containing the bootable flag, the disk interface and the reference to the disk.

Table 6.134. 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.44.1. add POST

Adds a new disk attachment to the virtual machine. The attachment parameter can contain just a reference, if the disk already exists:

<disk_attachment>
  <bootable>true</bootable>
  <pass_discard>true</pass_discard>
  <interface>ide</interface>
  <active>true</active>
  <disk id="123"/>
</disk_attachment>

Or it can contain the complete representation of the disk, if the disk doesn’t exist yet:

<disk_attachment>
  <bootable>true</bootable>
  <pa