Create Azure Stack HCI VM image using image in Azure Storage account

Applies to: Azure Stack HCI, version 23H2

This article describes how to create virtual machine (VM) images for your Azure Stack HCI using source images from Azure Storage account. You can create VM images using the Azure portal or Azure CLI and then use these VM images to create Arc VMs on your Azure Stack HCI.

Prerequisites

Before you begin, make sure that the following prerequisites are completed.

Azure CLI

• Make sure to review and complete the prerequisites.

• For custom images in Azure Storage account, you have the following extra prerequisites:

  • You should have a VHD loaded in your Azure Storage account. See how to Upload a VHD image in your Azure Storage account.
  • If using a VHDX:
    • The VHDX image must be Gen 2 type and secure boot enabled.
    • The VHDX image must be prepared using sysprep /generalize /shutdown /oobe. For more information, see Sysprep command-line options.

• If using a client to connect to your Azure Stack HCI cluster, see Connect to Azure Stack HCI via Azure CLI client.

• Make sure that you have Storage Blob Data Contributor role on the Storage account that you use for the image. For more information, see Assign an Azure role for access to blob data.

• Make sure that you're uploading your VHD or VHDX as a page blob image into the Storage account. Only page blob images are supported to create VM images via the Storage account.

Azure portal

• Make sure to review and complete the prerequisites.

• For custom images in Azure Storage account, you have the following extra prerequisites:

  • You should have a VHD loaded in your Azure Storage account. See how to Upload a VHD image in your Azure Storage account.
  • If using a VHDX:
    • The VHDX image must be Gen 2 type and secure boot enabled.
    • The VHDX image must be prepared using sysprep /generalize /shutdown /oobe. For more information, see Sysprep command-line options.

Add VM image from Azure Storage account

You create a VM image starting from an image in Azure Storage account and then use this image to deploy VMs on your Azure Stack HCI cluster.

Azure CLI

Follow these steps to create a VM image using the Azure CLI.

Sign in and set subscription

1. Connect to a server on your Azure Stack HCI system.

2. Sign in. Type:

   az login --use-device-code
   

3. Set your subscription.

   az account set --subscription <Subscription ID>
   

Set some parameters

1. Set your subscription, resource group, location, path to the image in local share, and OS type for the image. Replace the parameters in < > with the appropriate values.

$subscription = "<Subscription ID>"
$resource_group = "<Resource group>"
$location = "<Location for your Azure Stack HCI cluster>"
$osType = "<OS of source image>"
$imageName = "<VM image name>"
$imageSourcePath = "<path to the source image in the Storage account>"

The parameters are described in the following table:

Parameter	Description
subscription	Resource group for Azure Stack HCI cluster that you associate with this image.
resource_group	Resource group for Azure Stack HCI cluster that you associate with this image.
location	Location for your Azure Stack HCI cluster. For example, this could be eastus.
imageName	Name of the VM image created starting with the image in your local share. Note: Azure rejects all the names that contain the keyword Windows.
imageSourcePath	Path to the Blob SAS URL of the image in the Storage account. For more information, see instructions on how to Get a blob SAS URL of the image in the Storage account. Note: Make sure that all the Ampersands in the path are escaped with double quotes and the entire path string is wrapped within single quotes.
os-type	Operating system associated with the source image. This can be Windows or Linux.

Here's a sample output:

PS C:\Users\azcli> $subscription = "<Subscription ID>"
PS C:\Users\azcli> $resource_group = "myhci-rg"
PS C:\Users\azcli> $location = "eastus"
PS C:\Users\azcli> $osType = "Windows"
PS C:\Users\azcli> $imageName = "myhci-storacctimage"
PS C:\Users\azcli> $imageSourcePath = 'https://vmimagevhdsa1.blob.core.windows.net/vhdcontainer/Windows_InsiderPreview_ServerStandard_en-us_VHDX_25131.vhdx?sp=r"&"st=2022-08-05T18:41:41Z"&"se=2022-08-06T02:41:41Z"&"spr=https"&"sv=2021-06-08"&"sr=b"&"sig=X7A98cQm%2FmNRaHmTbs9b4OWVv%2F9Q%2FJkWDBHVPyAc8jo%3D'

Create VM image from image in Azure Storage account

