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