Create Azure Stack HCI VM image using Azure Marketplace images (preview)

Applies to: Azure Stack HCI, versions 22H2 and 21H2

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.

Important

This feature is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Prerequisites

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

  • You've your Microsoft account with credentials to access Azure portal.

  • You've access to an Azure Stack HCI cluster. This cluster is deployed, registered, and connected to Azure Arc.

    • Go to the Overview page in the Azure Stack HCI cluster resource. On the Server tab in the right-pane, the Azure Arc should show as Connected.

      Screenshot of the Overview page in the Azure Stack HCI cluster resource showing Azure Arc as connected.

  • To enable Azure Arc VMs on your Azure Stack HCI, see Deploying Azure Arc resource bridge. As a part of Arc Resource Bridge deployment, you'll also create a custom location for your Azure Stack HCI cluster that you'll use later in the scenario. The custom location will also show up in the Overview page for Azure Stack HCI cluster.

  • Access to a client that can connect to your Azure Stack HCI cluster. This client should be:

    • Running PowerShell 5.0 or later.
    • Running the latest version of az CLI.
      • Download the latest version of az CLI. Once you have installed az CLI, make sure to restart the system.
      • If you have an older version of az CLI running, make sure to uninstall the older version first.

Add VM image from Azure Marketplace

You'll 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.

Set some parameters

  1. Run PowerShell as an administrator.

  2. Sign in. Type:

    az login
    
  3. Set your subscription.

    az account set --subscription <Subscription ID>
    
  4. 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>"
    $Location = "<Location for your Azure Stack HCI cluster>"
    $OsType = "<OS of source image>"
    

    The parameters are described in the following table:

    Parameter Description
    Subscription Resource group for Azure Stack HCI cluster that you'll associate with this image.
    Resource_Group Resource group for Azure Stack HCI cluster that you'll associate with this image.
    Location Location for your Azure Stack HCI cluster. For example, this could be eastus, eastus2euap.
    OsType 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 = "mkclus90-rg"
    PS C:\Users\azcli> $location = "eastus2euap"
    PS C:\Users\azcli> $osType = "Windows"
    

Create VM image from marketplace image

  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 azurestackhci image create --subscription $subscription --resource-group $resource_group --extended-location name=$customLocationID type="CustomLocation" --location $Location --name "<VM image name>"  --os-type $osType --offer "windowsserver" --publisher "microsoftwindowsserver" --sku "2022-datacenter-azure-edition-core" --version "20348.707.220609"
    

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

Here's a sample output:

