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

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:

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

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

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>