--- title: "Start upgrading the code or configuration version of a Service Fabric cluster." method: POST path: "/$/Upgrade" tags: ["Cluster"] --- # Start upgrading the code or configuration version of a Service Fabric cluster. `POST /$/Upgrade` Validate the supplied upgrade parameters and start upgrading the code or configuration version of a Service Fabric cluster if the parameters are valid. ## Query parameters - `api-version` '6.0', required - `timeout` integer ## Request body - StartClusterUpgradeDescription — Describes the parameters for starting a cluster upgrade. - `CodeVersion` string — The cluster code version. - `ConfigVersion` string — The cluster configuration version. - `UpgradeKind` 'Invalid' | 'Rolling' — The kind of upgrade out of the following possible values. - `RollingUpgradeMode` 'Invalid' | 'UnmonitoredAuto' | 'UnmonitoredManual' | 'Monitored' — The mode used to monitor health during a rolling upgrade. The values are UnmonitoredAuto, UnmonitoredManual, and Monitored. - `UpgradeReplicaSetCheckTimeoutInSeconds` integer — The maximum amount of time to block processing of an upgrade domain and prevent loss of availability when there are unexpected issues. When this timeout expires, processing of the upgrade domain will proceed regardless of availability loss issues. The timeout is reset at the start of each upgrade domain. Valid values are between 0 and 42949672925 inclusive. (unsigned 32-bit integer). - `ForceRestart` boolean — If true, then processes are forcefully restarted during upgrade even when the code version has not changed (the upgrade only changes configuration or data). - `SortOrder` 'Invalid' | 'Default' | 'Numeric' | 'Lexicographical' | 'ReverseNumeric' | 'ReverseLexicographical' — Defines the order in which an upgrade proceeds through the cluster. - `MonitoringPolicy` MonitoringPolicyDescription — Describes the parameters for monitoring an upgrade in Monitored mode. - `FailureAction` 'Invalid' | 'Rollback' | 'Manual' — The compensating action to perform when a Monitored upgrade encounters monitoring policy or health policy violations. Invalid indicates the failure action is invalid. Rollback specifies that the upgrade will start rolling back automatically. Manual indicates that the upgrade will switch to UnmonitoredManual upgrade mode. - `HealthCheckWaitDurationInMilliseconds` string — The amount of time to wait after completing an upgrade domain before applying health policies. It is first interpreted as a string representing an ISO 8601 duration. If that fails, then it is interpreted as a number representing the total number of milliseconds. - `HealthCheckStableDurationInMilliseconds` string — The amount of time that the application or cluster must remain healthy before the upgrade proceeds to the next upgrade domain. It is first interpreted as a string representing an ISO 8601 duration. If that fails, then it is interpreted as a number representing the total number of milliseconds. - `HealthCheckRetryTimeoutInMilliseconds` string — The amount of time to retry health evaluation when the application or cluster is unhealthy before FailureAction is executed. It is first interpreted as a string representing an ISO 8601 duration. If that fails, then it is interpreted as a number representing the total number of milliseconds. - `UpgradeTimeoutInMilliseconds` string — The amount of time the overall upgrade has to complete before FailureAction is executed. It is first interpreted as a string representing an ISO 8601 duration. If that fails, then it is interpreted as a number representing the total number of milliseconds. - `UpgradeDomainTimeoutInMilliseconds` string — The amount of time each upgrade domain has to complete before FailureAction is executed. It is first interpreted as a string representing an ISO 8601 duration. If that fails, then it is interpreted as a number representing the total number of milliseconds. - `ClusterHealthPolicy` ClusterHealthPolicy — Defines a health policy used to evaluate the health of the cluster or of a cluster node. - `ConsiderWarningAsError` boolean — Indicates whether warnings are treated with the same severity as errors. - `MaxPercentUnhealthyNodes` integer — The maximum allowed percentage of unhealthy nodes before reporting an error. For example, to allow 10% of nodes to be unhealthy, this value would be 10. The percentage represents the maximum tolerated percentage of nodes that can be unhealthy before the cluster is considered in error. If the percentage is respected but there is at least one unhealthy node, the health is evaluated as Warning. The percentage is calculated by dividing the number of unhealthy nodes over the total number of nodes in the cluster. The computation rounds up to tolerate one failure on small numbers of nodes. Default percentage is zero. In large clusters, some nodes will always be down or out for repairs, so this percentage should be configured to tolerate that. - `MaxPercentUnhealthyApplications` integer — The maximum allowed percentage of unhealthy applications before reporting an error. For example, to allow 10% of applications to be unhealthy, this value would be 10. The percentage represents the maximum tolerated percentage of applications that can be unhealthy before the cluster is considered in error. If the percentage is respected but there is at least one unhealthy application, the health is evaluated as Warning. This is calculated by dividing the number of unhealthy applications over the total number of application instances in the cluster, excluding applications of application types that are included in the ApplicationTypeHealthPolicyMap. The computation rounds up to tolerate one failure on small numbers of applications. Default percentage is zero. - `ApplicationTypeHealthPolicyMap` ApplicationTypeHealthPolicyMapItem[] — Defines a map with max percentage unhealthy applications for specific application types. Each entry specifies as key the application type name and as value an integer that represents the MaxPercentUnhealthyApplications percentage used to evaluate the applications of the specified application type. The application type health policy map can be used during cluster health evaluation to describe special application types. The application types included in the map are evaluated against the percentage specified in the map, and not with the global MaxPercentUnhealthyApplications defined in the cluster health policy. The applications of application types specified in the map are not counted against the global pool of applications. 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 MaxPercentUnhealthyApplications 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. - `Key` string, required — The key of the application type health policy map item. This is the name of the application type. - `Value` integer, required — The value of the application type health policy map item. The max percent unhealthy applications allowed for the application type. Must be between zero and 100. - `NodeTypeHealthPolicyMap` NodeTypeHealthPolicyMapItem[] — Defines a map with max percentage unhealthy nodes for specific node types. Each entry specifies as key the node type name and as value an integer that represents the MaxPercentUnhealthyNodes percentage used to evaluate the nodes of the specified node type. The node type health policy map can be used during cluster health evaluation to describe special node types. They are evaluated against the percentages associated with their node type name in the map. Setting this has no impact on the global pool of nodes used for MaxPercentUnhealthyNodes. The node type health policy map is used only if the cluster manifest enables node type health evaluation using the configuration entry for HealthManager/EnableNodeTypeHealthEvaluation. For example, given a cluster with many nodes of different types, with important work hosted on node type "SpecialNodeType" that should not tolerate any nodes down. You can specify global MaxPercentUnhealthyNodes to 20% to tolerate some failures for all nodes, but for the node type "SpecialNodeType", set the MaxPercentUnhealthyNodes to 0 by setting the value in the key value pair in NodeTypeHealthPolicyMapItem. The key is the node type name. This way, as long as no nodes of type "SpecialNodeType" are in Error state, even if some of the many nodes in the global pool are in Error state, but below the global unhealthy percentage, the cluster would be evaluated to Warning. A Warning health state does not impact cluster upgrade or other monitoring triggered by Error health state. But even one node of type SpecialNodeType in Error would make cluster unhealthy (in Error rather than Warning/Ok), which triggers rollback or pauses the cluster upgrade, depending on the upgrade configuration. Conversely, setting the global MaxPercentUnhealthyNodes to 0, and setting SpecialNodeType's max percent unhealthy nodes to 100, with one node of type SpecialNodeType in Error state would still put the cluster in an Error state, since the global restriction is more strict in this case. - `Key` string, required — The key of the node type health policy map item. This is the name of the node type. - `Value` integer, required — The value of the node type health policy map item. If the percentage is respected but there is at least one unhealthy node in the node type, the health is evaluated as Warning. The percentage is calculated by dividing the number of unhealthy nodes over the total number of nodes in the node type. The computation rounds up to tolerate one failure on small numbers of nodes. The max percent unhealthy nodes allowed for the node type. Must be between zero and 100. - `EnableDeltaHealthEvaluation` boolean — When true, enables delta health evaluation rather than absolute health evaluation after completion of each upgrade domain. - `ClusterUpgradeHealthPolicy` ClusterUpgradeHealthPolicyObject — Defines a health policy used to evaluate the health of the cluster during a cluster upgrade. - `MaxPercentDeltaUnhealthyNodes` integer — The maximum allowed percentage of nodes health degradation allowed during cluster upgrades. The delta is measured between the state of the nodes at the beginning of upgrade and the state of the nodes at the time of the health evaluation. The check is performed after every upgrade domain upgrade completion to make sure the global state of the cluster is within tolerated limits. The default value is 10%. - `MaxPercentUpgradeDomainDeltaUnhealthyNodes` integer — The maximum allowed percentage of upgrade domain nodes health degradation allowed during cluster upgrades. The delta is measured between the state of the upgrade domain nodes at the beginning of upgrade and the state of the upgrade domain nodes at the time of the health evaluation. The check is performed after every upgrade domain upgrade completion for all completed upgrade domains to make sure the state of the upgrade domains is within tolerated limits. The default value is 15%. - `ApplicationHealthPolicyMap` ApplicationHealthPolicies — Defines the application health policy map used to evaluate the health of an application or one of its children entities. - `ApplicationHealthPolicyMap` ApplicationHealthPolicyMapItem[] — Defines a map that contains specific application health policies for different applications. Each entry specifies as key the application name and as value an ApplicationHealthPolicy used to evaluate the application health. If an application is not specified in the map, the application health evaluation uses the ApplicationHealthPolicy found in its application manifest or the default application health policy (if no health policy is defined in the manifest). The map is empty by default. - `Key` string, required — The name of the application, including the 'fabric:' URI scheme. - `Value` ApplicationHealthPolicy, required — Defines a health policy used to evaluate the health of an application or one of its children entities. - `ConsiderWarningAsError` boolean — Indicates whether warnings are treated with the same severity as errors. - `MaxPercentUnhealthyDeployedApplications` integer — The maximum allowed percentage of unhealthy deployed applications. Allowed values are Byte values from zero to 100. The percentage represents the maximum tolerated percentage of deployed applications that can be unhealthy before the application is considered in error. This is calculated by dividing the number of unhealthy deployed applications over the number of nodes where the application is currently deployed on in the cluster. The computation rounds up to tolerate one failure on small numbers of nodes. Default percentage is zero. - `DefaultServiceTypeHealthPolicy` ServiceTypeHealthPolicy — Represents the health policy used to evaluate the health of services belonging to a service type. - `MaxPercentUnhealthyPartitionsPerService` integer — The maximum allowed percentage of unhealthy partitions per service. Allowed values are Byte values from zero to 100 The percentage represents the maximum tolerated percentage of partitions that can be unhealthy before the service is considered in error. If the percentage is respected but there is at least one unhealthy partition, the health is evaluated as Warning. The percentage is calculated by dividing the number of unhealthy partitions over the total number of partitions in the service. The computation rounds up to tolerate one failure on small numbers of partitions. Default percentage is zero. - `MaxPercentUnhealthyReplicasPerPartition` integer — The maximum allowed percentage of unhealthy replicas per partition. Allowed values are Byte values from zero to 100. The percentage represents the maximum tolerated percentage of replicas that can be unhealthy before the partition is considered in error. If the percentage is respected but there is at least one unhealthy replica, the health is evaluated as Warning. The percentage is calculated by dividing the number of unhealthy replicas over the total number of replicas in the partition. The computation rounds up to tolerate one failure on small numbers of replicas. Default percentage is zero. - `MaxPercentUnhealthyServices` integer — The maximum allowed percentage of unhealthy services. Allowed values are Byte values from zero to 100. The percentage represents the maximum tolerated percentage of services that can be unhealthy before the application is considered in error. If the percentage is respected but there is at least one unhealthy service, the health is evaluated as Warning. This is calculated by dividing the number of unhealthy services of the specific service type over the total number of services of the specific service type. The computation rounds up to tolerate one failure on small numbers of services. Default percentage is zero. - `ServiceTypeHealthPolicyMap` ServiceTypeHealthPolicyMapItem[] — Defines a ServiceTypeHealthPolicy per service type name. The entries in the map replace the default service type health policy for each specified service type. For example, in an application that contains both a stateless gateway service type and a stateful engine service type, the health policies for the stateless and stateful services can be configured differently. With policy per service type, there's more granular control of the health of the service. If no policy is specified for a service type name, the DefaultServiceTypeHealthPolicy is used for evaluation. - `Key` string, required — The key of the service type health policy map item. This is the name of the service type. - `Value` ServiceTypeHealthPolicy, required — Represents the health policy used to evaluate the health of services belonging to a service type. - `MaxPercentUnhealthyPartitionsPerService` integer — The maximum allowed percentage of unhealthy partitions per service. Allowed values are Byte values from zero to 100 The percentage represents the maximum tolerated percentage of partitions that can be unhealthy before the service is considered in error. If the percentage is respected but there is at least one unhealthy partition, the health is evaluated as Warning. The percentage is calculated by dividing the number of unhealthy partitions over the total number of partitions in the service. The computation rounds up to tolerate one failure on small numbers of partitions. Default percentage is zero. - `MaxPercentUnhealthyReplicasPerPartition` integer — The maximum allowed percentage of unhealthy replicas per partition. Allowed values are Byte values from zero to 100. The percentage represents the maximum tolerated percentage of replicas that can be unhealthy before the partition is considered in error. If the percentage is respected but there is at least one unhealthy replica, the health is evaluated as Warning. The percentage is calculated by dividing the number of unhealthy replicas over the total number of replicas in the partition. The computation rounds up to tolerate one failure on small numbers of replicas. Default percentage is zero. - `MaxPercentUnhealthyServices` integer — The maximum allowed percentage of unhealthy services. Allowed values are Byte values from zero to 100. The percentage represents the maximum tolerated percentage of services that can be unhealthy before the application is considered in error. If the percentage is respected but there is at least one unhealthy service, the health is evaluated as Warning. This is calculated by dividing the number of unhealthy services of the specific service type over the total number of services of the specific service type. The computation rounds up to tolerate one failure on small numbers of services. Default percentage is zero. - `InstanceCloseDelayDurationInSeconds` integer — Duration in seconds, to wait before a stateless instance is closed, to allow the active requests to drain gracefully. This would be effective when the instance is closing during the application/cluster upgrade, only for those instances which have a non-zero delay duration configured in the service description. See InstanceCloseDelayDurationSeconds property in $ref: "#/definitions/StatelessServiceDescription.yaml" for details. Note, the default value of InstanceCloseDelayDurationInSeconds is 4294967295, which indicates that the behavior will entirely depend on the delay configured in the stateless service description. ## Response `202` A successful response means that the cluster code or configuration upgrade has started. Use GetUpgradeProgress operation to get the status of the upgrade. ## Other responses - `default` — The detailed error response. --- [API](https://skmtc.net/azure/apis/servicefabric-servicefabric.md) · [All operations](https://skmtc.net/azure/apis/servicefabric-servicefabric/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/servicefabric-servicefabric/revisions/8fd479ce0f16/schema)