Scripting Object - VcResourcePool

Scripting-object corresponding to
ResourcePool
Attribute of
_VcPlugin, VcClusterComputeResource, VcClusterInitialPlacementAction, VcComputeResource, VcOvfResourceMap, VcResourcePool, VcResourcePoolEventArgument, VcSdkConnection, VcStoragePlacementSpec, VcVAppCloneSpecResourceMap, VcVirtualApp, VcVirtualMachine, VcVirtualMachineImportSpec, VcVirtualMachineRelocateSpec
Parameter to
addHost_Task, checkCompatibility_Task, checkMigrate_Task, cloneVApp_Task, createImportSpec, createVM_Task, createVM_Task, getRPSettings, markAsVirtualMachine, migrateVM_Task, moveHostInto_Task, recommendHostsForVm, registerVM_Task, registerVM_Task
Returned by
createResourcePool, createResourcePool, getAllResourcePools, getAllResourcePools, getChildRPforHub

Scripting 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:

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.

Attributes

Name Type Description
alarmActionsEnabled*boolean

Whether alarm actions are enabled for this entity. True if enabled; false otherwise.
availableField*VcCustomFieldDef []

List of custom field definitions that are valid for the object's type. The fields are sorted by VcCustomFieldDef.
childConfiguration*VcResourceConfigSpec []

The resource configuration of all direct children (VirtualMachine and ResourcePool) of this resource group.
configVcResourceConfigSpec

Configuration of this resource pool.
configIssue*VcEvent []

Current configuration issues that have been detected for this entity. Typically, these issues have already been logged as events. The entity stores these events as long as they are still current. The VcManagedEntity property provides an overall status based on these events.
configStatusVcManagedEntityStatus

The configStatus indicates whether or not the system has detected a configuration issue involving this entity. For example, it might have detected a duplicate IP address or MAC address, or a host in a cluster might be out of compliance. The meanings of the configStatus values are:
  • red: A problem has been detected involving the entity.
  • yellow: A problem is about to occur or a transient condition has occurred (For example, reconfigure fail-over policy).
  • green: No configuration issues have been detected.
  • gray: The configuration status of the entity is not being monitored.
A green status indicates only that a problem has not been detected; it is not a guarantee that the entity is problem-free.

The VcManagedEntity property contains a list of the problems that have been detected. 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.

customValue*VcCustomFieldValue []

Custom field values.
declaredAlarmState*VcAlarmState []

A set of alarm states for alarms that apply to this managed entity. The set includes alarms defined on this entity and alarms inherited from the parent entity, or from any ancestors in the inventory hierarchy.

Alarms are inherited if they can be triggered by this entity or its descendants. This set does not include alarms that are defined on descendants of this entity.

disabledMethod*string []

List of operations that are disabled, given the current runtime state of the entity. For example, a power-on operation always fails if a virtual machine is already powered on. This list can be used by clients to enable or disable operations in a graphical user interface.

Note: This list is determined by the current runtime state of an entity, not by its permissions.

This list may include the following operations for a HostSystem:

This list may include the following operations for a VirtualMachine:

This list may include the following operations for a ResourcePool:

This list may include the following operations for a VirtualApp:

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.

effectiveRole*number []

Access rights the current session has to this entity.
idstring

returns the id of this ManagedObject
namestring

Name of this entity, unique relative to its parent.

Any / (slash), \ (backslash), character used in this name element will be escaped. Similarly, any % (percent) character used in this name element will be escaped, unless it is used to start an escape sequence. A slash is escaped as %2F or %2f. A backslash is escaped as %5C or %5c, and a percent is escaped as %25.

overallStatusVcManagedEntityStatus

General health of this managed entity. The overall status of the managed entity is computed as the worst status among its alarms and the configuration issues detected on the entity. The status is reported as one of the following values:
  • red: The entity has alarms or configuration issues with a red status.
  • yellow: The entity does not have alarms or configuration issues with a red status, and has at least one with a yellow status.
  • green: The entity does not have alarms or configuration issues with a red or yellow status, and has at least one with a green status.
  • gray: All of the entity's alarms have a gray status and the configuration status of the entity is not being monitored.
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.
ownerVcComputeResource

