| Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |
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:
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.
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.
Properties
Name | Type | Description |
---|---|---|
childConfiguration* | ResourceConfigSpec[] |
The resource configuration of all direct children (VirtualMachine and
ResourcePool) of this resource group.
Property collector update notifications might not be generated for this
property. To listen for the child configuration change, please create
PropertyCollector filter on the child entities directly.
|
config | ResourceConfigSpec |
Configuration of this resource pool.
|
namespace* P | xsd:string |
The namespace with which the ResourcePool is associated. Namespace is a
vAPI resource which divides cluster resources and allows administrators
to give Kubernetes environments to their development teams.
This property is set only at the time of creation and cannot change.
Since vSphere API 7.0 |
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.
The ResourcePoolResourceUsage information within
ResourcePoolRuntimeInfo can be transiently stale.
Use RefreshRuntime method to
update the information.
In releases after vSphere API 5.0, vSphere Servers might not
generate property collector update notifications for this property.
To obtain the latest value of the property, you can use
PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx.
If you use the PropertyCollector.WaitForUpdatesEx method, specify
an empty string for the version parameter. Any other version value will not
produce any property values as no updates are generated.
|
summary | ResourcePoolSummary |
Basic information about a resource pool.
In releases after vSphere API 5.0, vSphere Servers might not
generate property collector update notifications for this property.
To obtain the latest value of the property, you can use
PropertyCollector methods RetrievePropertiesEx or WaitForUpdatesEx.
If you use the PropertyCollector.WaitForUpdatesEx method, specify
an empty string for the version parameter. Any other version value will not
produce any property values as no updates are generated.
|
vm* P | ManagedObjectReference[]
to a VirtualMachine[] |
The set of virtual machines associated with this resource pool.
|
Properties inherited from ManagedEntity | ||
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState | ||
Properties inherited from ExtensibleManagedObject | ||
availableField, value |
Methods
Methods defined in this Managed Object |
---|
CreateChildVM_Task, CreateResourcePool, CreateVApp, DestroyChildren, ImportVApp, MoveIntoResourcePool, QueryResourceConfigOption, RefreshRuntime, RegisterChildVM_Task, UpdateChildResourceConfiguration, UpdateConfig |
Methods inherited from ManagedEntity |
Destroy_Task, Reload, Rename_Task |
Methods inherited from ExtensibleManagedObject |
setCustomValue |
This method supports creating a virtual machine directly in a vApp. A virtual machine in a vApp is not associated with a VM folder and therefore cannot be created using the method on a CreateVM_Task.
This method can only be called directly on a vApp or on a resource pool that is a child of a vApp.
The privilege VirtualMachine.Inventory.Create is required on this entity. Further, if this is a resource pool, the privilege Resource.AssignVMToPool is required. If this is a vApp, the privilege VApp.AssignVM is required.
Depending on the properties of the virtual machine bring created, additional privileges may be required. See CreateVM_Task for a description of these privileges.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
config P | VirtualMachineConfigSpec |
The configuration of the virtual machine hardware.
Since vSphere API 4.0 |
host* P | ManagedObjectReference
to a HostSystem |
The target host on which the virtual machine will run. This must
specify a host that is a member of the ComputeResource indirectly
specified by the pool. For a stand-alone host or a cluster with DRS,
host can be omitted, and the system selects a default.
Since vSphere API 4.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly created VirtualMachine upon success. |
Faults
Type | Description |
---|---|
FileAlreadyExists | Thrown if the requested cfgPath for the virtual machine's configuration file already exists. |
FileFault | Thrown if there is a problem creating the virtual machine on disk. Typically, a more specific subclass, such as NoDiskSpace, will be thrown. |
InsufficientResourcesFault | Thrown if this operation would violate a resource usage policy. |
InvalidDatastore | Thrown if the operation cannot be performed on the target datastores. |
InvalidName | Thrown if the name is not a valid entity name. |
OutOfBounds | Thrown if Host.capability.maxSupportedVMs is exceeded. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmConfigFault | Thrown if the configSpec has incorrect values. Typically, a more specific subclass is thrown. |
VmWwnConflict | Thrown if the WWN of the virtual machine has been used by other virtual machines. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
name P | xsd:string |
The name of the ResourcePool. Any % (percent) character
used in this parameter must be escaped, unless it is used
to start an escape sequence. Clients may also escape any
other characters in this parameter.
Since 2.0 |
spec P | ResourceConfigSpec |
The spec for the ResourcePool.
All values in ResourceAllocationInfo must be specified and
are not optional.
Since 2.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a ResourcePool | A reference to the new resource pool. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if this pool already contains an object with the given name. |
InsufficientResourcesFault | Thrown if the operation would violate a resource usage policy. Typically, a more specific subclass, such as InsufficientCpuResourcesFault will be thrown. |
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. |
Events
Type | |
---|---|
None |
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
name P | xsd:string |
The name of the vApp container in the inventory
Since vSphere API 4.0 |
resSpec P | ResourceConfigSpec |
The resource configuration for the vApp container (same as for a
regular resource pool).
Since vSphere API 4.0 |
configSpec P | VAppConfigSpec |
The specification of the vApp specific meta-data.
Since vSphere API 4.0 |
vmFolder* P | ManagedObjectReference
to a Folder |
The parent folder for the vApp. This must be null if this is
a child vApp.
Since vSphere API 4.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a VirtualApp | The created vApp object. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if this pool already contains an object with the given name. |
InsufficientResourcesFault | Thrown if the operation would violate a resource usage policy. Typically, a more specific subclass, such as InsufficientCpuResourcesFault will be thrown. |
InvalidName | Thrown if the name is not a valid entity name. |
InvalidState | Thrown if the resource pool does not support the operation in its current state. This will typically be a subclass such as NoActiveHostInCluster. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmConfigFault | or a more specific subclass, if errors are found in the supplied in VApp configuration. |
Events
Type | |
---|---|
None |
Note that resource pools contained in child vApps are not affected.
The privilege checks performed are the following.
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. |
Events
Type | |
---|---|
None |
In step 2, the client uploads disk contents using the URLs provided in the Info property of the lease. The client must call HttpNfcLeaseProgress on the lease periodically to keep the lease alive and report progress to the server. Failure to do so will cause the lease to time out, and the import process will be aborted.
When the client is done uploading disks, it completes the lease by calling HttpNfcLeaseComplete. The client can also abort the import process by calling HttpNfcLeaseAbort.
If the import process fails, is aborted, or times out, all created inventory objects are removed, including all virtual disks.
This operation only works if the folder's childType includes VirtualMachine.
Depending on the properties of the virtual machine bring imported, additional privileges may be required. See CreateVM_Task for a description of these privileges.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
spec P | ImportSpec |
An ImportSpec describing what to import.
Since vSphere API 4.0 |
folder* P | ManagedObjectReference
to a Folder |
The folder to which the entity will be attached.
Since vSphere API 4.0 |
host* P | ManagedObjectReference
to a HostSystem |
The target host on which the entity will run. This must
specify a host that is a member of the ComputeResource indirectly
specified by the pool. For a stand-alone host or a cluster with DRS,
host can be omitted, and the system selects a default.
Since vSphere API 4.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a HttpNfcLease | A HttpNfcLease object which is used to drive the import session. |
Faults
Type | Description |
---|---|
DuplicateName | Thrown if another virtual machine in the same folder already has the specified target name. |
FileAlreadyExists | Thrown if the requested cfgPath for the virtual machine's configuration file already exists. |
FileFault | Thrown if there is a problem creating the virtual machine on disk. Typically, a more specific subclass, such as NoDiskSpace, will be thrown. |
InsufficientResourcesFault | Thrown if this operation would violate a resource usage policy. |
InvalidDatastore | Thrown if the operation cannot be performed on the target datastores. |
InvalidName | Thrown if the name is not a valid entity name. |
OutOfBounds | Thrown if Host.capability.maxSupportedVMs is exceeded. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmConfigFault | Thrown if a VM configSpec has incorrect values. Typically, a more specific subclass is thrown. |
VmWwnConflict | Thrown if the WWN of the virtual machine has been used by other virtual machines. |
Events
Type | |
---|---|
None |
For each entity being moved, the move is subject to the following privilege checks:
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.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
list P | ManagedObjectReference[]
to a ManagedEntity[] |
A list of ResourcePool and VirtualMachine objects.
Since 2.0 |
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. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
Return Value
Type | Description |
---|---|
ResourceConfigOption | ResourceConfigOption object. |
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. |
Events
Type | |
---|---|
None |
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. |
Events
Type | |
---|---|
None |
This operation only works for vApps or resource pools that are children of vApps. To register a VM in a folder, see RegisterVM_Task.
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. In addition to the VirtualMachine.Inventory.Register privilege, it requires System.Read privilege on the datastore that the existing virtual machine resides on.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
path P | xsd:string |
A datastore path to the virtual machine. If the path ends with
".vmtx", indicating that it refers to a VM template, an InvalidArgument
fault is thrown.
Since vSphere API 4.0 |
name* P | xsd:string |
The name to be assigned to the virtual machine. If this parameter is
not set, the displayName configuration parameter of the virtual machine is
used. An entity name must be a non-empty string of less than 80
characters. The slash (/), backslash (\) and percent (%) will be
escaped using the URL syntax. For example, %2F.
Since vSphere API 4.0 |
host* P | ManagedObjectReference
to a HostSystem |
The target host on which the virtual machine will run. This parameter
must specify a host that is a member of the ComputeResource to which this
resource pool belongs. For a stand-alone host or a cluster with DRS,
the parameter can be omitted, and the system selects a default.
Since vSphere API 4.0 |
Return Value
Type | Description |
---|---|
ManagedObjectReference
to a Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains the newly registered VirtualMachine upon success. |
Faults
Type | Description |
---|---|
AlreadyExists | Thrown if the virtual machine is already registered. |
FileFault | Thrown if there is an error accessing the files on disk. |
InsufficientResourcesFault | Thrown if this operation would violate a resource usage policy. |
InvalidDatastore | Thrown if the operation cannot be performed on the target datastores. |
InvalidName | Thrown if the entity name is invalid. |
NotFound | Thrown if the configuration file is not found on the system. |
OutOfBounds | Thrown if the maximum number of VMs has been exceeded. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
VmConfigFault | Thrown if the format / configuration of the virtual machine is invalid. Typically, a more specific fault is thrown such as InvalidFormat if the configuration file cannot be read, or InvalidDiskFormat if the disks cannot be read. |
Events
Type | |
---|---|
None |
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:
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
spec P | ResourceConfigSpec[] |
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
InsufficientResourcesFault | Thrown if the operation would violate a resource usage policy. Typically, a more specific subclass, such as InsufficientMemoryResourcesFault will be thrown. |
InvalidState | |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
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.
The privilege checks for this operation are as follows:
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the ResourcePool used to make the method call. |
name* P | xsd:string |
If set, then the new name of the resource pool.
Since 2.0 |
config* P | ResourceConfigSpec |
If set, then the new resource allocation for this
resource pool.
Since 2.0 |
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 or vApp. |
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. |
Events
Type | |
---|---|
None |
Top of page | Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |