Managed Object - ClusterComputeResource(vim.ClusterComputeResource)

Property of: ClusterEVCManager, PlacementRankResult, PlacementRankSpec, StorageDrsPlacementRankVmSpec
Parameter to: BatchAddHostsToCluster_Task, PerformVsanUpgrade_Task, PerformVsanUpgradePreflightCheck, QueryUnmonitoredHosts, QueryVsanUpgradeStatus, ResolveInstallationErrorsOnCluster_Task
Returned by: CreateCluster, CreateClusterEx
Extends: ComputeResource
See also: ClusterActionHistory, ClusterComputeResourceClusterConfigResult, ClusterComputeResourceHCIConfigInfo, ClusterComputeResourceHCIConfigSpec, ClusterComputeResourceHostConfigurationInput, ClusterComputeResourceValidationResultBase, ClusterConfigInfo, ClusterConfigSpec, ClusterDasAdvancedRuntimeInfo, ClusterDrsFaults, ClusterDrsMigration, ClusterDrsRecommendation, ClusterEnterMaintenanceResult, ClusterEVCManager, ClusterHostRecommendation, ClusterRecommendation, ClusterResourceUsageSummary, ClusterRuleInfo, HostConnectSpec, HostSystem, OptionValue, PlacementResult, PlacementSpec, ResourcePool, SDDCBase, VirtualMachine
Since: 2.0

Managed Object Description

The ClusterComputeResource data object aggregates the compute resources of associated HostSystem objects into a single compute resource for use by virtual machines. The cluster services such as HA (High Availability), DRS (Distributed Resource Scheduling), and EVC (Enhanced vMotion Compatibility), enhance the utility of this single compute resource.

Use the Folder.CreateClusterEx method to create an instance of this object.

Properties

Name	Type	Description
actionHistory*	ClusterActionHistory[]	The set of actions that have been performed recently. *Since* VI API 2.5
configuration	ClusterConfigInfo	Deprecated. As of VI API 2.5, use ConfigurationEx, which is a ClusterConfigInfoEx data object.. Configuration of the cluster.
drsFault* P	ClusterDrsFaults[]	A collection of the DRS faults generated in the last DRS invocation. Each element of the collection is the set of faults generated in one recommendation. DRS faults are generated when DRS tries to make recommendations for rule enforcement, power management, etc., and indexed in a tree structure with reason for recommendations and VM to migrate (optional) as the index keys. 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. *Since* vSphere API 4.0
drsRecommendation*	ClusterDrsRecommendation[]	Deprecated. As of VI API 2.5, use Recommendation. vSphere 6.5 is the last version where this property is populated. Later versions of vSphere no longer populate this property. deprecated As of VI API 2.5, use Recommendation. vSphere 6.5 is the last version where this property is populated. Later versions of vSphere no longer populate this property.
hciConfig*	ClusterComputeResourceHCIConfigInfo	This is applicable to clusters which are configured using the HCI workflow and contains data related to the workflow and specification. *Since* vSphere API 6.7.1
migrationHistory*	ClusterDrsMigration[]	The set of migration decisions that have recently been performed. This list is populated only when DRS is in automatic mode.
recommendation* P	ClusterRecommendation[]	List of recommended actions for the cluster. It is possible that the current set of recommendations may be empty, either due to not having any running dynamic recommendation generation module, or since there may be no recommended actions at this time. *Since* VI API 2.5
Properties inherited from ComputeResource
configurationEx, datastore, environmentBrowser, host, lifecycleManaged, network, resourcePool, summary
Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value

*May not be presentP Required privilege: System.Read

Methods

Methods defined in this Managed Object
AbandonHciWorkflow, AddHost_Task, ApplyRecommendation, CancelRecommendation, ClusterEnterMaintenanceMode, ConfigureHCI_Task, EvcManager, ExtendHCI_Task, FindRulesForVm, GetResourceUsage, MoveHostInto_Task, MoveInto_Task, PlaceVm, RecommendHostsForVm, ReconfigureCluster_Task, RefreshRecommendation, RetrieveDasAdvancedRuntimeInfo, SetCryptoMode, StampAllRulesWithUuid_Task, ValidateHCIConfiguration
Methods inherited from ComputeResource
ReconfigureComputeResource_Task
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject
setCustomValue

