Start-ServiceFabricClusterUpgrade

Module:

ServiceFabric

Upgrades a Service Fabric cluster.

Syntax

Start-ServiceFabricClusterUpgrade
     [-CodePackageVersion] <String>
     [-ClusterManifestVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredAuto]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-Code]
     [-CodePackageVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredAuto]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-Code]
     [-CodePackageVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredManual]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-Code]
     [-CodePackageVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-Monitored]
     -FailureAction <UpgradeFailureAction>
     [-HealthCheckRetryTimeoutSec <UInt32>]
     [-HealthCheckWaitDurationSec <UInt32>]
     [-HealthCheckStableDurationSec <UInt32>]
     [-UpgradeDomainTimeoutSec <UInt32>]
     [-UpgradeTimeoutSec <UInt32>]
     [-ConsiderWarningAsError <Boolean>]
     [-MaxPercentUnhealthyApplications <Byte>]
     [-MaxPercentUnhealthyNodes <Byte>]
     [-ApplicationTypeHealthPolicyMap <ApplicationTypeHealthPolicyMap>]
     [-EnableDeltaHealthEvaluation]
     [-MaxPercentDeltaUnhealthyNodes <Byte>]
     [-MaxPercentUpgradeDomainDeltaUnhealthyNodes <Byte>]
     [-Force]
     [-ApplicationHealthPolicyMap <ApplicationHealthPolicyMap>]
     [-NodeTypeHealthPolicyMap <NodeTypeHealthPolicyMap>]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-Config]
     [-ClusterManifestVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredAuto]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-Config]
     [-ClusterManifestVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredManual]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-Config]
     [-ClusterManifestVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-Monitored]
     -FailureAction <UpgradeFailureAction>
     [-HealthCheckRetryTimeoutSec <UInt32>]
     [-HealthCheckWaitDurationSec <UInt32>]
     [-HealthCheckStableDurationSec <UInt32>]
     [-UpgradeDomainTimeoutSec <UInt32>]
     [-UpgradeTimeoutSec <UInt32>]
     [-ConsiderWarningAsError <Boolean>]
     [-MaxPercentUnhealthyApplications <Byte>]
     [-MaxPercentUnhealthyNodes <Byte>]
     [-ApplicationTypeHealthPolicyMap <ApplicationTypeHealthPolicyMap>]
     [-EnableDeltaHealthEvaluation]
     [-MaxPercentDeltaUnhealthyNodes <Byte>]
     [-MaxPercentUpgradeDomainDeltaUnhealthyNodes <Byte>]
     [-Force]
     [-ApplicationHealthPolicyMap <ApplicationHealthPolicyMap>]
     [-NodeTypeHealthPolicyMap <NodeTypeHealthPolicyMap>]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-CodePackageVersion] <String>
     [-ClusterManifestVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-UnmonitoredManual]
     [-Force]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-ServiceFabricClusterUpgrade
     [-CodePackageVersion] <String>
     [-ClusterManifestVersion] <String>
     [-ForceRestart]
     [[-UpgradeReplicaSetCheckTimeoutSec] <UInt32>]
     [[-SortOrder] <UpgradeSortOrder>]
     [-ReplicaQuorumTimeoutSec <UInt32>]
     [-RestartProcess]
     [-InstanceCloseDelayDurationSec <UInt32>]
     [-Monitored]
     -FailureAction <UpgradeFailureAction>
     [-HealthCheckRetryTimeoutSec <UInt32>]
     [-HealthCheckWaitDurationSec <UInt32>]
     [-HealthCheckStableDurationSec <UInt32>]
     [-UpgradeDomainTimeoutSec <UInt32>]
     [-UpgradeTimeoutSec <UInt32>]
     [-ConsiderWarningAsError <Boolean>]
     [-MaxPercentUnhealthyApplications <Byte>]
     [-MaxPercentUnhealthyNodes <Byte>]
     [-ApplicationTypeHealthPolicyMap <ApplicationTypeHealthPolicyMap>]
     [-EnableDeltaHealthEvaluation]
     [-MaxPercentDeltaUnhealthyNodes <Byte>]
     [-MaxPercentUpgradeDomainDeltaUnhealthyNodes <Byte>]
     [-Force]
     [-ApplicationHealthPolicyMap <ApplicationHealthPolicyMap>]
     [-NodeTypeHealthPolicyMap <NodeTypeHealthPolicyMap>]
     [-TimeoutSec <Int32>]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Description

The Start-ServiceFabricClusterUpgrade cmdlet upgrades a Service Fabric cluster. You can upgrade Service Fabric code, configuration, or both code and configuration.

To manage Service Fabric clusters, start Windows PowerShell by using the Run as administrator option. Before you perform any operation on a Service Fabric cluster, establish a connection to the cluster by using the Connect-ServiceFabricCluster cmdlet.

Examples

Example 1: Start unmonitored manual upgrade

PS C:\> Start-ServiceFabricClusterUpgrade -CodePackageVersion "2.0.59.0" -ClusterManifestVersion "v2" -UnmonitoredManual

This command starts the unmonitored manual upgrade for the specified code package and configuration.

