Move a VM from Azure to Azure Stack Hub

Article
07/29/2022

You can upload a virtual hard drive (VHD) from a virtual machine (VM) created in Azure to your Azure Stack Hub instance.

Prepare and download your VHD from Azure

Find the section that that is specific to your needs when preparing your VHD.

Follow the steps in the article Create a Windows VM from a specialized disk by using PowerShell to prepare the VHD.
To deploy VM extensions, make sure that the VM agent .msi available.
For information and steps, see Azure Virtual Machine Agent overview. Make sure the extension is installed on the VM before your move VM. If the VM agent is not present in the VHD, extension deployment will fail. You do not need to set the OS profile while provisioning, or set $vm.OSProfile.AllowExtensionOperations = $true.

Follow the instructions in Download a Windows VHD from Azure to correctly generalize and download the VHD before moving it to Azure Stack Hub.
When you provision the VM on Azure, use PowerShell. Prepare it without the -ProvisionVMAgent flag.
Remove all VM extensions using the cmdlet from the VM before generalizing the VM in Azure. You can find which VM extensions are installed by going to Windows (C:) > WindowsAzure > Logs > Plugins.

Use the Az PowerShell module:

Remove-AzVMExtension -ResourceGroupName winvmrg1 -VMName windowsvm -Name "CustomScriptExtension"

Use the AzureRM PowerShell module:

Remove-AzureRmVMExtension -ResourceGroupName winvmrg1 -VMName windowsvm -Name "CustomScriptExtension"

Follow the instructions in Download a Windows VHD from Azure to correctly generalize and download the VHD before moving it to Azure Stack Hub.

Before downloading your Linux VM, follow the guidance in the "Prepare VM" section of the article Create a Linux VM from a custom disk with the Azure CLI
Follow the steps in the article Download a Linux VHD from Azure to prepare and download the VHD.
For a specialized VHD, make sure to use "attach" semantics using -CreateOption Attach. You can find an example in the article Create a virtual machine using an existing managed OS disk with PowerShell (Windows).

Stop the waagent service:
```
sudo waagent -force -deprovision
export HISTSIZE=0
logout
```
The Azure Linux Agent versions that work with Azure Stack Hub are documented here. Make sure that the image on which you have run sysprep has an Azure Linux agent version that is compatible with Azure Stack Hub.
Stop deallocate the VM.
Download the VHD.
1. To download the VHD file, generate a shared access signature (SAS) URL. When the URL is generated, an expiration time is assigned to the URL.
2. On the menu of the blade for the VM, select Disks.
3. Select the operating system disk for the VM, and then select Disk Export.
4. Set the expiration time of the URL to 36000.
5. Select Generate URL.
6. Generate the URL.
7. Under the URL that was generated, select Download the VHD file.
8. You might need to select Save in the browser to start the download. The default name for the VHD file is abcd.
9. You can now move this VHD to Azure Stack Hub.

Important

You can find a script in the article Sample script to upload a VHD to Azure and create a new VM to upload the VHD to an Azure Stack Hub user storage account and create a VM. Make sure to provide $urlOfUploadedImageVhd as the Azure Stack Hub storage account+container URL. For a generalized VHD, make sure to use FromImage value when setting -CreateOption FromImage.

Verify your VHD

Before uploading your VHD, you must validate that the VHD meets the requirements. VHDs that don't meet the requirements will fail to load in Azure Stack Hub.

You will use the PowerShell modules found with Hyper-V. Activating Hyper-V installs supporting PowerShell modules. You can check that you have the module by opening PowerShell with an elevated prompt and running the following cmdlet:
```
Get-Command -Module hyper-v
```
If you do not have the Hyper-V commands, see, see Working with Hyper-V and Windows PowerShell.

Get the path to your VHD on your machine. Run the following cmdlet:

get-vhd <path-to-your-VHD>

The cmdlet will return the VHD object and display the attributes, such as:

ComputerName            : YOURMACHINENAME
Path                    : <path-to-your-VHD>
VhdFormat               : VHD
VhdType                 : Fixed
FileSize                : 68719477248
Size                    : 68719476736
MinimumSize             : 32212254720
LogicalSectorSize       : 512
PhysicalSectorSize      : 512
BlockSize               : 0
ParentPath              :
DiskIdentifier          : 3C084D21-652A-4C0E-B2D1-63A8E8E64C0C
FragmentationPercentage : 0
Alignment               : 1
Attached                : False
DiskNumber              :
IsPMEMCompatible        : False
AddressAbstractionType  : None
Number                  :

With the VHD object, check that meets the requirements for Azure Stack Hub.
In addition, Azure Stack Hub only supports images from generation one (1) VMs.
If your VHD is not compatible with Azure Stack Hub, you will need to return to the source image and Hyper-V, create a VHD that meets the requirements, and upload. To minimize possible corruption in the upload process, use AzCopy.

How to fix your VHD

The following requirements must be met for compatibility of your VHD with Azure Stack Hub.

VHD is of fixed type

