Show Table of Contents
10.7. Sub-Collections
10.7.1. Networks Sub-Collection
10.7.1.1. Networks Sub-Collection
Networks associated with a cluster are represented with the
networks sub-collection. Every host within a cluster connects to these associated networks.
The representation of a cluster's
network sub-collection is the same as a standard network resource except for the following additional elements:
Table 10.4. Additional network elements
| Element | Type | Description | Properties |
|---|---|---|---|
cluster id= | relationship | A reference to the cluster of which this network is a member. | 
|
required | Boolean | Defines required or optional network status. | |
display | Boolean | Defines the display network status. Used for backward compatibility. | |
usages | complex | Defines a set of usage elements for the network. Users can define networks as VM and DISPLAY networks at this level. |
An API user manipulates the
networks sub-collection with the standard REST methods. POSTing a network id or name reference to the networks sub-collection associates the network with the cluster.
Example 10.6. Associating a network resource with a cluster
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>ovirtmgmt</name>
</network>
HTTP/1.1 201 Created
Location: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"
href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>ovirtmgmt</name>
<status>
<state>operational</state>
</status>
<description>Display Network</description>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
href="/ovirt-engine/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
<required>true</required>
<usages>
<usage>VM</usage>
</usages>
</network>
Update the resource with a
PUT request.
Example 10.7. Setting the display network status
PUT /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<required>false</required>
<usages>
<usage>VM</usage>
<usage>DISPLAY</usage>
</usages>
</network>
The required or optional network status is set using a
PUT request to specify the Boolean value (true or false) of the required element.
Example 10.8. Setting optional network status
PUT /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<required>false</required>
</network>
An association is removed with a
DELETE request to the appropriate element in the collection.
Example 10.9. Removing a network association from a cluster
DELETE /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1 HTTP/1.1 204 No Content
10.7.2. Storage Volumes Sub-Collection
10.7.2.1. Red Hat Gluster Storage Volumes Sub-Collection
Red Hat Virtualization provides a means for creating and managing Red Hat Gluster Storage volumes. Red Hat Gluster Storage volumes are associated with clusters and are represented with the
glustervolumes sub-collection.
The representation of a Red Hat Gluster Storage volume resource in the
glustervolumes sub-collection is defined using the following elements:
Table 10.5. Gluster volume elements
| Element | Type | Description | Properties |
|---|---|---|---|
volume_type | enumerated | Defines the volume type. See the capabilities collection for a list of volume types. | 
|
bricks | relationship | The sub-collection for the Red Hat Gluster Storage bricks. When creating a new volume, the request requires a set of brick elements to create and manage in this cluster. Requires the server_id of the Red Hat Gluster Storage server and a brick_dir element for the brick directory |
|
transport_types | complex | Defines a set of volume transport_type elements. See the capabilities collection for a list of available transport types. |
|
replica_count | integer | Defines the file replication count for a replicated volume. |
|
stripe_count | integer | Defines the stripe count for a striped volume |
|
options | complex | A set of additional Red Hat Gluster Storage option elements. Each option includes an option name and a value. |
|
Example 10.10. An XML representation of a Red Hat Gluster Storage volume
<gluster_volume id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
/glustervolume/e199f877-900a-4e30-8114-8e3177f47651">
<name>GlusterVolume1</name>
<link rel="bricks"
href="/ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
/glustervolume/e199f877-900a-4e30-8114-8e3177f47651/bricks"/>
<volume_type>DISTRIBUTED_REPLICATE</volume_type>
<transport_types>
<transport_type>TCP</transport_type>
</transport_types>
<replica_count>2</replica_count>
<stripe_count>1</stripe_count>
<options>
<option>
<name>cluster.min-free-disk</name>
<value>536870912</value>
</option>
</options>
</gluster_volume>
Create a Red Hat Gluster Storage volume via a
POST request with the required name, volume_type and bricks to the sub-collection.
Example 10.11. Creating a Red Hat Gluster Storage volume
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<gluster_volume>
<name>GlusterVolume1</name>
<volume_type>DISTRIBUTED_REPLICATE</volume_type>
<bricks>
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<bricks>
</gluster_volume>
Remove a Red Hat Gluster Storage volume with a
DELETE request.
Example 10.12. Removing a Red Hat Gluster Storage volume
DELETE /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1 HTTP/1.1 204 No Content
Important
Resources in the
glustervolumes sub-collection cannot be updated.
10.7.2.2. Bricks Sub-Collection
The
glustervolumes sub-collection contains its own bricks sub-collection to define individual bricks in a Red Hat Gluster Storage volume. Additional information can be retrieved for GET requests using the All-Content: true header.
The representation of a volume's
bricks sub-collection is defined using the following elements:
Table 10.6. Brick elements
| Element | Type | Description | Properties |
|---|---|---|---|
server_id | string | A reference to the Red Hat Gluster Storage server. |
|
brick_dir | string | Defines a brick directory on the Red Hat Gluster Storage server. |
|
replica_count | integer | Defines the file replication count for the brick in the volume. |
|
stripe_count | integer | Defines the stripe count for the brick in the volume |
|
Create new bricks via a
POST request with the required server_id and brick_dir to the sub-collection.
Example 10.13. Adding a brick
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
Remove a brick with a
DELETE request.
Example 10.14. Removing a brick
DELETE /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks/0a473ebe-01d2-444d-8f58-f565a436b8eb HTTP/1.1 HTTP/1.1 204 No Content
Important
Resources in the
bricks sub-collection cannot be updated.
10.7.2.3. Actions
10.7.2.3.1. Start Action
The
start action makes a Gluster volume available for use.
Example 10.15. Starting a Volume
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
Use an optional
force Boolean element to force the action for a running volume. This is useful for starting disabled brick processes in a running volume.
10.7.2.3.2. Stop Action
The
stop action deactivates a Gluster volume.
Example 10.16. Stopping a Volume
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
Use an optional
force Boolean element to brute force the stop action.
10.7.2.3.3. Set Option Action
The
setoption action sets a volume option.
Example 10.17. Set an option
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<option>
<name>cluster.min-free-disk</name>
<value>536870912</value>
</option>
</action>
10.7.2.3.4. Reset Option Action
The
resetoption action resets a volume option.
Example 10.18. Reset an option
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<option>
<name>cluster.min-free-disk</name>
</option>
</action>
10.7.2.3.5. Reset All Options Action
The
resetalloptions action resets all volume options.
Example 10.19. Reset all options
POST /ovirt-engine/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetalloptions HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
10.7.3. Affinity Groups Sub-Collection
10.7.3.1. Affinity Group Sub-Collection
The representation of a virtual machine affinity group resource in the
affinitygroups sub-collection is defined using the following elements:
Table 10.7. Affinity group elements
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | A plain text, human readable name for the affinity group. |
|
cluster | relationship | A reference to the cluster to which the affinity group applies. | |
positive | Boolean: true or false | Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group. | |
enforcing | Boolean: true or false | Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group. |
Example 10.20. An XML representation of a virtual machine affinity group
<affinity_group href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<name>AF_GROUP_001</name>
<cluster href="/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>
Create a virtual machine affinity group via a
POST request with the required name attribute.
Example 10.21. Creating a virtual machine affinity group
POST https://XX.XX.XX.XX/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups HTTP/1.1 Accept: application/xml Content-Type: application/xml <affinity_group> <name>AF_GROUP_001</name> <positive>true</positive> <enforcing>true</enforcing> </affinity_group>
Remove a virtual machine affinity group with a
DELETE request.
Example 10.22. Removing a virtual machine affinity group
DELETE https://XX.XX.XX.XX/ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000 HTTP/1.1 HTTP/1.1 204 No Content
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.