Create Azure Stack HCI VM image using Azure Marketplace images

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

Add VM image from Azure Marketplace

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

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 parameters for your subscription, resource group, location, OS type for the image. Replace the parameters in < > with the appropriate values.

    $subscription = "<Subscription ID>"
    $resource_group = "<Resource group>"
    $mktplaceImage = "<Marketplace image name>"
    $customLocationName = "<Custom location name>"
    $customLocationID = (az customlocation show --resource-group $resource_group --name "<custom_location_name_for_Azure_Stack_HCI_cluster>" --query id -o tsv)
    $location = "<Location for your Azure Stack HCI cluster>"
    $osType = "<OS of source image>"
    

    The parameters are described in the following table:

    Parameter Description
    subscription Subscription associated with your Azure Stack HCI cluster.
    resource-group Resource group for Azure Stack HCI cluster that you associate with this image.
    name Name of the marketplace image for Azure Stack HCI cluster.
    customLocation Resource ID of custom location for Azure Stack HCI cluster.
    location Location for your Azure Stack HCI cluster. For example, this could be eastus.
    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> $mktplaceImage= "myhci-marketplaceimage"
    PS C:\Users\azcli> $customLocationName = "myhci-cl"
    PS C:\Users\azcli> $customerLocationID /subscriptions$subscription/resourcegroups/$resource_group/providers/microsoft.extendedlocation/customlocations/$customLocationName
    PS C:\Users\azcli> $location = "eastus"
    PS C:\Users\azcli> $ostype = "Windows"
    

Create VM image from marketplace image

  1. Set additional parameters that specify the intended VM image you would like to create. You will need to include the offer, publisher, SKU, and version for the marketplace image. Replace the parameters in < > with the appropriate values:

    $publisher = "<Publisher name>"
    $offer = "<OS offer>"
    $sku = "<Image SKU>"
    

    Use the following table to find the available marketplace images and their attribute values:

    Name Publisher Offer SKU
    Windows 11 Enterprise multi-session + Microsoft 365 microsoftwindowsdesktop office-365 win11-21h2-avd-m365
    win11-23h2-avd-m365
    Windows 10 Enterprise multi-session + Microsoft 365 microsoftwindowsdesktop office-365 win10-21h2-avd-m365
    win10-22h2-avd-m365
    Windows 11 Pro microsoftwindowsdesktop windows-11 win11-21h2-pro
    win11-22h2-pro
    win11-23h2-pro
    Windows 11 Enterprise microsoftwindowsdesktop windows-11 win11-21h2-ent
    win11-22h2-ent
    win11-23h2-ent
    Windows 11 Enterprise multi-session microsoftwindowsdesktop windows-11 win11-21h2-avd
    win11-22h2-avd
    win11-23h2-avd
    Windows 10 Pro microsoftwindowsdesktop windows-10 win10-22h2-pro-g2
    Windows 10 Enterprise microsoftwindowsdesktop windows-10 win10-22h2-ent-g2
    Windows 10 Enterprise multi-session microsoftwindowsdesktop windows-10 win10-22h2-avd
    Windows Server 2022 Datacenter: Azure Edition microsoftwindowsserver windowsserver 2022-datacenter-azure-edition-hotpatch
    2022-datacenter-azure-edition-core
    2022-datacenter-azure-edition
    Windows Server 2019 microsoftwindowsserver windowsserver 2019-datacenter-gensecond
    2019-datacenter-core-g2
    SQL Server 2022 Enterprise on Windows Server 2022 microsoftsqlserver sql2022-ws2022 enterprise-gen2
    standard-gen2

    If you wanted to create a Windows Server 2019 Datacenter image, you would have the following parameters:

    $publisher = "microsoftwindowsserver" 
    $offer = "windowsserver" 
    $sku = "2019-datacenter-gensecond"
    
  2. Create the VM image starting with a specified marketplace image:

    az stack-hci-vm image create --resource-group $resource_group --custom-location $customLocationID --name $mktplaceImage --os-type $ostype --offer $offer --publisher $publisher --sku $sku 
    

Here's a sample output:

PS C:\Users\azcli> az stack-hci-vm image create --custom-location $cl --name $mktplaceImage --os-type $ostype --resource-group $rg --publisher $publisher --offer $offer --sku $sku 
{ 
  "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/myhci-marketplaceimage", 
\ 
  "location": "eastus", 
  "name": "myhci-marketplaceimage", 
  "properties": { 
    "cloudInitDataSource": null, 
    "containerId": null, 
    "hyperVGeneration": null, 
    "identifier": { 
      "offer": "windowsserver", 
      "publisher": "microsoftwindowsserver", 
      "sku": "2019-datacenter-gensecond" 
    }, 
    "osType": "Windows", 
    "provisioningState": "Succeeded", 
    "status": { 
      "downloadStatus": { 
        "downloadSizeInMb": 10832 
      }, 
      "errorCode": "", 
      "errorMessage": "", 
      "progressPercentage": 100, 
      "provisioningStatus": { 
        "operationId": "13efc468-7473-429f-911b-858c1e6fc1d5*B11A62EE76B08EF194F8293CDD40F7BC71BFB93255D5A99DD11B4167690752D9", 
        "status": "Succeeded" 
      } 
    }, 
    "version": { 
      "name": "17763.6293.240905", 
      "properties": { 
        "storageProfile": { 
          "osDiskImage": { 
            "sizeInMb": 130050 
          } 
        } 
      } 

    } 
  }, 
  "resourceGroup": "myhci-rg", 
  "systemData": { 
    "createdAt": "2024-09-23T18:53:13.734389+00:00", 
    "createdBy": "guspinto@contoso.com", 
    "createdByType": "User", 
    "lastModifiedAt": "2024-09-23T19:06:07.532276+00:00", 
    "lastModifiedBy": "319f651f-7ddb-4fc6-9857-7aef9250bd05", 
    "lastModifiedByType": "Application" 
  }, 

  "tags": null, 
  "type": "microsoft.azurestackhci/marketplacegalleryimages" 
} 

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

List VM images

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

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.

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:

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> 
      

Update VM image

When a new updated image is available in Azure Marketplace, the VM images on your Azure Stack HCI cluster become stale and should be updated. The update operation isn't an in-place update of the image. Rather you can see for which VM images an updated image is available, and select images to update. After you update, the create VM image operation uses the new updated image.

To update a VM image, use the following steps in Azure portal.

  1. To see if an update is available, select a VM image from the list view.

    Screenshot showing that a VM image update is available for download.

    In the Overview blade, you see a banner that shows the new VM image available for download, if one is available. To update to the new image, select the arrow icon.

    Screenshot showing a new VM image available for download in VM image details.

  2. Review image details and then select Review and create. By default, the new image uses the same resource group and instance details as the previous image.

    The name for the new image is incremented based on the name of the previous image. For example, an existing image named winServer2022-01 will have an updated image named winServer2022-02.

    Screenshot showing the Review and create dialog for a new VM image.

  3. To complete the operation, select Create.

    Screenshot showing the Create image dialog for a new VM image.

    After the new VM image is created, create a VM using the new image and verify that the VM works properly. After verification, you can delete the old VM image.

    Note

    In this release, you can't delete a VM image if the VM associated with that image is running. Stop the VM and then delete the VM image.

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.

  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>

Next steps