Identify: Use get-vhd cmdlet to get the VHD object.
Fix: You can convert a VHDX file to VHD, convert a dynamically expanding disk to a fixed-size disk, but you can't change a VM's generation. Use Hyper-V Manager or PowerShell to convert the disk.

VHD has minimum virtual size of at least 20 MB

Identify: Use get-vhd cmdlet to get the VHD object.
Fix: Use Hyper-V Manager or PowerShell to resize the disk.

VHD is aligned

Identify: Use get-vhd cmdlet to get the VHD object.
Fix: The virtual size must be a multiple of one (1) MB.

Disks must have a virtual size aligned to 1 MiB. If your VHD is a fraction of 1 MiB, you'll need to resize the disk to a multiple of 1 MiB. Disks that are fractions of a MiB cause errors when creating images from the uploaded VHD. To verify the size you can use the PowerShell Get-VHD cmdlet to show "Size", which must be a multiple of 1 MiB in Azure, and "FileSize", which will be equal to "Size" plus 512 bytes for the VHD footer.

Use Hyper-V Manager or PowerShell to resize the disk.

VHD blob length

Identify: Use the get-vhd cmdlet to show Size
Fix: The VHD blob length = virtual size + vhd footer length (512). A small footer at the end of the blob describes the properties of the VHD. Size must be a multiple of 1 MiB in Azure, and FileSize, which will be equal to Size + 512 bytes for the VHD footer.

Use Hyper-V Manager or PowerShell to resize the disk.

Generation one VMs

Identify: To confirm if your virtual machine is Generation 1, use the cmdlet Get-VM | Format-Table Name, Generation.
Fix: You will need to recreate your VM in your hypervisor (Hyper-V).

Upload to a storage account

You can upload your VHD with the portal, or with the container you created in the portal, use AzCopy.

Portal to generate SAS URL and upload VHD

Sign in to the Azure Stack Hub user portal.
Select Storage Accounts and select an existing storage account or create a new storage account.
Select Blobs in the storage account blade for your storage account. Select Container to create a new container.
Type the name of your container, and then select Blob (anonymous read access for blobs only).
If you are going to use AzCopy to upload your image rather than the portal, create a SAS token. Select Shared access signature in the storage account, and then select Generate SAS and connection string. Copy and make a note of the Blob service SAS URL. You will use this URL when using AzCopy to upload your VHD.
Select your container and then select Upload. Upload your VHD.

AzCopy VHD

Use Azure Storage Explorer or AzCopy to reduce that chance that your VHD will be corrupted in the upload process, and your upload will be faster. The following steps use AzCopy on a Windows 10 machine. AzCopy is a command-line utility that you can use to copy blobs or files to or from a storage account.

If you don't have AzCopy installed, install AzCopy. You find find instruction to download and get started with AzCopy in the article Get started with AzCopy. Make a note of where you store the binary. You can add AzCopy to your path to use it from the PowerShell command line.
Open PowerShell to use AzCopy from the shell.

Use AzCopy to upload your VHD into the your container in the storage account.

set AZCOPY_DEFAULT_SERVICE_API_VERSION=2017-11-09
azcopy cp "/path/to/file.vhd" "https://[account].blob.core.windows.net/[container]/[path/to/blob]?[SAS] --blob-type=PageBlob

Note

Upload your VHD using syntax similar to uploading a single file to virtual directory. Add --blob-type=PageBlob to make sure that the VHD is uploaded as a Page Blob, instead of Block by default.

For more information about using AzCopy and other storage tools, see Use data transfer tools in Azure Stack Hub Storage.

Create the VM

Custom images come in two forms: specialized and generalized.

Specialized
Generalized

Sign in to the Azure Stack Hub user portal.

If you are a cloud operator creating a platform disk, follow the instructions in Add a platform image to add the VHD through the administrator portal or with the administrator endpoints.
In the user portal, select All Services > Disks > Add.
In Create managed disk:
1. Type the Name of your image.
2. Select your Subscription.
3. Create or add the image to a Resource group.
4. Select the Location, also referred to as the region, of your ASDK.
5. Select the Account type.
  - Premium disks (SSD) are backed by solid-state drives and offer consistent, low-latency performance. They provide the best balance between price and performance, and are ideal for I/O-intensive applications and production workloads.
  - Standard disks (HDD) are backed by magnetic drives and are preferable for applications where data is accessed infrequently. Zone-redundant disks are backed by Zone redundant storage (ZRS) that replicates your data across multiple zones and are available even if a single zone is down.
6. Select Storage blob your Source type. You are created a disk from a blob in a storage account.
7. For the VHD source select:
  1. The Source subscription where the storage account is located.
  2. Select Browse and then navigate to your Storage account, container, and VHD. Choose Select.
  3. Select the OS Type that matches the VHD.
8. Select a disk Size (GiB) that the size of or larger than your VHD.
9. Select Create.
Once the disk is created, you can use the disk to create a new VM.

Next steps

Move a VM to Azure Stack Hub Overview