Chapter 9. Host Clusters

The clusters collection provides information about host clusters in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="clusters" link obtained from the entry point URI (see Chapter 4, Entry Point).
The following table shows specific elements contained in a host cluster resource representation.

Note

The icons used in the properties column of this table are described in Table 7.1, “Element property icons”

Table 9.1. Host cluster elements

Element Type Description Properties
link rel="networks" relationship A link to the sub-collection for networks associated with this cluster.
link rel="permissions" relationship A link to the sub-collection for cluster permissions. See Section 7.3.7, “ Permissions ”.
cpu id= complex A server CPU reference that defines the CPU type all hosts must support in the cluster. See Section 6.1.3, “CPUs”.
data_center id= GUID A reference to the data center membership of this cluster. See Chapter 8, Data Centers.
memory_policy complex Defines the cluster's policy on host memory utilization. See Table 9.2, “Memory policy elements”.
scheduling_policy complex Defines the load-balancing or power sharing modes for hosts in the cluster. See Table 9.3, “Scheduling policy elements”.
version major= minor= complex The compatibility level of the cluster. See Chapter 5, Compatibility Level Versions.
supported_versions complex A list of possible version levels for the cluster. See Chapter 5, Compatibility Level Versions.
error_handling complex/enumerated Defines virtual machine handling when a host within a cluster becomes non-operational. Requires a single on_error element containing an enumerated type property listed in capabilities. See Section 6.1.19, “Error Handling”.

The memory_policy element contains the following elements:

Table 9.2. Memory policy elements

Element Type Description Properties
overcommit percent= complex The percentage of host memory allowed in use before no more virtual machines can start on a host. Virtual machines can use more than the available host memory due to memory sharing under KSM. Recommended values include 100 (None), 150 (Server Load) and 200 (Desktop Load).
transparent_hugepages complex Define the enabled status of Transparent Hugepages. The status is either true or false. Check capabilities feature set (see Section 6.1.2, “Features”) to ensure your version supports transparent hugepages.

The scheduling_policy element contains the following elements:

Table 9.3. Scheduling policy elements

Element Type Description Properties
policy enumerated The VM scheduling mode for hosts in the cluster. A list of enumerated types are listed in capabilities. See Section 6.3, “Scheduling Policies”.
thresholds low= high= duration= complex Defines CPU limits for the host. The high attribute controls the highest CPU usage percentage the host can have before being considered overloaded. The low attribute controls the lowest CPU usage percentage the host can have before being considered underutilized. The duration attribute refers to the number of seconds the host needs to be overloaded before the scheduler starts and moves the load to another host.

Example 9.1. An XML representation of a host cluster

<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
  href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
    <name>Default</name>
    <description>The default server cluster</description>
    <link rel="networks"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
    <link rel="permissions"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
    <cpu id="Intel Penryn Family"/>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
      href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
    <memory_policy>
        <overcommit percent="100"/>
        <transparent_hugepages>
            <enabled>false</enabled>
        </transparent_hugepages>
    </memory_policy>
    <scheduling_policies>
      <policy>evenly_distributed</policy>
      <thresholds low="10" high="75" duration="120"/>
    </scheduling_policies>
    <version minor="0" major="3"/>
    <supported_versions>
        <version minor="0" major="3"/>
    </supported_versions>
    <error_handling>
        <on_error>migrate</on_error>
    </error_handling>
</cluster>

Creation of a new cluster requires the name, cpu id= and datacenter elements. Identify the datacenter with either the id attribute or name element. See Section 7.2.4, “ Creating a Resource in a Collection ” for more information.

Example 9.2. Creating a host cluster

POST /api/clusters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <name>cluster1</name>
    <cpu id="Intel Penryn Family"/>
    <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"/>
</cluster>

The name, description, cpu id= and error_handling elements are updatable post-creation. See Section 7.3.2, “ Updating a Resource ” for more information.

Example 9.3. Updating a host cluster

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <description>Cluster 1</description>
</cluster>

Removal of a cluster requires a DELETE request.

Example 9.4. Removing a cluster

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1

HTTP/1.1 204 No Content

9.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 with an additional cluster id= to signify a relationship to the cluster and a display element to represent the display network status in the cluster.
An API user manipulates the networks sub-collection as described in Chapter 7, Common Features. POSTing a network id or name reference to the networks sub-collection associates the network with the cluster.

Example 9.5. Associating a network resource with a cluster

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <name>rhevm</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="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
  da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>rhevm</name>
    <status>
        <state>operational</state>
    </status>
    <description>Display Network</description>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <display>true</display>
</network>

The display network status is set using a PUT request to specify the Boolean value (true or false) of the display element.

Example 9.6. Setting the display network status

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <display>false</display>
</network>

An association is removed with a DELETE request to the appropriate element in the collection.

Example 9.7. Removing a network association from a cluster

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1

HTTP/1.1 204 No Content