AbandonHciWorkflow

Opt out of the HCI workflow. This operation is only allowed on a cluster that was created with the HCI workflow. When the cluster is created, but still unconfigured, the workflowState is "in_progress". The AbandonHciWorkflow method may be called at any time before cluster configuration begins; it is not possible to abandon the workflow during the configuration procedure.

Required Privileges: Host.Inventory.EditCluster
Since: vSphere API 6.7.1

Parameters

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

Return Value

Type	Description
None

Faults

Type	Description
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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AbandonHciWorkflow" type="vim25:AbandonHciWorkflowRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AbandonHciWorkflowResponse">
                  <complexType/>
               </element>

AddHost_Task(addHost)

Adds a host to the cluster. The hostname must be either an IP address, such as 192.168.0.1, or a DNS resolvable name. DNS names may be fully qualified names, such as host1.domain1.com, or a short name such as host1, providing host1 resolves to host1.domain1.com. The system uses DNS to resolve short names to fully qualified names. If the cluster supports nested resource pools and the user specifies the optional ResourcePool argument, then the host's root resource pool becomes the specified resource pool. The stand-alone host resource hierarchy is imported into the new nested resource pool.

If the cluster does not support nested resource pools, then the stand-alone host resource hierarchy is discarded and all virtual machines on the host are put under the cluster's root resource pool.

In addition to the Host.Inventory.AddHostToCluster and Resource.AssignVMToPool privileges, it requires System.View privilege on the VM folder that the VMs of the host will be placed on.

Required Privileges: Host.Inventory.AddHostToCluster

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ClusterComputeResource used to make the method call.
spec P	HostConnectSpec	Specifies the parameters needed to add a single host. *Since* 2.0
asConnected P	xsd:boolean	Flag to specify whether or not the host should be connected immediately after it is added. The host will not be added if a connection attempt is made and fails. *Since* 2.0
resourcePool* P	ManagedObjectReference to a ResourcePool	the resource pool for the root resource pool from the host. *Since* 2.0
license* P	xsd:string	Provide a licenseKey or licenseKeyType. See LicenseManager *Since* 2.0

*Need not be set PRequired privilege - see tooltip for details

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 added HostSystem upon success.

Faults

Type	Description
AgentInstallFailed	Thrown if there is an error installing the VirtualCenter agent on the host.
AlreadyBeingManaged	Thrown if the host is already being managed by a VirtualCenter server.
AlreadyConnected	Thrown if asConnected is true and the host is already connected to VirtualCenter.
DuplicateName	Thrown if another host in the same cluster has the name.
GatewayConnectFault	Thrown if the host is managed via host gateway and any error occurred during the communication with the gateway
GatewayHostNotReachable	Thrown if the host is managed via host gateway and the gateway server cannot connect to the host
GatewayNotFound	Thrown if the host is managed via host gateway and no available gateway server is found for the given parameters
GatewayNotReachable	Thrown if the host is managed via host gateway and vCenter Server cannot establish a network connection to the gateway server, or verify the gateway server's identity
GatewayOperationRefused	Thrown if the gateway server cannot accept more host connections
GatewayToHostAuthFault	Thrown if the host is managed via host gateway and the gateway server needs additional information to authenticate before the host
GatewayToHostTrustVerifyFault	Thrown if the host is managed via host gateway and the gateway server cannot verify that the host is trusted
HostConnectFault	Thrown if an error occurred when connecting to a host. Typically, a more specific subclass, such as AlreadyBeingManaged, is thrown.
InvalidLogin	Thrown if "asConnected" is specified but authentication with the new host fails.
NoHost	Thrown if the host cannot be contacted.
NotSupportedHost	Thrown if the host is running a software version that does not support clustering features. It may still be possible to add the host as a stand-alone host.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SSLVerifyFault	Thrown if the host certificate could not be authenticated
TooManyHosts	Thrown if no additional hosts can be added to the cluster.