1. Select a custom location to deploy your VM image. The custom location should correspond to the custom location for your Azure Stack HCI cluster. Get the custom location ID for your Azure Stack HCI cluster. Run the following command:

   $customLocationID=(az customlocation show --resource-group $resource_group --name "<custom location name for HCI cluster>" --query id -o tsv)
   

2. Create the VM image starting with a specified marketplace image. Make sure to specify the offer, publisher, sku and version for the marketplace image.

   az stack-hci-vm image create --subscription $subscription --resource-group $resource_Group --custom-location $customLocationID --location $location --name $imageName --os-type $osType --image-path $imageSourcePath --storage-path-id $storagepathid
   

   A deployment job starts for the VM image.

   In this example, the storage path was specified using the --storage-path-id flag and that ensured that the workload data (including the VM, VM image, non-OS data disk) is placed in the specified storage path.

   If the flag is not specified, the workload data is automatically placed in a high availability storage path.

The image deployment takes a few minutes to complete. The time taken to download the image depends on the size of the image in Azure Storage account and the network bandwidth available for the download.

Here's a sample output:

PS > $customLocationID=(az customlocation show --resource-group $resource_group --name "myhci-cl" --query id -o tsv)
PS C:\Users\azcli> az stack-hci-vm image create --subscription $subscription --resource-group $resource_Group --custom-location $customLocationID --location $location --name $imageName --os-type $osType --image-path $imageSourcePath --storage-path-id $storagepathid
Command group 'stack-hci-vm' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "extendedLocation": {
    "name": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.ExtendedLocation/customLocations/myhci-cl",
    "type": "CustomLocation"
  },
  "id": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.AzureStackHCI/galleryimages/myhci-storacctimage",
  "location": "eastus",
  "name": "windos",
  "properties": {
    "identifier": null,
    "imagePath": null,
    "osType": "Windows",
    "provisioningState": "Succeeded",
    "status": {
      "downloadStatus": {
        "downloadSizeInMB": 7876
      },
        "progressPercentage": 100,
      "provisioningStatus": {
        "operationId": "cdc9c9a8-03a1-4fb6-8738-7a8550c87fd1*31CE1EA001C4B3E38EE29B78ED1FD47CCCECF78B4CEA9E9A85C0BAEA5F6D80CA",
        "status": "Succeeded"
      }
    },
    "storagepathId": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.AzureStackHCI/storagecontainers/myhci-storagepath",
    "version": null
  },
  "resourceGroup": "myhci-rg",
  "systemData": {
    "createdAt": "2023-11-03T20:17:10.971662+00:00",
    "createdBy": "guspinto@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-11-03T21:08:01.190475+00:00",
    "lastModifiedBy": "319f651f-7ddb-4fc6-9857-7aef9250bd05",
    "lastModifiedByType": "Application"
  },
  "tags": null,
  "type": "microsoft.azurestackhci/galleryimages"
}
PS C:\Users\azcli>

Azure portal

Follow these steps to create a VM image using the Azure portal. In the Azure portal of your Azure Stack HCI cluster resource, take the following steps:

1. Go to Resources > VM images.

2. Select + Add VM Image and from the dropdown list, select Add VM image from Azure Storage Account.

   

3. In the Create an image page, on the Basics tab, input the following information:

   1. Subscription Select a subscription to associate with your VM image.

   2. Resource group Create new or select an existing resource group that you associate with the VM image.

   3. Save image as Enter a name for your VM image.

   4. Custom location Select a custom location to deploy your VM image. The custom location should correspond to the custom location for your Azure Stack HCI cluster.

   5. Image to download Select a VM image from the list of images in Azure Marketplace. The dropdown list shows all the Azure Marketplace images that are compatible with your Azure Stack HCI cluster.

   6. OS type Select the OS of the image as Windows or Linux. This is the OS associated with the image in your Storage account.

   7. VM generation. Select the Generation of the image.

   8. Source. The source of the image should be Storage blobs and is automatically populated.

   9. Storage blob. Specify the Azure Storage account path for the source image on your HCI cluster.

   10. Storage path. Select the storage path for your VM image. Select Choose automatically to have a storage path with high availability automatically selected. Select Choose manually to specify a storage path to store VM images and configuration files on the Azure Stack HCI cluster. In this case, ensure that the specified storage path has sufficient storage space.