PS C:\Users\azcli> $customLocationID=(az customlocation show --resource-group $resource_group --name "cl04" --query id -o tsv)
PS C:\Users\azcli> $customLocationID
/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04
PS C:\Users\azcli> az azurestackhci image create --subscription $subscription --resource-group $resource_group --extended-location name=$customLocationID type="CustomLocation" --location $Location --name "marketplacetest03"  --os-type $osType --offer "<Offer>" --publisher "<Publisher>" --sku "<SKU>" --version "<Version number>"
{
 "extendedLocation": {
 "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
 "type": "CustomLocation"
 },
 "id": "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/marketplacegalleryimages/marketplacetest03",
 "location": "eastus2euap",
 "name": "marketplacetest03",
 "properties": {
    "containerName": null,
    "identifier": {
    "offer": "windowsserver",
    "publisher": "microsoftwindowsserver",
    "sku": "2022-datacenter-azure-edition-core"
    },
  "imagePath": null,
  "provisioningState": "Succeeded",
  "resourceName": "marketplacetest03",
  "status": {
    "downloadStatus": {},
    "provisioningStatus": {
    "operationId": "<Operation ID>",
      "status": "Succeeded"
    }
  },
    "version": {
      "name": "20348.707.220609",
        "storageProfile": {
          "osDiskImage": {}
        }
      }
    }
  },
  "resourceGroup": "mkclus90-rg",
  "systemData": {
    "createdAt": "2022-08-01T22:29:11.074104+00:00",
    "createdBy": "guspinto@microsoft.com",
    "createdByType": "User",
    "lastModifiedAt": "2022-08-01T22:36:12.900694+00:00",
    "lastModifiedBy": "319f651f-7ddb-4fc6-9857-7aef9250bd05",
    "lastModifiedByType": "Application"
  },
  "tags": null,
  "type": "microsoft.azurestackhci/marketplacegalleryimages"
}
PS C:\Users\azcli>

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 azurestackhci 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 azurestackhci image list --subscription "b8d594e5-51f3-4c11-9c54-a7771b81c712" --resource-group "mkclus90-rg"
Command group 'azurestackhci' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[
  {
    "extendedLocation": {
      "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
      "type": "CustomLocation"
    },
    "id": "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/testvhdgen1",
    "location": "eastus2euap",
    "name": "testvhdgen1",
    "properties": {
      "containerName": null,
      "hyperVGeneration": "V1",
      "identifier": null,
      "imagePath": null,
      "osType": "Windows",
      "provisioningState": "Succeeded",
      "status": null,
      "version": null
    },
    "resourceGroup": "mkclus90-rg",
    "systemData": {
      "createdAt": "2022-07-28T22:45:30.803142+00:00",
      "createdBy": "guspinto@microsoft.com",
      "createdByType": "User",
      "lastModifiedAt": "2022-07-28T22:45:30.803142+00:00",
      "lastModifiedBy": "guspinto@microsoft.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "type": "microsoft.azurestackhci/galleryimages"
  },
  {
    "extendedLocation": {
      "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
      "type": "CustomLocation"
    },
    "id": "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/testvhdxgen2",
    "location": "eastus2euap",
    "name": "testvhdxgen2",
    "properties": {
      "containerName": null,
      "hyperVGeneration": null,
      "identifier": null,
      "imagePath": null,
      "osType": "Windows",
      "provisioningState": "Succeeded",
      "status": null,
      "version": null
    },
    "resourceGroup": "mkclus90-rg",
    "systemData": {
      "createdAt": "2022-07-28T23:00:56.490100+00:00",
      "createdBy": "guspinto@microsoft.com",
      "createdByType": "User",
      "lastModifiedAt": "2022-07-28T23:00:56.490100+00:00",
      "lastModifiedBy": "guspinto@microsoft.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "type": "microsoft.azurestackhci/galleryimages"
  },
  {
    "extendedLocation": {
      "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
      "type": "CustomLocation"
    },
    "id": "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/marketplacegalleryimages/marketplacetest03",
    "location": "eastus2euap",
    "name": "marketplacetest03",
    "properties": {
      "containerName": null,
      "hyperVGeneration": null,
      "identifier": {
        "offer": "windowsserver",
        "publisher": "microsoftwindowsserver",
        "sku": "2022-datacenter-azure-edition-core"
      },
      "imagePath": null,
      "osType": "Windows",
      "provisioningState": "Succeeded",
      "resourceName": "marketplacetest03",
      "status": {
        "downloadStatus": {},
        "provisioningStatus": {
          "operationId": "<Operation ID>",
          "status": "Succeeded"
        }
      },
      "version": {
        "name": "20348.707.220609",
        "properties": {
          "storageProfile": {
            "osDiskImage": {}
          }
        }
      }
    },
    "resourceGroup": "mkclus90-rg",
    "systemData": {
      "createdAt": "2022-08-01T22:29:11.074104+00:00",
      "createdBy": "guspinto@microsoft.com",
      "createdByType": "User",
      "lastModifiedAt": "2022-08-01T22:36:12.900694+00:00",
      "lastModifiedBy": "<ID>",
      "lastModifiedByType": "Application"
    },
    "tags": null,
    "type": "microsoft.azurestackhci/marketplacegalleryimages"
  }
]
PS C:\Users\azcli>

View VM image properties

You may 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 ID:

    1. Set the following parameter.

      $MktplaceImageID = "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/mktplace8"
      
    2. Run the following command to view the properties.

      az azurestackhci image show --id $mktplaceImageID

      Here's a sample output for this command:

      PS C:\Users\azcli> az azurestackhci image show --id $mktplaceImageID
      Command group 'azurestackhci' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
      {
        "extendedLocation": {
          "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
          "type": "CustomLocation"
        },
        "id": "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/mktplace8",
        "location": "eastus2euap",
        "name": "mktplace8",
        "properties": {
          "containerName": null,
          "hyperVGeneration": null,
          "identifier": null,
          "imagePath": null,
          "osType": "Windows",
          "provisioningState": "Succeeded",
          "status": null,
          "version": null
        },
        "resourceGroup": "mkclus90-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>
      
  4. Take the following steps when specifying name and resource group.

    1. Set the following parameters:

      $mktplaceImage = "mktplace8"
      $resource_group = "mkclus90-rg"    
      
    2. Run the following command to view the properties:

      az azurestackhci image show --name $MktplaceImage --resource-group $Resource_Group
      

      Here's a sample output:

      PS C:\Users\azcli> az azurestackhci image show --name $mktplaceImage --resource-group $resource_group
      Command group 'azurestackhci' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
      {
         "extendedLocation": {
         "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
         "type": "CustomLocation"
         },
         "id": "/subscriptions/b8d594e5-51f3-4c11-9c54-a7771b81c712/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/mktplace8",
         "location": "eastus2euap",
         "name": "mktplace8",
         "properties": {
         "containerName": null,
         "hyperVGeneration": null,
         "identifier": null,
         "imagePath": null,
         "osType": "Windows",
         "provisioningState": "Succeeded",
         "status": null,
         "version": null
         },
         "resourceGroup": "mkclus90-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>        
      

Delete VM image

You may 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.

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 ID:

    1. Set the following parameter.

      $MktplaceImageID = "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/mktplace8"
      
    2. Run the following command to view the properties.

      az azurestackhci image show --id $mktplaceImageID

      Here's a sample output for this command:

      PS C:\Users\azcli> az azurestackhci image show --id $mktplaceImageID
      Command group 'azurestackhci' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
      {
        "extendedLocation": {
          "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
          "type": "CustomLocation"
        },
        "id": "/subscriptions/<Subscription ID>/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/mktplace8",
        "location": "eastus2euap",
        "name": "mktplace8",
        "properties": {
          "containerName": null,
          "hyperVGeneration": null,
          "identifier": null,
          "imagePath": null,
          "osType": "Windows",
          "provisioningState": "Succeeded",
          "status": null,
          "version": null
        },
        "resourceGroup": "mkclus90-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>
      
  4. Take the following steps when specifying name and resource group.

    1. Set the following parameters:

      $mktplaceImage = "mktplace8"
      $resource_group = "mkclus90-rg"    
      
    2. Run the following command to view the properties:

      az azurestackhci image show --name $MktplaceImage --resource-group $Resource_Group
      

      Here's a sample output:

      PS C:\Users\azcli> az azurestackhci image show --name $mktplaceImage --resource-group $resource_group
      Command group 'azurestackhci' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
      {
         "extendedLocation": {
         "name": "/subscriptions/<Subscription ID>/resourcegroups/mkclus90-rg/providers/microsoft.extendedlocation/customlocations/cl04",
         "type": "CustomLocation"
         },
         "id": "/subscriptions/b8d594e5-51f3-4c11-9c54-a7771b81c712/resourceGroups/mkclus90-rg/providers/Microsoft.AzureStackHCI/galleryimages/mktplace8",
         "location": "eastus2euap",
         "name": "mktplace8",
         "properties": {
         "containerName": null,
         "hyperVGeneration": null,
         "identifier": null,
         "imagePath": null,
         "osType": "Windows",
         "provisioningState": "Succeeded",
         "status": null,
         "version": null
         },
         "resourceGroup": "mkclus90-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>        
      

Next steps