Events

Type
None

ApplyRecommendation(applyRecommendation)

Applies a recommendation from the drsRecommendation or the recommendation list. Each recommendation can be applied only once.

resource.applyRecommendation privilege is required if the recommendation is DRS migration or power management recommendations.

Required Privileges: None

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

key P

xsd:string

The key field of the DrsRecommendation or Recommendation.

Since 2.0

P Required privilege: key

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ApplyRecommendation" type="vim25:ApplyRecommendationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ApplyRecommendationResponse">
                  <complexType/>
               </element>

CancelRecommendation(cancelRecommendation)

Cancels a recommendation.

Required Privileges: System.Read
Since: vSphere API 4.1

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

key P

xsd:string

The key field of the Recommendation.

Since vSphere API 4.1

P Required privilege: key

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelRecommendation" type="vim25:CancelRecommendationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelRecommendationResponse">
                  <complexType/>
               </element>

ClusterEnterMaintenanceMode(enterMaintenanceMode)

The API takes a list of hosts in the cluster as input, and returns a list of hosts in "ClusterMaintenanceResult" that the server can successfully evacuate given the existing constraints in the cluster, such as HA, FT, Vmotion compatibility, reservations, affinity rules, etc. The client is allowed to pass all hosts in the cluster to the API, even though all of them cannot enter maintenance mode at the same time. The list returned from the API contains the largest number of hosts that the server can evacuate simultaneously. The client can then request to enter each host in the returned list into maintenance mode. The client can specify an integer "DemandCapacityRatioTarget" option in the "option" parameter. The allowed values of the option range from 40 to 200, and the default value is 100. This option controls how much resource overcommitment the server should make in consolidating the VMs onto fewer hosts. A value of 100 means the server will keep the same amount of powered-on capacity as the current VM demands. A value less than 100 means undercommitted resources. A value greater than 100 means overcommitted resources. The hosts are recommended based on the inventory at the time of the API invocation. It is not guaranteed that the actual enter-maintenance tasks on the hosts will succeed, if the inventory changes after the API returns, or if vmotions fail due to unexpected conditions. For possible exceptions thrown by the necessary relocate operations, see MigrateVM_Task.

Required Privileges: System.View
Since: vSphere API 5.0

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

host P

ManagedObjectReference[]
to a HostSystem[]

The array of hosts to put into maintenance mode.

Since vSphere API 5.0

option* P

OptionValue[]

An array of OptionValue options for this query. The specified options override the advanced options in ClusterDrsConfigInfo.

Since vSphere API 5.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ClusterEnterMaintenanceResult	A ClusterEnterMaintenanceResult object, which consists of an array of recommendations for hosts that can be evacuated and an array of faults for hosts that cannot be evacuated.

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ClusterEnterMaintenanceMode" type="vim25:ClusterEnterMaintenanceModeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ClusterEnterMaintenanceModeResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ClusterEnterMaintenanceResult"/>
                     </sequence>
                  </complexType>
               </element>

ConfigureHCI_Task(configureHCI)

Configures the cluster. This API requires Host.Inventory.EditCluster privilege on the cluster and the hosts; additional privileges might be required depending on the inputs. This operation is only allowed on a cluster that was created with the HCI workflow. Before calling this method, it is recommended that ValidateHCIConfiguration is invoked with the DvsProfile objects listed in HCIConfigSpec#dvsProf along with the hosts listed in HostConfigurationInput to validate that the desired network settings can be applied correctly.

Required Privileges: None
Since: vSphere API 6.7.1

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

clusterSpec P

ClusterComputeResourceHCIConfigSpec

