Move resources across regions in PowerShell

This article explains how to move Azure resources to a different Azure region, using PowerShell in Azure Resource Mover.

In this tutorial, you learn how to:

Verify the following requirements:

Most move resources operations are the same whether using the Azure portal or PowerShell, with a couple of exceptions.

We're using these values in our script examples:

If you don't have an Azure subscription, create a trial subscription before you begin. Then sign in to the Azure portal.

Sign in to your Azure subscription with the Connect-AzAccount -Environment AzureChinaCloud cmdlet:

Connect-AzAccount -Environment AzureChinaCloud -Subscription "<subscription-id>"

The MoveCollection object stores metadata and configuration information about the resources you want to move. To set up a move collection, you do the following:

• Create a resource group for the move collection.
• Register the service provider to the subscription, so that the MoveCollection resource can be created.
• Create the MoveCollection object with managed identity. For the MoveCollection object to access the subscription in which the Resource Mover service is located, it needs a system-assigned managed identity (formerly known as Managed Service Identity (MSI)) that's trusted by the subscription.
• Grant access to the Resource Mover subscription for the managed identity.

1. Register the resource provider Microsoft.Migrate, so that the MoveCollection resource can be created, as follows:

   Register-AzResourceProvider -ProviderNamespace Microsoft.Migrate
   

2. Wait for registration:

   While(((Get-AzResourceProvider -ProviderNamespace Microsoft.Migrate)| where {$_.RegistrationState -eq "Registered" -and $_.ResourceTypes.ResourceTypeName -eq "moveCollections"}|measure).Count -eq 0)
   {
       Start-Sleep -Seconds 5
       Write-Output "Waiting for registration to complete."
   }
   

Create a MoveCollection object, and assign a managed identity to it, as follows:

New-AzResourceMoverMoveCollection -Name "PS-chinaeast-chinanorth-demoRMS"  -ResourceGroupName "RG-MoveCollection-demoRMS" -SourceRegion "chinaeast" -TargetRegion "chinanorth" -Location "chinaeast2" -IdentityType "SystemAssigned"

Output:

Grant the managed identity access to the Resource Mover subscription as follows. You must be the subscription owner.

1. Retrieve identity details from the MoveCollection object.

   $moveCollection = Get-AzResourceMoverMoveCollection -SubscriptionId $subscriptionId -ResourceGroupName "RG-MoveCollection-demoRMS" -Name "PS-chinaeast-chinanorth-demoRMS"
   
   $identityPrincipalId = $moveCollection.IdentityPrincipalId
   

2. Assign the required roles to the identity so Azure Resource Mover can access your subscription to help move resources.

   New-AzRoleAssignment -ObjectId $identityPrincipalId -RoleDefinitionName Contributor -Scope "/subscriptions/$subscriptionId"
   
   New-AzRoleAssignment -ObjectId $identityPrincipalId -RoleDefinitionName "User Access Administrator" -Scope "/subscriptions/$subscriptionId"
   

Retrieve the IDs for existing source resources you want to move. Create the destination resource settings object, then add resources to the move collection.

Add resources as follows:

1. Get the source resource ID:

   Get-AzResource -Name PSDemoVM -ResourceGroupName PSDemoRM
   

   Output

   

2. Create the target resource settings object per the resource you're moving. In our case, it's a VM.

   $targetResourceSettingsObj = New-Object Microsoft.Azure.PowerShell.Cmdlets.ResourceMover.Models.Api202101.VirtualMachineResourceSettings
   

3. Set the resource type and target resource name for the object.

   $targetResourceSettingsObj.ResourceType = "Microsoft.Compute/virtualMachines"
   $targetResourceSettingsObj.TargetResourceName = "PSDemoVM"
   

   Note

   Our target VM has the same name as the VM in the source region. You can choose a different name.

4. Add the source resources to the move collection, using the resource ID and target settings object you retrieved/created.

   Add-AzResourceMoverMoveResource -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS" -SourceId "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx xxxxxxxxxxxx/resourceGroups/
   PSDemoRM/providers/Microsoft.Compute/virtualMachines/PSDemoVM" -Name "PSDemoVM" -ResourceSetting $targetResourceSettingsObj
   

   Output

Check whether the resources you added have any dependencies on other resources, and add as needed.

