Edit

Patch the Windows operating system in your Service Fabric cluster

Getting automatic OS image upgrades on your Virtual Machine Scale Sets is the best practice for keeping your operating system patched in Azure. Virtual Machine Scale Set based automatic OS image upgrades will require silver or greater durability on a scale set.

Note

Service Fabric supports Windows Server OS images only through their mainstream support end dates. Service Fabric support for clusters running on Windows Server 2019 ends on March 31, 2027. Plan OS image upgrades to a supported Windows Server version (such as Windows Server 2025) ahead of that date. While Azure Virtual Machine Scale Sets running Windows Server 2019 continue to operate after March 31, 2027, they're not supported by Service Fabric.

Requirements for automatic OS image upgrades by Virtual Machine Scale Sets

  • Service Fabric durability level is Silver or Gold, and not Bronze.
  • The Service Fabric extension on the scale set model definition must have TypeHandlerVersion 1.1 or above.
  • Durability level should be the same at the Service Fabric cluster and Service Fabric extension on the scale set model definition.
  • An additional health probe or use of application health extension for Virtual Machine Scale Sets isn't required.
  • Stateless nodetypes are the only exception, which have durability as Bronze, but automatic OS image upgrades can still be configured on them. For more information, see Deploy an Azure Service Fabric cluster with stateless-only node types.
  • While Azure Virtual Machine Scale Sets running Windows Server 2019 will continue to operate after March 31, 2027, those clusters won't be supported by Service Fabric. Set the scale set image reference to a supported Windows Server version to remain within support.

Ensure that durability settings aren't mismatched on the Service Fabric cluster and Service Fabric extension, as a mismatch will result in upgrade errors. Durability levels can be modified per the guidelines outlined on this page.

With Bronze durability, automatic OS image upgrade isn't available. While Patch Orchestration Application (intended only for non-Azure hosted clusters) isn't recommended* for Silver or greater durability levels, it is your only option to automate Windows updates with respect to Service Fabric upgrade domains.

If you want to switch from Patch Orchestration Application to automatic OS image upgrade, you must first deprecate the use of Patch Orchestration Application.

Enable auto OS upgrades and disable Windows Update

When enabling automatic OS updates, you'll also need to disable Windows Update in the deployment template. Once you deploy these changes, all machines in the scale set will be reimaged and the scale set will be enabled for automatic updates. Automatic OS image upgrades can also be used as part of a controlled node-type scale-out/scale-in process to move to newer Windows Server versions without impacting application availability. The documented upgrade steps for moving from Windows Server 2019 to Windows Server 2022 apply equally when upgrading to Windows Server 2025 images. When configuring automatic OS image upgrades, verify that the chosen marketplace or custom image is a supported Windows Server version to ensure continued Service Fabric support.

Important

Service Fabric doesn't support in-VM upgrades where Windows Updates applies operating system patches without replacing the OS disk.

Note

When managed disks are used ensure that Custom Extension script for mapping managed disks to drive letters handles reimage of the VM correctly. See Create a Service Fabric cluster with attached data disks for an example script that handles reimage of VMs with managed disks correctly.

  1. Enable automatic OS image upgrades and disable Windows Updates in the deployment template:

    "properties": {
   "upgradePolicy": {
     "mode": "Automatic",
      "automaticOSUpgradePolicy": {
        "enableAutomaticOSUpgrade": true
      }
    }
}

    "osProfile": { 
   "windowsConfiguration": { 
     "enableAutomaticUpdates": false 
    }
}

    Update-AzVmss -ResourceGroupName $resourceGroupName -VMScaleSetName $scaleSetName -AutomaticOSUpgrade $true -EnableAutomaticUpdate $false

  2. Update the scale set model. After this configuration change, a reimage of all machines is needed to update the scale set model for the change to take effect:

    $scaleSet = Get-AzVmssVM -ResourceGroupName $resourceGroupName -VMScaleSetName $scaleSetName
$instances = foreach($vm in $scaleSet)
{
    Set-AzVmssVM -ResourceGroupName $resourceGroupName -VMScaleSetName $scaleSetName -InstanceId $vm.InstanceID -Reimage
}

Next steps

Learn how to enable automatic OS image upgrades on Virtual Machine Scale Sets.

To upgrade cluster node types to a newer Windows Server version using the scale-out/scale-in approach, see Scale up a Service Fabric cluster primary node type and Scale up a Service Fabric cluster non-primary node type. These same steps apply when upgrading to Windows Server 2025 images.

  • Last updated on