4. Select Review + Create to create your VM image.

   

5. The input parameters are validated. If the validations succeed, you can review the VM image details and select Create.

   

6. An Azure Resource Manager template deployment job starts for the VM image. The image deployment takes a few minutes to complete. The time taken to download the image depends on the size of the Marketplace image and the network bandwidth available for the download.

   

   You can track the image deployment on the VM image grid. You can see the list of the VM images that are already downloaded and the ones that are being downloaded on the cluster.

   To view more details of any image, select the VM image name from the list of VM images.

7. When the image download is complete, the VM image shows up in the list of images, and the Status shows as Available.

   

   If the download of the VM image fails, the error details are shown in the portal blade.

   

List VM images

You need to view the list of VM images to choose an image to manage.

Azure CLI

Follow these steps to list VM image using Azure CLI.

1. Run PowerShell as an administrator.

2. Set some parameters.

   $subscription = "<Subscription ID associated with your cluster>"
   $resource_group = "<Resource group name for your cluster>"
   

3. List all the VM images associated with your cluster. Run the following command:

   az stack-hci-vm image list --subscription $subscription --resource-group $resource_group
   

   Depending on the command used, a corresponding set of images associated with the Azure Stack HCI cluster are listed.

   • If you specify just the subscription, the command lists all the images in the subscription.
   • If you specify both the subscription and the resource group, the command lists all the images in the resource group.

   These images include:

   • VM images from marketplace images.
   • Custom images that reside in your Azure Storage account or are in a local share on your cluster or a client connected to the cluster.

Here's a sample output.

PS C:\Users\azcli> az stack-hci-vm image list --subscription "<Subscription ID>" --resource-group "myhci-rg"
Command group 'stack-hci-vm' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[
  {
    "extendedLocation": {
      "name": "/subscriptions/<Subscription ID>/resourcegroups/myhci-rg/providers/microsoft.extendedlocation/customlocations/myhci-cl",
      "type": "CustomLocation"
    },
    "id": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/microsoft.azurestackhci/marketplacegalleryimages/w
inServer2022Az-01",
    "location": "eastus",
    "name": "winServer2022Az-01",
    "properties": {
      "hyperVGeneration": "V2",
      "identifier": {
        "offer": "windowsserver",
        "publisher": "microsoftwindowsserver",
        "sku": "2022-datacenter-azure-edition-core"
      },
      "imagePath": null,
      "osType": "Windows",
      "provisioningState": "Succeeded",
      "status": {
        "downloadStatus": {
          "downloadSizeInMB": 6710
        },
        "progressPercentage": 100,
        "provisioningStatus": {
          "operationId": "19742d69-4a00-4086-8f17-4dc1f7ee6681*E1E9889F0D1840B93150BD74D428EAE483CB67B0904F9A198C161AD471F670ED",
          "status": "Succeeded"
        }
      },
      "storagepathId": null,
      "version": {
        "name": "20348.2031.231006",
        "properties": {
          "storageProfile": {
            "osDiskImage": {
              "sizeInMB": 130050
            }
          }
        }
      }
    },
    "resourceGroup": "myhci-rg",
    "systemData": {
      "createdAt": "2023-10-30T21:44:53.020512+00:00",
      "createdBy": "guspinto@contoso.com",
      "createdByType": "User",
      "lastModifiedAt": "2023-10-30T22:08:25.495995+00:00",
      "lastModifiedBy": "319f651f-7ddb-4fc6-9857-7aef9250bd05",
      "lastModifiedByType": "Application"
    },
    "tags": {},
    "type": "microsoft.azurestackhci/marketplacegalleryimages"
  }
]
PS C:\Users\azcli>

For more information on this CLI command, see az stack-hci-vm image list.

Azure portal

In the Azure portal of your Azure Stack HCI cluster resource, you can track the VM image deployment on the VM image grid. You can see the list of the VM images that are already downloaded and the ones that are being downloaded on the cluster.

Follow these steps to view the list of VM images in Azure portal.

1. In the Azure portal, go to your Azure Stack HCI cluster resource.

2. Go to Resources > VM images.

3. In the right-pane, you can view the list of the VM images.

   

View VM image properties