The ComputeResource to which this set of one or more nested resource pools belong.
parent*VcManagedEntity

Parent of this entity.

This value is null for the root object and for VcVirtualMachine objects that are part of a VcVirtualApp.

permission*VcPermission []

List of permissions defined for this entity.
recentTask*VcTask []

The set of recent tasks operating on this managed entity. This is a subset of VcTaskManager belong to this entity. A task in this list could be in one of the four states: pending, running, success or error.

This property can be used to deduce intermediate power states for a virtual machine entity. For example, if the current powerState is "poweredOn" and there is a running task performing the "suspend" operation, then the virtual machine's intermediate state might be described as "suspending."

Most tasks (such as power operations) obtain exclusive access to the virtual machine, so it is unusual for this list to contain more than one running task. One exception, however, is the task of cloning a virtual machine. 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.

referenceVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject
resourcePool*VcResourcePool []

The set of child resource pools.
resourcePool_ResourcePoolResourcePool []

Filtered attribute 'resourcePool' with only ResourcePool objects
resourcePool_VirtualAppVirtualApp []

Filtered attribute 'resourcePool' with only VirtualApp objects
runtimeVcResourcePoolRuntimeInfo

Runtime information about a resource pool. The VcResourcePoolResourceUsage information within VcResourcePoolRuntimeInfo can be transiently stale. Use VcResourcePool 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.
sdkConnectionVcSdkConnection

returns the parent SdkConnection
summaryVcResourcePoolSummary

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.
tag*VcTag []

The set of tags associated with this managed entity. Experimental. Subject to change.
triggeredAlarmState*VcAlarmState []

A set of alarm states for alarms triggered by this entity or by its descendants.

Triggered alarms are propagated up the inventory hierarchy so that a user can readily tell when a descendant has triggered an alarm. 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.

value*VcCustomFieldValue []

List of custom field values. Each value uses a key to associate an instance of a VcCustomFieldStringValue with a custom field definition.
vimHostVcSdkConnection

returns the parent SdkConnection (deprecated)
vimTypestring

returns the type of this ManagedObject
vm*VcVirtualMachine []

The set of virtual machines associated with this resource pool.
*May not be present

Methods

Methods defined in this Scripting Object
createChildVM_Task, createResourcePool, createTrigger, createVApp, destroy_Task, destroyChildren, importVApp, moveIntoResourcePool, queryResourceConfigOption, refreshRuntime, registerChildVM_Task, reload, rename_Task, setCustomValue, updateChildResourceConfiguration, updateConfig

reload

Reload the entity state. Clients only need to call this method if they changed some external state that affects the service without using the Web service interface to perform the change. For example, hand-editing a virtual machine configuration file affects the configuration of the associated virtual machine but the service managing the virtual machine might not monitor the file for changes. In this case, after such an edit, a client would call "reload" on the associated virtual machine to ensure the service and its clients have current data for the virtual machine.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

rename_Task

Renames this managed entity.

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.


See VcManagedEntity

Parameters

NameTypeDescription
newNamestring


See VcManagedEntity

Return Value

Type Description
VcTask

destroy_Task

Destroys this object, deleting its contents and removing it from its parent folder (if any).

NOTE: The appropriate privilege must be held on the parent of the destroyed entity as well as the entity itself.

This method can throw one of several exceptions. The exact set of exceptions depends on the kind of entity that is being removed. See comments for each entity for more information on destroy behavior.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

setCustomValue

Assigns a value to a custom field. The setCustomValue method requires whichever updatePrivilege is defined as one of the VcCustomFieldDef for the CustomFieldDef whose value is being changed.

Parameters

NameTypeDescription
keystring

The name of the field whose value is to be updated.
valuestring

Value to be assigned to the custom field.

Return Value

Type Description
None

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.

The privilege checks for this operation are as follows:

Parameters