Example 2: Start upgrade for code only

PS C:\> Start-ServiceFabricClusterUpgrade -Code -CodePackageVersion "2.0.59.0" -UnmonitoredAuto

This command starts the unmonitored automatic upgrade for the specified code package. There is no configuration upgrade.

Example 3: Start config only upgrade

Start-ServiceFabricClusterUpgrade -ClusterManifestVersion "v2" -Config -FailureAction Rollback -Monitored

This command starts the monitored config only upgrade for the specified cluster manifest version. The upgrade uses default health policies and the failure action is specified as Rollback.

Example 4: Start upgrade with a custom health policy

PS C:\> $AppTypeHealthPolicyMap = New-Object -TypeName "System.Fabric.Health.ApplicationTypeHealthPolicyMap"
PS C:\> $AppTypeHealthPolicyMap.Add("CriticalAppType", 0)

PS C:\> $svcType = New-Object -TypeName System.Fabric.Health.ServiceTypeHealthPolicy
PS C:\> $svcType.MaxPercentUnhealthyPartitionsPerService = 20
PS C:\> $svcType.MaxPercentUnhealthyReplicasPerPartition = 20
PS C:\> $warningAsErrorPolicy = New-Object -TypeName System.Fabric.Health.ApplicationHealthPolicy
PS C:\> $warningAsErrorPolicy.ConsiderWarningAsError = $true
PS C:\> $warningAsErrorPolicy.DefaultServiceTypeHealthPolicy = $svcType

PS C:\> $appHealthPolicyMap = New-Object -TypeName System.Fabric.Health.ApplicationHealthPolicyMap
PS C:\> $appHealthPolicyMap.Add("fabric:/System", $warningAsErrorPolicy)

PS C:\> Start-ServiceFabricClusterUpgrade -CodePackageVersion "4.2.83.9493" -ClusterManifestVersion "ScaleMin-1.0" -Monitored -FailureAction Rollback -ApplicationTypeHealthPolicyMap $AppTypeHealthPolicyMap -Force -MaxPercentUnhealthyNodes 20 -MaxPercentUnhealthyApplications 20 -ApplicationHealthPolicyMap $appHealthPolicyMap

This command starts the monitored upgrade for the specified code package and configuration and passes custom health policies. It specifies a custom cluster health policy, defines a different MaxPercentUnhealthyApplications for a critical application type and a custom application health policy for the cluster System application.

Parameters

-ApplicationHealthPolicyMap

Specifies a System.Fabric.Health.ApplicationHealthPolicyMap object that includes custom health policies for some or all of the applications. If you do not specify this parameter, or if you don't include an entry in the map for an application, that application is evaluated with the application health policy defined in the application manifest if it exists, or the default health policy otherwise.

Type:	ApplicationHealthPolicyMap
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationTypeHealthPolicyMap

Specifies the map that defines the maximum percentage of unhealthy applications that are allowed per application type. Application types in this map are evaluated using specific percentages rather than the global percentage specified in the MaxPercentUnhealthyApplications parameter.

For example, if some applications of a type are critical, the cluster administrator can add an entry to the map for that application type and assign it a value of 0% (that is, do not tolerate any failures). All other applications can be evaluated with the MaxPercentUnhealthyApplications parameter set to 20% to tolerate some failures out of the thousands of application instances.

The application type health policy map is used only if the cluster manifest enables application type health evaluation using the configuration entry for HealthManager/EnableApplicationTypeHealthEvaluation.

Type:	ApplicationTypeHealthPolicyMap
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ClusterManifestVersion

Specifies the version stored in a Service Fabric cluster manifest.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Code

Indicates that the package includes only a Service Fabric .msi file.

Type:	SwitchParameter
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-CodePackageVersion

Specifies the version of the Service Fabric .msi file.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Config

Indicates that the package is a Service Fabric cluster manifest.

Type:	SwitchParameter
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

Prompts for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ConsiderWarningAsError

Indicates whether to treat a warning health event as an error event during health evaluation of the cluster entity and of the Nodes entities. Applications are evaluated using per application health policy settings.

Type:	Boolean
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EnableDeltaHealthEvaluation

Indicates that delta health evaluation is used to determine if the Service Fabric cluster is healthy.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FailureAction

Specifies the action to take if the monitored upgrade fails. The acceptable values for this parameter are:

• Rollback
• Manual

Type:	UpgradeFailureAction
Accepted values:	Invalid, Rollback, Manual
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Force

Indicates that this cmdlet skips the warning message and forces the upgrade.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ForceRestart

Indicates that the service host restarts even if the upgrade is a configuration-only change.

Type:	SwitchParameter
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HealthCheckRetryTimeoutSec

Specifies the duration, in seconds, after which Service Fabric retries the health check if the previous health check fails.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HealthCheckStableDurationSec

Specifies the duration, in seconds, that Service Fabric waits in order to verify that the cluster is stable before moving to the next upgrade domain or completing the upgrade. This wait duration prevents undetected changes of health right after the health check is performed.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HealthCheckWaitDurationSec

Specifies the duration, in seconds, that Service Fabric waits before it performs the initial health check after it finishes the upgrade on the upgrade domain.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InstanceCloseDelayDurationSec

