Product SiteDocumentation Site

Chapter 10. Host Clusters

10.1. Networks Sub-Collection
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.

Element property icons

The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Element Type Description Properties
name string A user-supplied human readable name for the cluster. The name is unique across all cluster resources.
description string A free-form user-supplied human readable description of the cluster
link rel="networks" string A link to the sub-collection for networks associated with this cluster
link rel="permissions" string A link to the sub-collection for cluster permissions. See Section 8.3.9, “ Permissions ”
cpu complex A server CPU reference that defines the CPU type all hosts must support in the cluster. See Section 7.1.3, “CPUs”
data_center id complex A reference to the data center membership of this cluster. See Chapter 9, Data Centers
memory_policy complex Defines the cluster's policy on host memory utilization. See below.
scheduling_policy complex Defines the load-balancing or power sharing modes for hosts in the cluster. See below.
version complex The compatibility level of the cluster (see Chapter 6, Compatibility Level Versions)
supported_versions complex A list of possible version levels for the cluster. See Chapter 6, 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 7.1.18, “Error Handling”
The memory_policy element can contain the following specific elements:
Element Type Description Properties
overcommit 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 ) to ensure your version supports transparent hugepages.
The scheduling_policy element can contain the following specific 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 7.3, “Scheduling Policies”
thresholds 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 10.1. An XML representation of a host cluster
<clusters>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
        <name>Default</name>
        <description>The default server cluster</description>
        <link rel="networks"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
        <link rel="permissions"
          href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
        <cpu id="Intel Penryn Family"/>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/rhevm-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>
</clusters>

When creating a new cluster, the name, cpu id and datacenter properties are required. The datacenter is identified with either name or id. See Section 8.3.2, “ Creating a Resource ” for more information.
Example 10.2. Creating a host cluster
POST /rhevm-api/cluster 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 and cpu id elements are updatable post-creation. See Section 8.3.4, “ Updating a Resource ” for more information.
Example 10.3. Updating a host cluster
PUT /rhevm-api/cluster/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1
Accept: application/xml
Content-type: application/xml

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

10.1.  Networks Sub-Collection

Networks are associated with clusters and are represented with the networks sub-collection. Every host within the cluster must have a network interface attached to that network in order for the network to be operational.
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.
An API user manipulates the networks sub-collection as described in Chapter 8, Common Features. POSTing a network id or name reference to the networks sub-collection associates the network with the cluster.
Example 10.4. Associating a network resource with a cluster
POST /rhevm-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="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
  da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>rhevm</name>
    <status>OPERATIONAL</status>
    <description>Display Network</description>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/rhevm-api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
</network>

An association is removed with a DELETE request to the appropriate element in the collection.
Example 10.5. Removing an network association to a cluster
DELETE /rhevm-api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1

HTTP/1.1 204 No Content