Scripting Object - VcResourcePool

Scripting-object corresponding to
ResourcePool
Attribute of
VcClusterComputeResource, VcClusterInitialPlacementAction, VcComputeResource, VcContext, VcNodeDeploymentSpec, VcOvfResourceMap, VcPassiveNodeDeploymentSpec, VcResourcePool, VcResourcePoolEventArgument, VcStoragePlacementSpec, VcVAppCloneSpecResourceMap, VcVirtualApp, VcVirtualMachine, VcVirtualMachineImportSpec, VcVirtualMachineInstantCloneSpec, VcVirtualMachineRelocateSpec
Parameter to
addHost_Task, addHostWithAdminDisabled_Task, checkCompatibility_Task, checkMigrate_Task, cloneVApp_Task, createImportSpec, createVM_Task, createVM_Task, createVM_Task, createVM_Task, createVM_Task, createVM_Task, createVM_Task, getRPSettings, importOvfAtUrl_Task, markAsVirtualMachine, migrateVM_Task, moveHostInto_Task, prepareDestination, prepareDestinationEx_Task, recommendHostsForVm, registerVM_Task, registerVM_Task, registerVM_Task, registerVM_Task, registerVM_Task, registerVM_Task, registerVM_Task, validateMigration
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
alarmActionsEnabledBoolean

@since vSphere API 4.0
availableFieldVcCustomFieldDef []

@since VI API 2.5
childConfigurationVcResourceConfigSpec []

@since VI API 2.5
configVcResourceConfigSpec

@since VI API 2.5
configIssueVcEvent []

@since VI API 2.5
configStatusVcManagedEntityStatus

@since VI API 2.5
cpuReservationString

@since Unknown
customValueVcCustomFieldValue []

@since VI API 2.5
declaredAlarmStateVcAlarmState []

@since VI API 2.5
disabledMethodString []

@since VI API 2.5
effectiveRoleNumber []

@since VI API 2.5
idString

@since Unknown
memoryReservationString

@since Unknown
morefVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject @since Unknown
nameString

@since VI API 2.5
overallStatusVcManagedEntityStatus

@since VI API 2.5
ownerVcComputeResource

@since VI API 2.5
parentVcManagedEntity

@since VI API 2.5
permissionVcPermission []

@since VI API 2.5
recentTaskVcTask []

@since VI API 2.5
resourcePoolVcResourcePool []

@since VI API 2.5
runtimeVcResourcePoolRuntimeInfo

@since VI API 2.5
sdkConnectionVcSdkConnection

@since Unknown
sdkIdString

@since Unknown
summaryVcResourcePoolSummary

@since VI API 2.5
tagVcTag []

@since vSphere API 4.0
triggeredAlarmStateVcAlarmState []

@since VI API 2.5
typeStringDeprecated.

Returns the name for the this managed object's vim type @since Unknown
valueVcCustomFieldValue []

@since VI API 2.5
vimHostVcSdkConnection

@since Unknown
vimIdString

@since Unknown
vimTypeString

@since Unknown
vmVcVirtualMachine []

@since VI API 2.5

Methods

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

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. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0String

arg1VcResourceConfigSpec

arg2VcVAppConfigSpec

arg3VcFolder


Return Value

Type Description
VcVirtualApp

removeTag

Removes a set of tags from this object. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcTag []


Return Value

Type Description
None

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. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
VcTask

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1VcResourceConfigSpec


Return Value

Type Description
VcResourcePool

refreshRuntime

Refreshes the resource usage data that is available in {@link ResourcePool.RuntimeInfo}. 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 {@link ResourcePool.RuntimeInfo} is needed. @since vSphere API 4.1

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createTrigger

@since Unknown

Parameters

NameTypeDescription
timeoutNumber

filterString

conditionString

filterToSyncString


Return Value

Type Description
Trigger

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 {@link vim.Folder#registerVm}.

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. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0String

arg1String

arg2VcHostSystem


Return Value

Type Description
VcTask

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 {@link vim.Folder#createVm Folder}.

This method can only be called directly on a {@link vim.VirtualApp 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 {@link vim.Folder#createVm} for a description of these privileges. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcVirtualMachineConfigSpec

arg1VcHostSystem


Return Value

Type Description
VcTask

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:

@since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1VcResourceConfigSpec


Return Value

Type Description
None

_getRef

@since Unknown

Parameters

NameTypeDescription
None

Return Value

Type Description
VcManagedObjectReference

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:

@since VI API 2.5

Parameters

NameTypeDescription
arg0VcResourceConfigSpec []


Return Value

Type Description
None

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.

@since VI API 2.5

Parameters

NameTypeDescription
None

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0VcManagedEntity []


Return Value

Type Description
None

setCustomValue

Assigns a value to a custom field. The setCustomValue method requires whichever updatePrivilege is defined as one of the {@link CustomFieldsManager.FieldDef#fieldInstancePrivileges} for the CustomFieldDef whose value is being changed. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
None

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 {@link vim.HttpNfcLease#state} property on the {@link vim.HttpNfcLease} 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 {@link vim.HttpNfcLease#info} property of the lease. The client must call {@link vim.HttpNfcLease#progress} 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 {@link vim.HttpNfcLease#complete}. The client can also abort the import process by calling {@link vim.HttpNfcLease#abort}.

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 {@link vim.Folder#createVm} for a description of these privileges. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0VcImportSpec

arg1VcFolder

arg2VcHostSystem


Return Value

Type Description
VcHttpNfcLease

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. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

retrieveCustomValues

Retrieve Custom field values based on specified custom field keys. If there is no key specified, all custom values associated to this ManagedEntity will be returned. @since vSphere API 6.5

Parameters

NameTypeDescription
arg0Number []


Return Value

Type Description
VcCustomFieldValue []

queryResourceConfigOption

Get a value range and default values for {@link ResourceConfigSpec}. @since vSphere API 4.1

Parameters

NameTypeDescription
None

Return Value

Type Description
VcResourceConfigOption

addTag

Add a set of tags to this object that can be queried later. The tag must be of the form "system/" or "global/ Parameters

NameTypeDescription
arg0VcTag []


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.

@since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcTask