Managed Object - ResourcePool

Property of: ComputeResource, ResourcePool, ResourcePoolEventArgument, VirtualMachine, VirtualMachineRelocateSpec
Parameter to: AddHost_Task, CreateVM_Task, MarkAsVirtualMachine, MigrateVM_Task, MoveHostInto_Task, RecommendHostsForVm, RegisterVM_Task, ValidateMigration
Returned by: CreateResourcePool
Extends: ManagedEntity
See also: ComputeResource, ManagedEntity, ResourceConfigSpec, ResourcePoolRuntimeInfo, ResourcePoolSummary, VirtualMachine

Managed Object Description

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 remain consistent. This means that nodes whos parents all are 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.

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.

Properties

Name	Type	Description
childConfiguration*	ResourceConfigSpec[]	The resource configuration of all direct children (VirtualMachine and ResourcePool) of this resource group.
config	ResourceConfigSpec	Configuration of this resource pool.
owner P	ManagedObjectReference to a ComputeResource	The ComputeResource to which this set of one or more nested resource pools belong.
resourcePool* P	ManagedObjectReference[] to a ResourcePool[]	The set of child resource pools.
runtime	ResourcePoolRuntimeInfo	Runtime information about a resource pool.
summary	ResourcePoolSummary	Basic information about a resource pool.
vm* P	ManagedObjectReference[] to a VirtualMachine[]	The set of virtual machines associated with this resource pool.
Properties inherited from ManagedEntity
configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, triggeredAlarmState

*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
CreateResourcePool, DestroyChildren, MoveIntoResourcePool, UpdateChildResourceConfiguration, UpdateConfig
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task

CreateResourcePool

Creates a new resource pool.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

Required Privileges: Resource.CreatePool

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ResourcePool used to make the method call.
name	xsd:string
spec	ResourceConfigSpec

Return Value

Type	Description
ManagedObjectReference to a ResourcePool

Faults

Type	Description
DuplicateName	Thrown if this pool already contains an object with the given name.
InsufficientResourcesFault	Thrown if the opertaion would violate a resource usage policy. Typically, a more specific subclass, such as InsufficientCpuResourcesFault will be thrown.
InvalidArgument	Thrown if the pool specification is invalid.
InvalidName	Thrown if the name is not a valid entity name.
NotSupported	Thrown if the ComputeResource does not support nested resource pools.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="CreateResourcePool">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="name" type="xsd:string"/>
                  <element name="spec" type="vim2:ResourceConfigSpec"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="CreateResourcePoolResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

DestroyChildren

Removes all child resource pools recursively. All virtual machines associated with the child resource pools are associated with this group. The Resource.DeletePool privilege must be held on this object and each of it's immediate children to be destroyed. The Resource.AssignVMToPool privilege must be held on this resource pool as well as on the virtual machine.

Required Privileges: Dynamic - See discussion above

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ResourcePool used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="DestroyChildren">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="DestroyChildrenResponse">
            <complexType/>
         </element>

MoveIntoResourcePool

Moves a set of resource pools or virtual machines into this pool. The pools and virtual machines must be part of the cluster or standalone host that contains this pool.

The move is subject to the following privilege checks. If the object being moved is a ResourcePool, then Resource.MovePool must be held on the pool being moved, its former parent pool, and the target pool. If the object is a VirtualMachine, then Resource.AssignVMToPool must be held on the target pool and the virtual machine.

This operation is typically used by clients when they implement a drag-and-drop interface to move a set of objects into a folder.

This operation is only transactional with respect to each individual entity. The set of entities is moved sequentially, as specified in the list, and committed one at a time. If a failure is detected, then the method terminates with an exception.

The root resource pool cannot be moved.

Required Privileges: Dynamic - See discussion above

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ResourcePool used to make the method call.
list	ManagedObjectReference[] to a ManagedEntity[]	A list of ResourcePool and VirtualMachine objects.

Return Value

Type	Description
None

Faults

Type	Description
DuplicateName	Thrown if this pool already contains an object with the given name.
InsufficientResourcesFault	Thrown if the move would violate the resource usage policy. Typically, a more specific subclass, such as InsufficientMemoryResourcesFault.
InvalidArgument	Thrown if an ancestor of this pool is in the list.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="MoveIntoResourcePool">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="list" type="vim2:ManagedObjectReference" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="MoveIntoResourcePoolResponse">
            <complexType/>
         </element>

UpdateChildResourceConfiguration

Changes resource configuration of a set of children of this resource pool. The method allows bulk modifications of the set of the direct children (virtual machines and resource pools).

Bulk modifications are not transactional. Each modification is made individually. If a failure is encountered while applying the changes, then the processing stops, meaning at least one and as many as all of the changes are not applied.

A set can include a subset of the resources. Children that are not mentioned in the list are not changed.

For each ResourceConfigSpec, the following privilege checks apply:

If the ResourceConfigSpec refers to a child resource pool, Resource.EditPool must be held on the resource pool as well as it's parent (this object).
If the ResourceConfigSpec refers to a virtual machine, VirtualMachine.Config.Resource must be held on the virtual machine.

Required Privileges: Dynamic - See discussion above

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ResourcePool used to make the method call.
spec	ResourceConfigSpec[]

Return Value

Type	Description
None

Faults

Type	Description
InsufficientResourcesFault	Thrown if the opertaion would violate a resource usage policy. Typically, a more specific subclass, such as InsufficientMemoryResourcesFault will be thrown.
InvalidArgument	Thrown if a managed entity that is not a child of this group is included.
InvalidState
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdateChildResourceConfiguration">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="spec" type="vim2:ResourceConfigSpec" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdateChildResourceConfigurationResponse">
            <complexType/>
         </element>

UpdateConfig

Updates the configuration of the resource pool.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

NOTE: The Resource.EditPool privilege must be held on the owner of this resource pool in order to change it's configuration.

Required Privileges: Resource.EditPool

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ResourcePool used to make the method call.
name*	xsd:string	If set, then the new name of the resource pool.
config*	ResourceConfigSpec	If set, then the new resource allocation for this resource pool.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
ConcurrentAccess	Thrown if the changeVersion does not match the server's changeVersion for the configuration.
DuplicateName	Thrown if the name is changed to an already existing name.
InsufficientResourcesFault	Thrown if the pool specification cannot be supported by the parent resource pool.
InvalidArgument	Thrown if the parameters are out of range.
InvalidName	Thrown if the name is not a valid entity name.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdateConfig">
            <complexType>
               <sequence>
                  <element name="_this" type="vim2:ManagedObjectReference"/>
                  <element name="name" type="xsd:string" minOccurs="0"/>
                  <element name="config" type="vim2:ResourceConfigSpec" minOccurs="0"/>
               </sequence>
            </complexType>
         </element>
         <element xmlns="http://www.w3.org/2001/XMLSchema" name="UpdateConfigResponse">
            <complexType/>
         </element>