You might want to view the properties of VM images before you use the image to create a VM. Follow these steps to view the image properties:

Azure CLI

Follow these steps to use Azure CLI to view properties of an image:

1. Run PowerShell as an administrator.

2. Set the following parameters.

   $subscription = "<Subscription ID>"
   $resource_group = "<Cluster resource group>"
   $mktplaceImage = "<Marketplace image name>"
   

3. You can view image properties in two different ways: specify ID or specify name and resource group. Take the following steps when specifying Marketplace image ID:

   1. Set the following parameter.

      $mktplaceImageID = "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.AzureStackHCI/galleryimages/myhci-marketplaceimage"
      

   2. Run the following command to view the properties.

      az stack-hci-vm image show --ids $mktplaceImageID

      Here's a sample output for this command:

      PS C:\Users\azcli> az stack-hci-vm image show --ids $mktplaceImageID
      Command group 'stack-hci-vm' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
      {
        "extendedLocation": {
          "name": "/subscriptions/<Subscription ID>/resourcegroups/myhci-rg/providers/microsoft.extendedlocation/customlocations/myhci-cl",
          "type": "CustomLocation"
        },
        "id": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.AzureStackHCI/galleryimages/myhci-marketplaceimage",
        "location": "eastus",
        "name": "myhci-marketplaceimage",
        "properties": {
          "containerName": null,
          "hyperVGeneration": null,
          "identifier": null,
          "imagePath": null,
          "osType": "Windows",
          "provisioningState": "Succeeded",
          "status": null,
          "version": null
        },
        "resourceGroup": "myhci-rg",
        "systemData": {
          "createdAt": "2022-08-05T20:52:38.579764+00:00",
          "createdBy": "guspinto@microsoft.com",
          "createdByType": "User",
          "lastModifiedAt": "2022-08-05T20:52:38.579764+00:00",
          "lastModifiedBy": "guspinto@microsoft.com",
          "lastModifiedByType": "User"
        },
        "tags": null,
        "type": "microsoft.azurestackhci/galleryimages"
      }
      PS C:\Users\azcli> 
      

Azure portal

In the Azure portal of your Azure Stack HCI cluster resource, perform the following steps:

1. Go to Resources > VM images. In the right-pane, a list of VM images is displayed.

   

2. Select the VM Image name to view the properties.

   

Delete VM image

You might want to delete a VM image if the download fails for some reason or if the image is no longer needed. Follow these steps to delete the VM images.

Azure CLI

1. Run PowerShell as an administrator.

2. Set the following parameters:

   $subscription = "<Subscription ID>"
   $resource_group = "<Cluster resource group>"
   $mktplaceImage = "<Markeplace image name>"    
   

3. Remove an existing VM image. Run the following command:

   az stack-hci-vm image delete --subscription $subscription --resource-group $resource_group --name $mktplaceImage --yes
   

You can delete image two ways:

• Specify name and resource group.
• Specify ID.

After you've deleted an image, you can check that the image is removed. Here's a sample output when the image was deleted by specifying the name and the resource-group.

PS C:\Users\azcli> $subscription = "<Subscription ID>"
PS C:\Users\azcli> $resource_group = "myhci-rg"
PS C:\Users\azcli> $mktplaceImage = "myhci-marketplaceimage"
PS C:\Users\azcli> az stack-hci-vm image delete --name $mktplaceImage --resource-group $resource_group
Command group 'stack-hci-vm' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
Are you sure you want to perform this operation? (y/n): y
PS C:\Users\azcli> az stack-hci-vm image show --name $mktplaceImage --resource-group $resource_group
Command group 'stack-hci-vm' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
ResourceNotFound: The Resource 'Microsoft.AzureStackHCI/marketplacegalleryimages/myhci-marketplaceimage' under resource group 'myhci-rg' was not found. For more details please go to https://aka.ms/ARMResourceNotFoundFix
PS C:\Users\azcli>

Azure portal

In the Azure portal of your Azure Stack HCI cluster resource, perform the following steps:

1. Go to Resources > VM images.

2. From the list of VM images displayed in the right-pane, select the trash can icon next to the VM image you want to delete.

   

3. When prompted to confirm deletion, select Yes.

   

After the VM image is deleted, the list of VM images refreshes to reflect the deleted image.

Next steps

• Create logical networks