Move a generalized VM from on-premises to Azure Stack Hub

Article
09/02/2022

Caution

This article references CentOS, a Linux distribution that is nearing End Of Life (EOL) status. Please consider your use and plan accordingly. For more information, see the CentOS End Of Life guidance.

You can add a virtual machine (VM) image from your on-premises environment. You can create your image as a virtual hard disk (VHD) and upload the image to a storage account in your Azure Stack Hub instance. You can then create a VM from the VHD.

A generalized disk image is one that has been prepared with Sysprep to remove any unique information (such as user accounts), enabling it to be reused to create multiple VMs. Generalized VHDs are a good fit for when are creating images that the Azure Stack Hub cloud operator plans to use as marketplace items.

How to move an image

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

Windows VM
Linux VM

Follow the steps in Prepare a Windows VHD or VHDX to upload to Azure to correctly generalize your VHD prior to uploading. You must use a VHD for Azure Stack Hub.

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 image in Azure Stack Hub

Sign in to the Azure Stack Hub user portal.

If you are a cloud operator creating a platform image, 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 > Images > Add.
In Create image:
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 an OS type that matches your image.
6. Select Browse and then navigate to your Storage account, container, and VHD. Choose Select.
7. 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.
8. Select Read/write for host catching.
9. Select Create.
Once the image is created, use the image to create a new VM.

Next steps

Move a VM to Azure Stack Hub Overview