Resource Pool APIs

Resource Pool APIs

Represents a set of physical resources: a single host, a subset of a host's resources, or resources spanning multiple hosts.

Resource pools can be subdivided by creating child resource pools. In order to run, a virtual machine must be associated as a child of a resource pool.

In a parent/child hierarchy of resource pools and virtual machines, the single resource pool that has no parent pool is known as the root resource pool.

Configuration

A resource pool is configured with a set of CPU (in MHz) and memory (in MB) resources. These resources are specified in absolute terms with a resource reservation and a resource limit, along with a shares setting. The shares are used during resource contention, to ensure graceful degradation.

For the root resource pool, the values of the reservation and the limit are set by the system and are not configurable. The reservation and limit are set to the same value, indicating the total amount of resources the system has available to run virtual machines. This is computed as the aggregated CPU and memory resources provided by the set of current available hosts in the parent compute resource minus the overhead of the virtualization layer.

Since the resource pool configuration is absolute (in MHz or MB), the configuration can become invalid when resources are removed. This can happen if a host is removed from the cluster, if a host becomes unavailable, or if a host is placed in maintenance mode. When this happens, the system flags misconfigured resource pools and displays the reservations and limits that are in effect. Further, in a DRS enabled cluster, the tree can be misconfigured if the user bypasses VirtualCenter and powers on VMs directly on the host.

A General Discussion of Resource pool states and admission control There are three states that the resource pool tree can be in: undercommited (green), overcommited (yellow), and inconsistent (red). Depending on the state, different resource pool configuration policies are enforced. The states are described in more detail below:

  • GREEN (aka undercommitted): We have a tree that is in a good state. Every node has a reservation greater than the sum of the reservations for its children. We have enough capacity at the root to satisfy all the resources reserved by the children. All operations performed on the tree, such as powering on virtual machines, creating new resource pools, or reconfiguring resource settings, will ensure that the above constraints are maintained.

  • RED (aka. inconsistent): One or more nodes in the tree has children whose reservations are greater than the node is configured to support. For example, i) a resource pool with a fixed reservation has a running virtual machine with a reservation that is higher than the reservation on resource pool itself., or ii) the child reservations are greater than the limit.

    In this state, the DRS algorithm is disabled until the resource pool tree's configuration has been brought back into a consistent state. We also restrict the resources that such invalid nodes request from their parents to the configured reservation/limit, in an attempt to isolate the problem to a small subtree. For the rest of the tree, we determine whether the cluster is undercommitted or overcommitted according to the existing rules and perform admission control accordingly.

    Note that since all changes to the resource settings are validated on the VirtualCenter server, the system cannot be brought into this state by simply manipulating a cluster resource pool tree through VirtualCenter. It can only happen if a virtual machine gets powered on directly on a host that is part of a DRS cluster.

  • YELLOW (aka overcommitted): In this state, the tree is consistent internally, but the root resource pool does not have the capacity at to meet the reservation of its children. We can only go from GREEN -> YELLOW if we lose resources at the root. For example, hosts becomes unavailable or is put into maintenance mode. Note that we will always have enough capacity at the root to run all currently powered on VMs. However, we may not be able to satisfy all resource pool reservations in the tree. In this state, the reservation configured for a resource pool is no longer guaranteed, but the limits are still enforced. This provides additional flexibility for bringing the tree back into a consistent state, without risking bringing the tree into a RED state. In more detail:

    • Resource Pool The root is considered to have unlimited capacity. You can reserve resources without any check except the requirement that the tree remains consistent. This means that nodes whose parents are all configured with expandable reservations and no limit will have unlimited available resources. However, if there is an ancestor with a fixed reservation or an expandable reservation with a limit somewhere, then the node will be limited by the reservation/limit of the ancestor.
    • Virtual Machine Virtual machines are limited by ancestors with a fixed reservation and the capacity at the root.

Destroying a ResourcePool

When a ResourcePool is destroyed, all the virtual machines are reassigned to its parent pool. The root resource pool cannot be destroyed, and invoking destroy on it will throw an InvalidType fault.

Any vApps in the ResourcePool will be moved to the ResourcePool's parent before the pool is destroyed.

The Resource.DeletePool privilege must be held on the pool as well as the parent of the resource pool. Also, the Resource.AssignVMToPool privilege must be held on the resource pool's parent pool and any virtual machines that are reassigned.

Operations
POST
Resource Pool Create Child VM Task
Creates a new virtual machine in a vApp container.
POST
Resource Pool Create Resource Pool
Creates a new resource pool.
POST
Resource Pool Create V App
Creates a new vApp container.
POST
Resource Pool Destroy Task
Destroys this object, deleting its contents and removing it from its parent folder (if any).
POST
Resource Pool Destroy Children
Removes all child resource pools recursively.
GET
Resource Pool Get Alarm Actions Enabled
Whether alarm actions are enabled for this entity.
GET
Resource Pool Get Available Field
List of custom field definitions that are valid for the object's type.
GET
Resource Pool Get Child Configuration
The resource configuration of all direct children (VirtualMachine and ResourcePool) of this resource group.
GET
Resource Pool Get Config
Configuration of this resource pool.
GET
Resource Pool Get Config Issue
Current configuration issues that have been detected for this entity.
GET
Resource Pool Get Config Status
The configStatus indicates whether or not the system has detected a configuration issue involving this entity.
GET
Resource Pool Get Custom Value
Custom field values.
GET
Resource Pool Get Declared Alarm State
A set of alarm states for alarms that apply to this managed entity.
GET
Resource Pool Get Disabled Method
List of operations that are disabled, given the current runtime state of the entity.
GET
Resource Pool Get Effective Role
Access rights the current session has to this entity.
GET
Resource Pool Get Name
Name of this entity, unique relative to its parent.
GET
Resource Pool Get Namespace
The namespace with which the ResourcePool is associated.
GET
Resource Pool Get Overall Status
General health of this managed entity.
GET
Resource Pool Get Owner
The ComputeResource to which this set of one or more nested resource pools belong.
GET
Resource Pool Get Parent
Parent of this entity.
GET
Resource Pool Get Permission
List of permissions defined for this entity.
GET
Resource Pool Get Recent Task
The set of recent tasks operating on this managed entity.
GET
Resource Pool Get Resource Pool
The set of child resource pools.
GET
Resource Pool Get Runtime
Runtime information about a resource pool.
GET
Resource Pool Get Summary
Basic information about a resource pool.
GET
Resource Pool Get Tag
The set of tags associated with this managed entity.
GET
Resource Pool Get Triggered Alarm State
A set of alarm states for alarms triggered by this entity or by its descendants.
GET
Resource Pool Get Value
List of custom field values.
GET
Resource Pool Get Vm
The set of virtual machines associated with this resource pool.
POST
Resource Pool Import V App
Creates a new entity in this resource pool.
POST
Resource Pool Move Into Resource Pool
Moves a set of resource pools, vApps or virtual machines into this pool.
POST
Resource Pool Query Resource Config Option
Get a value range and default values for *ResourceConfigSpec*.
POST
Resource Pool Refresh Runtime
Refreshes the resource usage data that is available in *ResourcePoolRuntimeInfo*.
POST
Resource Pool Register Child VM Task
Adds an existing virtual machine to this resource pool or vApp.
POST
Resource Pool Reload
Reload the entity state.
POST
Resource Pool Rename Task
Renames this managed entity.
POST
Resource Pool Set Custom Value
Assigns a value to a custom field.
POST
Resource Pool Update Child Resource Configuration
Changes resource configuration of a set of children of this resource pool.
POST
Resource Pool Update Config
Updates the configuration of the resource pool.