Specifies the duration in seconds, to wait before a stateless instance which is impacted by cluster upgrade is closed, to allow the active requests to drain gracefully. This wait duration is effective only for the instances of those stateless services which have a non-zero value configured for the InstanceCloseDelayDuration, and will override the pre-configured value. See InstanceCloseDelayDuration for details.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxPercentDeltaUnhealthyNodes

Specifies the maximum percentage of delta unhealthy nodes that can have aggregated health states of error. If the current unhealthy nodes do not respect the percentage relative to the state at the beginning of the upgrade, the cluster is considered unhealthy.

Type:	Byte
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxPercentUnhealthyApplications

Specifies the maximum percentage of applications that can have aggregated health states of error. If the currently unhealthy applications do not respect this amount, the cluster is considered unhealthy.

Type:	Byte
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxPercentUnhealthyNodes

Specifies the maximum percentage of nodes that can have aggregated health states of error. If the current unhealthy applications do not respect this percentage, the cluster is considered unhealthy.

Type:	Byte
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxPercentUpgradeDomainDeltaUnhealthyNodes

Specifies the maximum percentage of upgrade domain delta unhealthy nodes that can have aggregated health states of error. If there is any upgrade domain where the current unhealthy nodes do not respect the percentage relative to the state at the beginning of the upgrade, the cluster is considered unhealthy.

Type:	Byte
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Monitored

Indicates that the upgrade mode is monitored. This means that health checks are performed after upgrade finishes for an upgrade domain. If the health of the upgrade domain and the cluster meet the specified health policies, Service Fabric starts upgrade of the next upgrade domain. If the upgrade domain or cluster fails to meet health policies, the upgrade fails and Service Fabric rolls back the upgrade or switches to unmonitored manual mode, depending on the specified FailureAction.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-NodeTypeHealthPolicyMap

Defines a map with max percentages unhealthy nodes for specific node types.

The node type health policy map can be used during cluster health evaluation to describe special node types. The node types included in the map are evaluated against the percentage included in the map, and also with the global (see System.Fabric.Health.ClusterHealthPolicy.MaxPercentUnhealthyNodes). The nodes of node types specified in the map are also counted against the global pool of nodes; they are independent checks.

Type:	NodeTypeHealthPolicyMap
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ReplicaQuorumTimeoutSec

Specifies the time-out period, in seconds, to check whether the replica set has quorum. After the time out period, the upgrade proceeds.

This parameter has been deprecated. Specify the UpgradeReplicaSetCheckTimeoutSec parameter instead.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RestartProcess

Indicates that the service host restarts as part of the upgrade.

This parameter has been deprecated. Specify the ForceRestart parameter instead.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SortOrder

Defines the order in which an upgrade proceeds through the cluster.

Possible values are:

• Invalid - Indicates that this sort order is not valid. All Service Fabric enumerations have the invalid type.
• Default - Indicates that the default sort order (as specified in cluster manifest) will be used.
• Numeric - Indicates that forward numeric sort order (UD names sorted as numbers) will be used.
• Lexicographical - Indicates that forward lexicographical sort order (UD names sorted as strings) will be used.
• ReverseNumeric - Indicates that reverse numeric sort order (UD names sorted as numbers) will be used.
• ReverseLexicographical- Indicates that reverse lexicographical sort order (UD names sorted as strings) will be used.

Type:	UpgradeSortOrder
Accepted values:	Invalid, Default, Numeric, Lexicographical, ReverseNumeric, ReverseLexicographical
Position:	4
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TimeoutSec

Specifies the time-out period, in seconds, for the operation.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UnmonitoredAuto

Indicates that the upgrade mode is unmonitored automatic. No health checks are performed and after Service Fabric upgrades an upgrade domain, Service Fabric starts the upgrade of the next upgrade domain irrespective of the cluster health state. This mode is not recommended for production use.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UnmonitoredManual

Indicates that the upgrade mode is unmonitored manual. After Service Fabric upgrades an upgrade domain, it waits for the Resume-ServiceFabricClusterUpgrade cmdlet to explicitly start the upgrade of the next upgrade domain.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-UpgradeDomainTimeoutSec

Specifies the maximum time, in seconds, that Service Fabric can take to upgrade a single upgrade domain. After this period, the upgrade fails.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UpgradeReplicaSetCheckTimeoutSec

Specifies the maximum time that Service Fabric waits for a partition to be in a safe state, if not already in a safe state. Once safety checks pass for all partitions on a node, Service Fabric proceeds with the upgrade on that node.

Type:	UInt32
Position:	3
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UpgradeTimeoutSec

Specifies the maximum time, in seconds, that Service Fabric takes for the entire upgrade. After this period, the upgrade fails.

Type:	UInt32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

None

Outputs

System.Object

Related Links

• Connect-ServiceFabricCluster
• Get-ServiceFabricClusterConnection
• Get-ServiceFabricClusterUpgrade
• Update-ServiceFabricClusterUpgrade
• Resume-ServiceFabricClusterUpgrade
• Remove-ServiceFabricClusterPackage