Edit

Migrate from regional to a zonal Virtual Machine Scale Sets (Preview)

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets

This article describes how to migrate existing VMs in a regional (nonzonal) Virtual Machine Scale Set with Flexible orchestration into specific availability zones while preserving VM names, data disks, and other stateful properties.

Important

Regional to zonal VM migration is currently in Public Preview. Previews are made available to you on the condition that you agree to the supplemental terms of use. Some aspects of this feature may change prior to general availability (GA).

This migration functionality is not yet available in the Azure portal.

Overview

Virtual Machine Scale Sets allow you to combine the scalability of scale sets with the flexibility of individual VMs. If your scale set was originally deployed without availability zones (regional), you can update the scale set to include zones and then migrate the existing VMs into those zones in place.

The migration process involves:

  1. Update the scale set to include availability zones in its configuration
  2. Deallocate each VM in the scale set
  3. Assign each VM to an availability zone
  4. Start each VM in its new zone

Important

  • Each VM must be deallocated before zone assignment. Plan for downtime accordingly.
  • VMs can be started immediately after zone assignment completes.
  • Migration is a one-way operation. You can't migrate a zonal VM back to a regional deployment.

Prerequisites

  • Azure subscription with the migration preview feature registered
  • Contributor role or higher on the resource group containing the scale set
  • Azure CLI 2.72.0 or later, or Azure PowerShell Az module installed
  • An existing regional (nonzonal) Virtual Machine Scale Set with Flexible orchestration mode
  • The target availability zones must support the VM sizes used in the scale set

Register the preview feature

Register the RegionalToZonalVMMigrationForDeallocatedVM preview feature for your subscription:

# Set your subscription context
az account set --subscription "<subscription-name-or-id>"

# Register the migration feature
az feature register --namespace Microsoft.Compute --name RegionalToZonalVMMigrationForDeallocatedVM

# Check registration status
az feature show --namespace Microsoft.Compute --name RegionalToZonalVMMigrationForDeallocatedVM --query properties.state -o tsv

Note

Feature registration may take several minutes to complete. Wait until the state shows Registered before proceeding.

Supported configurations

Migration paths

Source Target Description
Regional VM in a Flexible scale set Zonal VM in a Flexible scale set VM placed in a specific availability zone (1, 2, or 3) while preserving VM name, disks, network config, and scale set membership

Limitations

The following configurations aren't supported for migration:

  • VMs with Basic public IP addresses - Upgrade to Standard SKU before migration
  • VMs behind a Basic Load Balancer - Upgrade to Standard Load Balancer before migration
  • VMs with unmanaged disks - Convert to managed disks before migration

Step 1: Update the scale set to include availability zones

Before migrating individual VMs, update the scale set to include the target availability zones in its configuration. This step doesn't affect running VMs. Only the scale set model is updated so that VMs can be assigned to zones.

az vmss update \
  --resource-group "<resource-group-name>" \
  --name "<scale-set-name>" \
  --set zones='["1","2","3"]'

Note

You can specify any combination of zones (for example, ["1"] or ["1", "3"]), depending on your requirements. Specifying all three zones (["1", "2", "3"]) provides the highest resiliency.

Step 2: Deallocate the VM

Before updating the zone assignment, each VM must be fully deallocated. Repeat this step and the following steps for each VM in the scale set.

Tip

To minimize downtime for applications with multiple VMs, consider migrating VMs in batches. Migrate a subset of VMs, validate application health, and then proceed with the next batch.

az vm deallocate --resource-group "<resource-group-name>" --name "<vm-name>"

Step 3: Update the zone assignment

Assign the VM to a specific availability zone:

az vm update \
  --resource-group "<resource-group-name>" \
  --name "<vm-name>" \
  --set zones='["<target-zone>"]'

Step 4: Start the VM

After zone assignment, the VM is in a Stopped (deallocated) state. Start the VM:

az vm start --resource-group "<resource-group-name>" --name "<vm-name>"

Note

You can start the VM immediately after zone assignment completes.

Repeat Steps 2 through 4 for each VM in the scale set that you want to migrate.

Troubleshooting

Scale set zone update fails

Error: Cannot update zones on the Virtual Machine Scale Set

Solution: Ensure the scale set uses Flexible orchestration mode and that the target zones are available in the scale set's region. Check that none of the VMs in the scale set is currently undergoing another operation.

VM size not available in zone

Error: The requested VM size is not available in the specified location/zone

Solution: Check available VM sizes in the target zone:

az vm list-skus --location "<region>" --zone "<zone>" --resource-type virtualMachines --output table

Consider changing the VM size before migration if the current size isn't available in the target zone.

Insufficient permissions

Error: The client does not have authorization to perform action

Solution: Ensure you have Contributor role or higher on the resource group.

VM zone assignment fails while in scale set

Error: Cannot assign zone to a VM in the specified Virtual Machine Scale Set

Solution: Verify the following:

  • The scale set has been updated to include the target zone
  • The VM is fully deallocated
  • The VM's size is available in the target zone
  • No other operations are running on the scale set
az vmss show \
  --resource-group "<resource-group-name>" \
  --name "<scale-set-name>" \
  --query "{Zones:zones, OrchestrationMode:orchestrationMode}" \
  --output table

Next steps

  • Last updated on