Managed Object - VsanUpgradeSystemEx(vim.VsanUpgradeSystemEx)

See also: ClusterComputeResource, HostSystem, Task, VsanDiskFormatConversionCheckResult, VsanDiskFormatConversionSpec, VsanUpgradeStatusEx
Since: vSphere API 6.0

Managed Object Description

It deprecates vim.VsanUpgradeSystem, to take care of vSAN upgrade process.

It has capability to support additional advanced disk format conversion specification, to help on configuration of latest vSAN advanced features.

It supports following vSAN on-disk format versions:

version 1, released by vSAN 1.0, vSphere ESXi 5.5U1;
version 2, released by vSAN 6.0, which supports Virsto file system;
version 3, released by vSAN 6.2, which supports vSAN deduplication and compression.

It can be accessed with MOID vsan-upgrade-systemex through vSAN service at vCenter server side.

Properties

Name	Type	Description
None

Methods

Methods defined in this Managed Object
PerformVsanUpgradeEx, PerformVsanUpgradePreflightAsyncCheck_Task, PerformVsanUpgradePreflightCheckEx, RetrieveSupportedVsanFormatVersion, VsanQueryUpgradeStatusEx

PerformVsanUpgradeEx(performUpgrade)

Start vSAN disk format conversion on a particular cluster.

It deprecates API vim.VsanUpgradeSystem.PerformVsanUpgrade, besides supporting original basic upgrade options, it also supports advanced disk format conversion spec, to convert vSAN disk format to support corresponding vSAN advanced features, such as vSAN deduplication and compression, etc.

In order to perform this on-disk format upgrade, the upgrade process will perform a rolling evacuation/remove/re-add operation to accomplish the upgrade. In other words, one disk group at a time, it will evacuate the data from the disk group, then remove the old format from the now empty disk group, then reformat the disk group with the new format. Once all disk groups have been upgraded, and if the performObjectUpgrade parameter is set, the vSAN object version is also upgraded. Before the object version is upgraded, it is possible to downgrade the cluster by passing the downgradeFormat parameter. Once objects are of the new object version however, downgrade (and thus rollback) are no longer possible. The new object version is required to allow objects to benefit from new vSAN features.

The upgrade process performs additional "preflight checks" before proceeding to upgrade the next host. The upgrade process will be halted if any of those preflight checks fail.

If the upgrade process has been halted due to a problem, or even due to a crash or other failure, it can be re-started at any point in time. The upgrade will resume where it left off and only do the parts that are still outstanding. If the upgrade process stopped after removing vSAN from a disk group, but before re-adding those disks to vSAN, the upgrade process can recover from that. The preflight check results indicate such a condition.

Combined Privileges Required (on vSphere ManagedEntity):

Privileges	Required on
Host.Config.Storage	ClusterComputeResource

* The RootFolder entity in above table refers to the vCenter server itself in the vCenter UI
* The ClusterComputeResource entity in above table refers to the cluster which is being operated on

* The Required Privileges section below is not used, please ignore.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VsanUpgradeSystemEx used to make the method call.
cluster	ManagedObjectReference to a ClusterComputeResource	The cluster to be upgraded
performObjectUpgrade*	xsd:boolean	After all disk groups have been updated, also upgrade all objects. Once started, rollback of the on disk format is no longer possible. Object upgrade unlocks new vSAN features. The default behavior is upgrading objects is this parameter is not specified. *Since* vSphere API 6.0
downgradeFormat*	xsd:boolean	Perform a on-disk format downgrade instead of upgrade. Only possible if no upgraded objects exist. *Since* vSphere API 6.0
allowReducedRedundancy*	xsd:boolean	Removes the need for one disk group worth of free space, by allowing reduced redundancy during disk upgrade. *Since* vSphere API 6.0
excludeHosts*	ManagedObjectReference[] to a HostSystem[]	Internal debug option meant for functional testing of vSAN upgrades. Skips upgrade on certain hosts and implies performObjectUpgrade being false. Should not be used by customers. *Since* vSphere API 6.0
spec*	VsanDiskFormatConversionSpec	The specification of advanced disk format configuration. The spec cannot be supported in downgrade process, for now we don't have any advanced features supported by lower disk format. *Since* vSphere API 6.0

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a Task	vim.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.
VsanFault

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="PerformVsanUpgradeEx" type="vsan:PerformVsanUpgradeExRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="PerformVsanUpgradeExResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vsan:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

PerformVsanUpgradePreflightAsyncCheck_Task(performUpgradePreflightAsyncCheck)

Perform an upgrade preflight check on a cluster asynchronously. Has the same arguments as PerformVsanUpgradePreflightCheckEx for argument details. The checks are performed asynchronously tracked by a task. Upon completion results can be obtained by calling VsanQueryUpgradeStatusEx

Combined Privileges Required (on vSphere ManagedEntity):

Privileges	Required on
Host.Config.Storage	ClusterComputeResource

* The Required Privileges section below is not used, please ignore.