Specification to configure the cluster, see ClusterComputeResourceHCIConfigSpec for details. The DistributedVirtualSwitch and DistributedVirtualPortgroup objects contained within the specification must be in the same datacenter as the cluster. Specify HCIConfigSpec#vSanConfigSpec only when vSan is enabled on the cluster.

Since vSphere API 6.7.1

hostInputs* P

ClusterComputeResourceHostConfigurationInput[]

Inputs to configure each host in the cluster, see ClusterComputeResourceHostConfigurationInput for details. Hosts in this list should be part of the cluster and should be in maintenance mode for them to be configured per specification. If this parameter is not specified, the API operates on all the hosts in the cluster. Hosts which were not configured due to not being in maintenance mode will be returned in ClusterConfigResult#failedHosts.

Since vSphere API 6.7.1

*Need not be set PRequired privilege - see tooltip for details

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 a ClusterConfigResult object, which upon completion will contain a list of hosts which were successfully configured and a list of hosts which could not be configured.

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

EvcManager(evcManager)

A managed object that controls Enhanced vMotion Compatibility mode for this cluster.

Required Privileges: System.Read
Since: vSphere API 6.0

Parameters

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

Return Value

Type	Description
ManagedObjectReference to a ClusterEVCManager

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EvcManager" type="vim25:EvcManagerRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EvcManagerResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

ExtendHCI_Task(extendHCI)

Extend an existing HCI cluster. This API requires Host.Inventory.EditCluster privilege on the cluster and the hosts, additional privileges might be required depending on the inputs.

Required Privileges: None
Since: vSphere API 6.7.1

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

hostInputs* P

ClusterComputeResourceHostConfigurationInput[]

Inputs to configure specified set of hosts in the cluster. See ClusterComputeResourceHostConfigurationInput for details. Hosts in this list should be part of the cluster and should be in maintenance mode for them to be configured per specification. Hosts which were not configured due to not being in maintenance mode will be returned in ClusterConfigResult#failedHosts. Specify HostConfigurationInput#hostVmkNics only if dvsSetting is set.

Since vSphere API 6.7.1

vSanConfigSpec* P

SDDCBase

Specification to configure vSAN on specified set of hosts. See vim.vsan.ReconfigSpec for details. This parameter should be specified only when vSan is enabled on the cluster.

Since vSphere API 6.7.1

*Need not be set PRequired privilege - see tooltip for details

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 a ClusterConfigResult object, which upon successful completion would contain the list of hosts which couldn't be configured and a list of hosts which were successfully configured. This API can be called only after the cluster is configured using ConfigureHCI_Task and requires HCIConfigInfo#workflowState to be "done".

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 a ClusterConfigResult object, which upon successful completion would contain the list of hosts which couldn't be configured and a list of hosts which were successfully configured. This API can be called only after the cluster is configured using ConfigureHCI_Task and requires HCIConfigInfo#workflowState to be "done".

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

FindRulesForVm(findRulesForVm)

Finds all enabled and disabled VM-VM Affinity and Anti-Affinity rules, involving the given Virtual Machine.

Required Privileges: System.View
Since: vSphere API 6.0

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

vm P

ManagedObjectReference
to a VirtualMachine

The vm whose rules need to be looked up.

Since vSphere API 6.0

P Required privilege: vm

Return Value

Type	Description
ClusterRuleInfo[]

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindRulesForVm" type="vim25:FindRulesForVmRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="FindRulesForVmResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ClusterRuleInfo" minOccurs="0" maxOccurs="unbounded"/>
                     </sequence>
                  </complexType>
               </element>

GetResourceUsage(getResourceUsage)

This API can be invoked to get the current CPU, memory and storage usage in the cluster.

Required Privileges: System.Read
Since: vSphere API 6.0

Parameters

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

Return Value

