Create Azure Local VM image using images in a local share

• Make sure to review and complete the prerequisites.

• For custom images in a local share on your Azure Local, you'll have the following extra prerequisites:

  • You should have a VHD/VHDX uploaded to a local share on your system.
  • The VHDX image must be Gen 2 type and secure boot enabled.
  • The VHDX image OS must be activated, including but not limited to KMS or AVMA.
  • The VHDX image must be prepared using sysprep /generalize /shutdown /oobe. For more information, see Sysprep command-line options.
  • The image should reside on a cluster shared volume available to all the machines in the instance. Both the Windows and Linux operating systems are supported.

• If using a client to connect to your Azure Local instance, see Connect to Azure Local via Azure CLI client.

• Make sure to review and complete the prerequisites.

• For custom images in a local share on your Azure Local, you'll have the following extra prerequisites:

  • You should have a VHD/VHDX uploaded to a local share on your system.
  • The VHDX image must be Gen 2 type and secure boot enabled.
  • The VHDX image OS must be activated, including but not limited to KMS or AVMA.
  • The VHDX image must be prepared using sysprep /generalize /shutdown /oobe. For more information, see Sysprep command-line options.
  • The image should reside on a cluster shared volume available to all the machines in the instance. Both the Windows and Linux operating systems are supported.

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

Sign in and set subscription

1. Connect to a machine on your Azure Local.

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

   $subscription = "<Subscription ID>"
   $resourceGroup = "<Resource group>"
   $customLocationID = "<Custom or extended location of your Azure Local instance>"
   $location = "<Location for your Azure Local>"
   $imageSourcePath = '"<Path to the source image in local share>"'
   $imageName = "<VM image name>"
   $osType = "<OS of source image>"
   $storagePathID = "/subscriptions/<Subscription ID>/resourceGroups/local-rg/providers/Microsoft.AzureStackHCI/storagecontainers/local-sp"
   

   The parameters are described in the following table:

   Parameter (CLI flag)	Variable name	Description
   subscription	$subscription	Subscription group for Azure Local that you associate with this image.
   resource-group	$resourceGroup	Resource group for Azure Local that you associate with this image.
   custom-location	$customLocationID	ARM ID of the custom or extended location of your Azure Local instance.
   location	$location	Location for your Azure Local instance. For example, eastus.
   image-path	$imageSourcePath	Path to the source gallery image (VHDX only) in local share. For example, C:\OSImages\winos.vhdx. See the prerequisites of the source image.
   name	$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.
   os-type	$osType	Operating system associated with the source image. For example, Windows or Linux.
   storage-path-id	$storagePathID	The associated storage path where the VM configuration and the data are saved.

   Here's a sample output:

   PS C:\Users\azcli> $subscription = "<Subscription ID>"
   PS C:\Users\azcli> $resourceGroup = "mylocalrg"
   PS C:\Users\azcli> $location = "eastus"
   PS C:\Users\azcli> $osType = "Windows"
   PS C:\ClusterStorage\Volume1> $imageName = "mylocal-localimage"
   PS C:\ClusterStorage\Volume1> $imageSourcePath = "C:\ClusterStorage\Volume1\Windows_K8s_17763.2928.220505-1621_202205101158.vhdx"
   

Add VM image from image in local share

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

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

2. Create the VM image starting with a specified image in a local share on your Azure Local.

   az stack-hci-vm image create --subscription $subscription --resource-group $resourceGroup --custom-location $customLocationID --location $location --image-path $imageSourcePath --name $imageName --os-type $osType --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. This flag ensures that the workload data (including the VM, VM image, and non-OS data disk) is placed in the specified storage path.

If the flag isn't 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 the local share and the network bandwidth available for the download.

Here's a sample output:

PS C:\Users\azcli> $customLocationID=(az customlocation show --resource-group $resourceGroup --name "myhci-cl" --query id -o tsv)
PS C:\Users\azcli> az stack-hci-vm image create --subscription $subscription --resource-group $resourceGroup --custom-location $customLocationID --location $location --image-path $imageSourcePath --name $imageName --os-type $osType --storage-path-id $storagePathID
type="CustomLocation" --location $Location --name $mktplaceImage --os-type $osType --image-path $mktImageSourcePath
Command group 'azurestackhci' is experimental and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "extendedLocation": {
    "name": "/subscriptions/<Subscription ID>/resourceGroups/mylocal-rg/providers/Microsoft.ExtendedLocation/customLocations/mylocal-cl",
    "type": "CustomLocation"
  },
  "id": "/subscriptions/<Subscription ID>/resourceGroups/mylocal-rg/providers/Microsoft.AzureStackHCI/galleryimages/mylocal-localimage",
  "location": "eastus",
  "name": "mylocal-localimage",
  "properties": {
    "identifier": null,
    "imagePath": null,
    "osType": "Windows",
    "provisioningState": "Succeeded",
    "status": {
      "downloadStatus": {},
      "progressPercentage": 100,
      "provisioningStatus": {
        "operationId": "82f58893-b252-43db-97a9-258f6f7831d9*43114797B86E6D2B28C4B52B02302C81C889DABDD9D890F993665E223A5947C3",
        "status": "Succeeded"
      }
    },
    "storagepathId": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.AzureStackHCI/storagecontainers/myhci-storagepath",
    "version": {
      "name": null,
      "properties": {
        "storageProfile": {
          "osDiskImage": {}
        }
      }
    }
  },
  "resourceGroup": "myhci-rg",
  "systemData": {
    "createdAt": "2023-11-02T06:15:10.450908+00:00",
    "createdBy": "guspinto@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-11-02T06:15:56.689323+00:00",
    "lastModifiedBy": "319f651f-7ddb-4fc6-9857-7aef9250bd05",
    "lastModifiedByType": "Application"
  },
  "tags": null,
  "type": "microsoft.azurestackhci/galleryimages"
}    

You can create a VM image by downloading an image that resides in a local share on your Azure Local and then use that VM image to deploy a virtual machine.

In Azure portal for your Azure Local resource, perform the following steps:

1. Go to Resources > VM images.

2. Select + Add VM Image and from the dropdown list, select Add VM image from a local share.

   

3. In the Create an image page, on the Basics tab, enter 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 Local.

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

   6. VM generation: Select the generation for your image.

   7. Source: The source of the image should be Local file share and is automatically populated.

   8. Local file share path: Specify the local share path for the source image on your system.

   9. 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 Local instance. 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.

   

   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 custom 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 system.

6. When the image download is complete, the VM image shows up in the list of images and the Status shows as Available. To view more details of any image, select the VM image name from the list of VM images.