Required Privileges: System.Read
Since: vSphere API 6.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VsanUpgradeSystemEx used to make the method call.
cluster	ManagedObjectReference to a ClusterComputeResource	The target cluster to process conversion.
downgradeFormat*	xsd:boolean	Intend to perform a on-disk format downgrade instead of upgrade. Adds additional checks. *Since* vSphere API 6.5
spec*	VsanDiskFormatConversionSpec	The specification of advanced disk format configuration. Adds additional checks. The specification cannot be supported in downgrade process, for now we don't have any advanced features supported by lower disk format. *Since* vSphere API 6.5

*Need not be set

Return Value

Type	Description
ManagedObjectReference to a Task	A task to monitor progress. Results should be obtains by VsanQueryUpgradeStatusEx

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

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="PerformVsanUpgradePreflightAsyncCheck_Task" type="vsan:PerformVsanUpgradePreflightAsyncCheck_TaskRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="PerformVsanUpgradePreflightAsyncCheck_TaskResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vsan:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

PerformVsanUpgradePreflightCheckEx(performUpgradePreflightCheck)

Perform an upgrade preflight check on a cluster.

It deprecates API vim.VsanUpgradeSystem.PerformVsanUpgradePreflightCheck, and helps to check following issues which would break vSAN upgrade process:

Any vSAN host is disconnected from vCenter server
ESXi host before vSphere 6.0 exists in vSAN cluster, of which on-disk format cannot be upgraded
Any vSAN host enables auto-mode to claim disk
Network issue exists in vSAN cluster, which leads to communication problem among vSAN hosts
Not all vSAN member hosts reside in specified vCenter cluster
Any vSAN host contributes in the other vSAN cluster
There is inaccessible vSAN object in vSAN datastore
Any in-use vSAN disk that are unhealthy, such as physical disk lost
Hybrid disk group exists in vSAN cluster, and requests to enable Deduplication and Compression
To request enable Deduplication and Compression, but there is ESXi host software version is below then ESXi 6.0 Update 2
vSAN downgrade is requested, but vSAN objects have already been upgraded to 2.0 or above
Any vSAN object that would present an upgrade issue

Any issue detected by preflight check, requires manual fix by end user, before trigger vSAN upgrade process through PerformVsanUpgradeEx.

Combined Privileges Required (on vSphere ManagedEntity):

Privileges	Required on
Host.Config.Storage	ClusterComputeResource

* The Required Privileges section below is not used, please ignore.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VsanUpgradeSystemEx used to make the method call.
cluster	ManagedObjectReference to a ClusterComputeResource	The target cluster to be converted.
downgradeFormat*	xsd:boolean	Intend to perform a on-disk format downgrade instead of upgrade. Adds additional checks. *Since* vSphere API 6.0
spec*	VsanDiskFormatConversionSpec	The specification of advanced disk format configuration. Adds additional checks. The specification cannot be supported in downgrade process, for now we don't have any advanced features supported by lower disk format. *Since* vSphere API 6.0

*Need not be set

Return Value

Type	Description
VsanDiskFormatConversionCheckResult	Preflight check result.

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:vsan="urn:vsan" name="PerformVsanUpgradePreflightCheckEx" type="vsan:PerformVsanUpgradePreflightCheckExRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="PerformVsanUpgradePreflightCheckExResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vsan:VsanDiskFormatConversionCheckResult"/>
               </sequence>
            </complexType>
         </element>

RetrieveSupportedVsanFormatVersion(retrieveSupportedFormatVersion)

Process a scan and retrieve the highest vSAN disk format version that given cluster supports, the version is up to version of ESXi host in specified cluster: ESX of VSAN2017Q1, support version is 5. ESX of vSphere6.0u2 and vSphere6.5, support version is 4; ESX of vSphere6.0 series before vSphere6.0U2, support version is 2; ESX of lower version, is not supported;

Combined Privileges Required (on vSphere ManagedEntity):

Privileges	Required on
System.Read	ClusterComputeResource

* The Required Privileges section below is not used, please ignore.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VsanUpgradeSystemEx used to make the method call.
cluster	ManagedObjectReference to a ClusterComputeResource	The target cluster to process scan.

Return Value

Type	Description
xsd:int	int To present the highest supported disk format version.

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:vsan="urn:vsan" name="RetrieveSupportedVsanFormatVersion" type="vsan:RetrieveSupportedVsanFormatVersionRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="RetrieveSupportedVsanFormatVersionResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:int"/>
               </sequence>
            </complexType>
         </element>

VsanQueryUpgradeStatusEx(queryUpgradeStatus)

Retrieve the latest status of a running, or the previously completed, upgrade or precheck process. Information about previous upgrade runs are not always, e.g. when vCenter gets restarted.

Combined Privileges Required (on vSphere ManagedEntity):

Privileges	Required on
System.Read	ClusterComputeResource

* The Required Privileges section below is not used, please ignore.

Required Privileges: System.Read
Since: vSphere API 6.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VsanUpgradeSystemEx used to make the method call.
cluster	ManagedObjectReference to a ClusterComputeResource	The cluster for which to retrieve the upgrade status.

Return Value

Type	Description
VsanUpgradeStatusEx	Status

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:vsan="urn:vsan" name="VsanQueryUpgradeStatusEx" type="vsan:VsanQueryUpgradeStatusExRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vsan="urn:vsan" name="VsanQueryUpgradeStatusExResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vsan:VsanUpgradeStatusEx"/>
               </sequence>
            </complexType>
         </element>