Type	Description
ClusterResourceUsageSummary	An instance of ResourceUsageSummary with following information: cpuCapacityMHz: Sum of CPU capacity of all the available hosts in the cluster in MHz. cpuUsedMHz: Sum of CPU consumed in all the available hosts in the cluster in MHz. memCapacityMB: Sum of memory capacity of all the available hosts in the cluster in MB. memUsedMB: Sum of memory consumed in all the available hosts in this cluster in MB. storageCapacityMB: Total storage capacity of all the accessible datastores in this cluster. storageUsedMB: Total storage consumed in all the accessible datastores in this cluster.

Type

Description

ClusterResourceUsageSummary

An instance of ResourceUsageSummary with following information:

cpuCapacityMHz: Sum of CPU capacity of all the available hosts in the cluster in MHz.
cpuUsedMHz: Sum of CPU consumed in all the available hosts in the cluster in MHz.
memCapacityMB: Sum of memory capacity of all the available hosts in the cluster in MB.
memUsedMB: Sum of memory consumed in all the available hosts in this cluster in MB.
storageCapacityMB: Total storage capacity of all the accessible datastores in this cluster.
storageUsedMB: Total storage consumed in all the accessible datastores in this cluster.

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="GetResourceUsage" type="vim25:GetResourceUsageRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="GetResourceUsageResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ClusterResourceUsageSummary"/>
                     </sequence>
                  </complexType>
               </element>

MoveHostInto_Task(moveHostInto)

Moves an existing host into a cluster. The host must be part of the same datacenter, and if the host is part of a cluster, the host must be in maintenance mode.

If the host is a stand-alone host, the stand-alone ComputeResource is removed as part of this operation.

All virtual machines associated with the host, regardless of whether or not they are running, are moved with the host into the cluster. If there are virtual machines that should not be moved, then migrate those virtual machines off the host before initiating this operation.

If the host is a stand-alone host, the cluster supports nested resource pools, and the user specifies the optional resourcePool argument, then the stand-alone host's root resource pool becomes the specified resource pool and the stand-alone host resource hierarchy is imported into the new nested resource pool. If the cluster does not support nested resource pools or the resourcePool argument is not specified, then the stand-alone host resource hierarchy is ignored.

Required Privileges: Host.Inventory.EditCluster

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

host P

ManagedObjectReference
to a HostSystem

The list of hosts to move into the cluster.

Since 2.0

resourcePool* P

ManagedObjectReference
to a ResourcePool

The resource pool to match the root resource pool of stand-alone hosts. This argument has no effect if the host is part of a cluster.

Since 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a Task	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
InvalidState	Thrown if a host is already part of a cluster and is not in maintenance mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TooManyHosts	Thrown if no additional hosts can be added to the cluster.

Events

Type
None

MoveInto_Task(moveInto)

Moves an existing host into a cluster. The host must be part of the same datacenter, and if the host is part of a cluster, the host must be in maintenance mode.

If the host is part of a stand-alone ComputeResource, then the stand-alone ComputeResource is removed as part of this operation.

All virtual machines associated with a host, regardless of whether or not they are running, are moved with the host into the cluster. If there are virtual machines that should not be moved, then migrate those virtual machines off the host before initiating this operation.

For stand-alone hosts, the host resource pool hierarchy is discarded in this call. To preserve a host resource pools from a stand-alone host, call moveHostInt, specifying an optional resource pool. This operation is transactional only with respect to each individual host. Hosts in the set are moved sequentially and are committed, one at a time. If a failure is detected, then the method terminates with an exception. Since hosts are moved one at a time, if this operation fails while in the process of moving multiple hosts, some hosts are left unmoved.

In addition to the privileges mentioned, the user must also hold Host.Inventory.EditCluster on the host's source ComputeResource object.

Required Privileges: Host.Inventory.EditCluster

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

host P

ManagedObjectReference[]
to a HostSystem[]

The list of hosts to move into the cluster.

Since 2.0

P Required privilege: host

Return Value

Type	Description
ManagedObjectReference to a Task	This method returns a Task object with which to monitor the operation.

Faults

Type	Description
DuplicateName	Thrown if the host is already in the cluster
InvalidState	Thrown if a host is already part of a cluster and is not in maintenance mode.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TooManyHosts	Thrown if no additional hosts can be added to the cluster.