1. Validate dependencies as follows:

   Resolve-AzResourceMoverMoveCollectionDependency -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"
   

   Output (when dependencies exist)

   

2. Identity missing dependencies:

   • To retrieve a list of all missing dependencies:

     Get-AzResourceMoverUnresolvedDependency -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS" -ResourceGroupName "RG-MoveCollection-demoRMS" -DependencyLevel Descendant
     

     Output

     

   • To retrieve only first-level dependencies (direct dependencies for the resource):

     Get-AzResourceMoverUnresolvedDependency -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS" -ResourceGroupName "RG-MoveCollection-demoRMS" -DependencyLevel Direct
     

     Output

     

3. To add any outstanding missing dependencies, repeat the instructions above to add resources to the move collection, and revalidate until there are no outstanding resources.

You usually need to prepare resources in the source region before the move. For example:

• To move stateless resources such as Azure virtual networks, network adapters, load balancers, and network security groups, you might need to export an Azure Resource Manager template.
• To move stateful resources such as Azure VMs and SQL databases, you might need to start replicating resources from the source to the destination region.

In this tutorial, since we're moving VMs, we need to prepare the source resource group, and then initiate and commit its move, before we can start preparing VMs.

After preparing and moving the source resource group, we can prepare VM resources for the move.

1. Validate the dependencies before you prepare VM resources.

   $resp = Invoke-AzResourceMoverPrepare -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"  -MoveResource $('psdemovm') -ValidateOnly
   

   Output

   

2. Get the dependent resources that need to be prepared along with the VM.

   $resp.AdditionalInfo[0].InfoMoveResource
   

   Output

   

3. Initiate the prepare process for all dependent resources.

   Invoke-AzResourceMoverPrepare -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"  -MoveResource $('PSDemoVM','psdemovm111', 'PSDemoRM-vnet','PSDemoVM-nsg')
   

   Output

   

   Note

   You can provide the source resource ID instead of the resource name as the input parameters for the Prepare cmdlet, as well as in the Initiate Move and Commit cmdlets. To do this, run:

   Invoke-AzResourceMoverPrepare -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS" -MoveResourceInputType MoveResourceSourceId  -MoveResource $('/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/PSDemoRMS/providers/Microsoft.Network/networkSecurityGroups/PSDemoVM-nsg')
   

1. Verify that the VM resources are in an Initiate Move Pending state:

   Get-AzResourceMoverMoveResource  -SubscriptionId " xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx " -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS "   | Where-Object {  $_.MoveStatusMoveState -eq "InitiateMovePending" } | Select Name
   

   Output

   

2. Initiate the move:

   Invoke-AzResourceMoverInitiateMove -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"  -MoveResource $('psdemovm111', 'PSDemoRM-vnet','PSDemoVM-nsg', 'PSDemoVM') -MoveResourceInputType "MoveResourceId"
   

   Output

   

After the initial move, you can decide whether you want to commit the move or discard it.

• Discard: You might discard a move if you're testing, and you don't want to actually move the source resource. Discarding the move returns the resource to a state of Initiate move pending. You can then initiate the move again if needed.
• Commit: Commit completes the move to the target region. After committing, a source resource will be in a state of Delete source pending, and you can decide if you want to delete it.

To discard the move:

Invoke-AzResourceMoverDiscard -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"  -MoveResource $('psdemovm111', 'PSDemoRM-vnet','PSDemoVM-nsg', 'PSDemoVM') -MoveResourceInputType "MoveResourceId"

Output

1. Commit the move as follows:

   Invoke-AzResourceMoverCommit -ResourceGroupName "RG-MoveCollection-demoRMS" -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"  -MoveResource $('psdemovm111', 'PSDemoRM-vnet','PSDemoVM-nsg', 'PSDemoVM') -MoveResourceInputType "MoveResourceId"
   

   Output

   

2. Verify that all resources have moved to the target region:

   Get-AzResourceMoverMoveResource  -ResourceGroupName "RG-MoveCollection-demoRMS " -MoveCollectionName "PS-chinaeast-chinanorth-demoRMS"
   

   All resources are now in a Delete Source Pending state in the target region.

After committing the move, and verifying that resources work as expected in the target region, you can delete each source resource in the Azure portal, using PowerShell, or using Azure CLI.

Learn more about move Azure VMs in the portal.