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

NameTypeDescription
_thisManagedObjectReference A reference to the VsanUpgradeSystemEx used to make the method call.
clusterManagedObjectReference
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
RuntimeFaultThrown 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



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 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
Since
vSphere API 6.5

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VsanUpgradeSystemEx used to make the method call.
clusterManagedObjectReference
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
RuntimeFaultThrown 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



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:

  1. Any vSAN host is disconnected from vCenter server
  2. ESXi host before vSphere 6.0 exists in vSAN cluster, of which on-disk format cannot be upgraded
  3. Any vSAN host enables auto-mode to claim disk
  4. Network issue exists in vSAN cluster, which leads to communication problem among vSAN hosts
  5. Not all vSAN member hosts reside in specified vCenter cluster
  6. Any vSAN host contributes in the other vSAN cluster
  7. There is inaccessible vSAN object in vSAN datastore
  8. Any in-use vSAN disk that are unhealthy, such as physical disk lost
  9. Hybrid disk group exists in vSAN cluster, and requests to enable Deduplication and Compression
  10. To request enable Deduplication and Compression, but there is ESXi host software version is below then ESXi 6.0 Update 2
  11. vSAN downgrade is requested, but vSAN objects have already been upgraded to 2.0 or above
  12. 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 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

NameTypeDescription
_thisManagedObjectReference A reference to the VsanUpgradeSystemEx used to make the method call.
clusterManagedObjectReference
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
VsanDiskFormatConversionCheckResultPreflight check result.

Faults

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



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

NameTypeDescription
_thisManagedObjectReference A reference to the VsanUpgradeSystemEx used to make the method call.
clusterManagedObjectReference
to a ClusterComputeResource

The target cluster to process scan.

Return Value

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

Faults

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



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 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
Since
vSphere API 6.5

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the VsanUpgradeSystemEx used to make the method call.
clusterManagedObjectReference
to a ClusterComputeResource

The cluster for which to retrieve the upgrade status.

Return Value

Type Description
VsanUpgradeStatusExStatus

Faults

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