Events

Type
None

PlaceVm(placeVm)

This method returns a PlacementResult object. This API can be invoked to ask DRS for a set of recommendations for moving a virtual machine and its virtual disks into a cluster.

Required Privileges: System.View
Since: vSphere API 6.0

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

placementSpec P

PlacementSpec

Specification for placing a virtual machine and its virtual disks

Since vSphere API 6.0

P Required privilege: placementSpec

Return Value

Type	Description
PlacementResult

Faults

Type	Description
InvalidState	Thrown if invoked on a DRS disabled cluster.
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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="PlaceVm" type="vim25:PlaceVmRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="PlaceVmResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:PlacementResult"/>
                     </sequence>
                  </complexType>
               </element>

RecommendHostsForVm(recommendHostsForVm)

Deprecated. As of VI API 2.5, use PowerOnMultiVM_Task. RecommendHostsForVm cannot make any recommendations if DRS cannot find the specified host in the cluster. With PowerOnMultiVM_Task, DRS attempts to migrate virtual machines and power on hosts in standby mode, given the same conditions.

Gets a recommendation for where to power on, resume, revert from powered-off state to powered on state, or to migrate a specific virtual machine. If no host is found, an empty list is returned.

The type of operation is implied by the state of the virtual machine. Returned hosts are intended for power-on or resume if the virtual machine is powered-off or suspended. However, if the virtual machine is powered-on, the request is assumed to be for migrating a virtual machine into a DRS enabled cluster. In that case, the ResourcePool argument should be specified and the ResourcePool and the virtual machine cannot be in the same cluster.

Required Privileges: System.Read

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

vm P

ManagedObjectReference
to a VirtualMachine

Specifies the virtual machine for which the user is requesting a recommendations.

Since 2.0

pool* P

ManagedObjectReference
to a ResourcePool

Specifies the ResourcePool into which the virtual machine is to be migrated. If the virtual machine is powered-on, this argument must be specified and it is relevant only when the virtual machine is powered-on. This ResourcePool cannot be in the same cluster as the virtual machine.

Since 2.0

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ClusterHostRecommendation[]	An array of HostRecommendation ordered by their rating.

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RecommendHostsForVm" type="vim25:RecommendHostsForVmRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RecommendHostsForVmResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ClusterHostRecommendation" minOccurs="0" maxOccurs="unbounded"/>
                     </sequence>
                  </complexType>
               </element>

ReconfigureCluster_Task(reconfigure)

Deprecated. As of VI API 2.5, use ReconfigureComputeResource_Task.

Reconfigures a cluster.

Required Privileges: Host.Inventory.EditCluster

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

spec P

ClusterConfigSpec

A set of configuration changes to apply to the cluster. The specification can be a complete set of changes or a partial set of changes, applied incrementally.

Since 2.0

modify P

xsd:boolean

Flag to specify whether the specification ("spec") should be applied incrementally. If "modify" is false and the operation succeeds, then the configuration of the cluster matches the specification exactly; in this case any unset portions of the specification will result in unset or default portions of the configuration.

Since 2.0

PRequired privilege - see tooltip for details

Return Value

Type	Description
ManagedObjectReference to a Task	This method returns a Task object with which to monitor the operation.

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

RefreshRecommendation(refreshRecommendation)

Make DRS invoke again and return a new list of recommendations. Concurrent "refresh" requests may be combined together and trigger only one DRS invocation.

The recommendations generated is stored at Recommendation.

Required Privileges: Host.Inventory.EditCluster
Since: VI API 2.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the ClusterComputeResource 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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RefreshRecommendation" type="vim25:RefreshRecommendationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RefreshRecommendationResponse">
                  <complexType/>
               </element>

RetrieveDasAdvancedRuntimeInfo(retrieveDasAdvancedRuntimeInfo)

Retrieve DAS advanced runtime info for this cluster.

Required Privileges: System.Read
Since: vSphere API 4.0