NameTypeDescription
name*string

If set, then the new name of the resource pool.
config*VcResourceConfigSpec

If set, then the new resource allocation for this resource pool.
*Need not be set

Return Value

Type Description
None

moveIntoResourcePool

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

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

NameTypeDescription
listVcManagedEntity []

A list of ResourcePool and VirtualMachine objects.

Return Value

Type Description
None

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:

Parameters

NameTypeDescription
specVcResourceConfigSpec []


Return Value

Type Description
None

createResourcePool

Creates a new resource pool.

In the ResourceConfigSpec, all values in ResourceAllocationInfo must be supplied; they are not optional.

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

NameTypeDescription
namestring

specVcResourceConfigSpec


Return Value

Type Description
VcResourcePool

destroyChildren

Removes all child resource pools recursively. All virtual machines and vApps associated with the child resource pools get associated with this resource pool.

Note that resource pools contained in child vApps are not affected.

The privilege checks performed are the following.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createVApp

Creates a new vApp container.

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

NameTypeDescription
namestring

The name of the vApp container in the inventory
resSpecVcResourceConfigSpec

The resource configuration for the vApp container (same as for a regular resource pool).
configSpecVcVAppConfigSpec

The specification of the vApp specific meta-data.
vmFolder*VcFolder

The parent folder for the vApp. This must be null if this is a child vApp.
*Need not be set

Return Value

Type Description
VcVirtualApp

createChildVM_Task

Creates a new virtual machine in a vApp container.

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 VcFolder.

This method can only be called directly on a VcVirtualApp 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 VcFolder for a description of these privileges.

Parameters

NameTypeDescription
configVcVirtualMachineConfigSpec

The configuration of the virtual machine hardware.
host*VcHostSystem

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.
*Need not be set

Return Value

Type Description
VcTask

registerChildVM_Task

Adds an existing virtual machine to this resource pool or vApp.

This operation only works for vApps or resource pools that are children of vApps. To register a VM in a folder, see VcFolder.

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

NameTypeDescription
pathstring

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.
name*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.
host*VcHostSystem

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.
*Need not be set

Return Value

Type Description
VcTask

importVApp

Creates a new entity in this resource pool. The import process consists of two steps:
  1. Create the VMs and/or vApps that make up the entity.
  2. Upload virtual disk contents.
In step 1, the client must wait for the server to create all inventory objects. It does that by monitoring the VcHttpNfcLease property on the VcHttpNfcLease object returned from this call. When the server is done creating objects, the lease will change to the ready state, and step 2 begins. If an error occurs while the server is creating inventory objects, the lease will change to the error state, and the import process is aborted.

In step 2, the client uploads disk contents using the URLs provided in the VcHttpNfcLease property of the lease. The client must call VcHttpNfcLease 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 VcHttpNfcLease. The client can also abort the import process by calling VcHttpNfcLease.

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 VcFolder for a description of these privileges.

Parameters

NameTypeDescription
specVcImportSpec

An VcImportSpec describing what to import.
folder*VcFolder

The folder to which the entity will be attached.
host*VcHostSystem

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.
*Need not be set

Return Value

Type Description
VcHttpNfcLease

queryResourceConfigOption

Get a value range and default values for VcResourceConfigSpec.

Parameters

NameTypeDescription
None

Return Value

Type Description
VcResourceConfigOption

refreshRuntime

Refreshes the resource usage data that is available in VcResourcePoolRuntimeInfo. The latest runtime resource usage of this resource pool may not be available immediately after operations that alter resource usage, such as powering on a virtual machine. Invoke this method when resource usage may have recently changed, and the most up-to-date value in the VcResourcePoolRuntimeInfo is needed.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createTrigger

Create a trigger from this ManagedObject

Parameters

NameTypeDescription
timeoutnumber

Waiting timout in seconds
filterstring

The monitored vCenter API filter
conditionstring

The condition in OGNL language
filterToSync*string

The vCenter API filter used to synchronize the content of the session
*Need not be set

Return Value

Type Description
Trigger