Move a VM from Azure to Azure Stack Hub

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.

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.

  1. 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.

  2. 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                  :
  3. 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.

  4. 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

  1. Sign in to the Azure Stack Hub user portal.

  2. Select Storage Accounts and select an existing storage account or create a new storage account.

  3. Select Blobs in the storage account blade for your storage account. Select Container to create a new container.

  4. Type the name of your container, and then select Blob (anonymous read access for blobs only).

  5. 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.

  6. 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.

  1. 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.

  2. Open PowerShell to use AzCopy from the shell.

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

    azcopy cp "/path/to/file.vhd" "https://[account][container]/[path/to/blob]?[SAS] --blob-type=PageBlob


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.

  1. 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.

  2. In the user portal, select All Services > Disks > Add.

  3. 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.

  4. 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