Parameters

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

Return Value

Type	Description
ClusterDasAdvancedRuntimeInfo

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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveDasAdvancedRuntimeInfo" type="vim25:RetrieveDasAdvancedRuntimeInfoRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveDasAdvancedRuntimeInfoResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ClusterDasAdvancedRuntimeInfo" minOccurs="0"/>
                     </sequence>
                  </complexType>
               </element>

SetCryptoMode(setCryptoMode)

Set encrytion mode of the cluster. "onDemand" mode means the hosts will be crypto enabled when there are encrypted VMs created in the cluster. "forceEnable" means all the hosts in the cluster will be forced crypto enable.

Required Privileges: Cryptographer.RegisterHost
Since: vSphere API 7.0

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

cryptoMode P

xsd:string

The new proposed encryption mode. It can be null, "onDemand", or "forceEnable".

Since vSphere API 7.0

P Required privilege: cryptoMode

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if cryptoMode is anything other than null, "onDemand", or "forceEnable".
InvalidRequest	Thrown if feature state swith VMcrypt3_Enhancement is not enabled.
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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SetCryptoMode" type="vim25:SetCryptoModeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SetCryptoModeResponse">
                  <complexType/>
               </element>

StampAllRulesWithUuid_Task(stampAllRulesWithUuid)

Stamp all rules in the cluster with ruleUuid. If a rule has ruleUuid field set, and it has a value, leave it untouched. If rule's ruleUuid field is unset, generate a UUID and stamp the rule.

Required Privileges: Host.Inventory.EditCluster
Since: vSphere API 6.0

Parameters

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

Return Value

Type	Description
ManagedObjectReference to a Task

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

ValidateHCIConfiguration(validateHCIConfiguration)

Validate HCI configuration in pre-configure and post-configure use-cases.

pre-configure use-case: Validates the HCI configuration to be applied on the cluster. A successful validation in this case means the HCIConfigSpec can be applied without errors on the cluster using ConfigureHCI_Task or ExtendHCI_Task

These are the things the API validates:
1. When providing a set of physical adapters in the dvsProf argument, the API validates that all the adapters should be present on all the hosts to be validated. The adapters should either be unmapped or mapped to the same vSwitch across hosts. In addition to this, if the adapters are connected to a DistributedVirtualSwitch, it should be exactly the same way as specified in the dvsProf or in the dvsSetting.
2. The API will also validate that the ESXi versions of the hosts are compatible with the version of the DistributedVirtualSwitch being created.
post-configure case: Validate the cluster has been configured correctly as per the ClusterComputeResourceHCIConfigInfo for the cluster. In this case, the API should be invoked with both params omitted as the intent is to validate all hosts in the cluster using the existing ClusterComputeResourceHCIConfigInfo

Required Privileges: System.Read
Since: vSphere API 6.7.1

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the ClusterComputeResource used to make the method call.

hciConfigSpec* P

ClusterComputeResourceHCIConfigSpec

The ClusterComputeResourceHCIConfigSpec to be used for validating the hosts. If not specified, the existing ClusterComputeResourceHCIConfigInfo of the cluster will be used.

Note:- This param must be omitted for post-configure validation.

Since vSphere API 6.7.1

hosts* P

ManagedObjectReference[]
to a HostSystem[]

The set of hosts to be validated. If not specified, the set of existing hosts in the cluster will be used.

Note:- This param must be omitted for post-configure validation.

Since vSphere API 6.7.1

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type	Description
ClusterComputeResourceValidationResultBase[]	A list of configuration errors. A non-empty list indicates validation has failed.

Faults

Type	Description
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

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ValidateHCIConfiguration" type="vim25:ValidateHCIConfigurationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ValidateHCIConfigurationResponse">
                  <complexType>
                     <sequence>
                        <element name="returnval" type="vim25:ClusterComputeResourceValidationResultBase" minOccurs="0" maxOccurs="unbounded"/>
                     </sequence>
                  </complexType>
               </element>