Create Azure Local VM image via Azure Compute Gallery images

Applies to: Hyperconverged deployments of Azure Local

This article describes how to create Azure Local virtual machines (VMs) enabled by Azure Arc using source images from the Azure Compute Gallery. You can create VM images on Azure CLI using the instructions in this article and then use these VM images to create Azure Local VMs.

Prerequisites

Review and complete the Azure Local VM prerequisites.
Make sure that your image uses an operating system that the Azure Arc connected machine agent supports.

Note

Not all operating systems listed on the Azure Arc-enabled servers supported OS page are supported for Arc enablement (guest management) on Azure Local. Guest management requires Hyper-V socket (HV socket) support, which limits the supported OS set further.
For custom images in Azure Compute Gallery, ensure you meet these extra prerequisites:
- You have a virtual hard disk (VHD) loaded in your Azure Compute Gallery. See how to Create an image definition and image version.
- If using a virtual hard disk v2 (VHDX):
  - The VHDX image is Gen 2 type and secure boot enabled.
  - The VHDX image is prepared using sysprep /generalize /shutdown /oobe. For more information, see Sysprep command-line options.

Add VM image from Azure Compute Gallery

Follow these steps to create an Azure Local VM image using Azure CLI.

Connect to a machine on your Azure Local instance.
Sign in and enter the following command:
```
az login --use-device-code
```

Set your subscription.

az account set --subscription <Subscription ID>

Export image to managed disk

To transfer your Azure Compute Gallery image to be an Azure Local compatible image, you need to export your Azure Compute Gallery image version to a managed disk.

To download the Azure Compute Gallery image to your resource group, follow the steps in Export an image version to a managed disk. Note the name of the managed disk.

Important

The export action must be performed in the source subscription and source resource group that contain the Azure Compute Gallery image version.

When creating the managed disk, ensure that:

You select the resource group where the gallery image exists (source subscription), not the Azure Local target resource group.
The resulting managed disk will remain in the source subscription. Azure Local will later access it via the SAS URL.

Attempting to create the managed disk in the target Azure Local resource group will fail because the image version doesn't exist there.

Get the shared access signature (SAS) token of the managed disk by using the following command:

# Variables to get SAS URL for the managed disk
$resource_group = "<Resource Group Name>"
$diskName = "<myDiskName>" # Replace 'myDiskName' with your actual disk name
$sasExpiryDuration = 100000 # Duration in seconds for SAS URL validity

az disk grant-access --resource-group $resource_group --name $diskName --duration-in-seconds $sasExpiryDuration --query [accessSas] -o tsv

Set parameters

Before creating an Azure Local VM image, you need to set some parameters.

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 Local>"
$osType = "<OS of source image>"
$imageName = "<VM image name>"
$customLocationID = "<Custom Location ID>"
$imageSourcePath = '"<SAS URL path to the source image>"'

The following table describes the parameters:

Parameter	Description
`subscription`	Subscription for Azure Local that you associate with the gallery image.
`resource_group`	Resource group for Azure Local that you associate with the gallery image.
`location`	Location for your Azure Local instance. For example, `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.
`os-type`	Operating system associated with the source image. For example, Windows or Linux.
`customLocationID`	Custom location ID for your Azure Local instance.
`imageSourcePath`	Path to the gallery image managed disk SAS URL.

Here's a sample output:

PS C:\Users\azcli> $subscription = "<Subscription ID>"
PS C:\Users\azcli> $resource_group = "mylocal-rg"
PS C:\Users\azcli> $location = "eastus"
PS C:\Users\azcli> $osType = "Windows"
PS C:\Users\azcli> $imageName = "mylocal-computegalleryimage"
PS C:\Users\azcli> $customLocationID = "/subscriptions/$subscription/resourcegroups/$resource_group/providers/microsoft.extendedlocation/customlocations/$customLocationName"
PS C:\Users\azcli> $imageSourcePath = '"https://EXAMPLE.blob.storage.azure.net/EXAMPLE/abcd<sas-token>"'

Create an Azure Local VM image

To create an Azure Local VM image, follow these steps:

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 $resource_group --name "<custom location name for your Azure Local>" --query id -o tsv)
```

Create the VM image starting with a specified gallery image. Make sure to specify the offer, publisher, Stock Keeping Unit (SKU), and version for the 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

A deployment job starts for the VM image and takes a few minutes to complete. The image download time depends on the image size and the network bandwidth available for the download.

Here's a sample output:

{ 
  "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-image", 
  "location": "eastus", 
  "name": "mylocal-image", 
  "properties": { 
    "cloudInitDataSource": null, 
    "containerId": "/subscriptions/<Subscription ID>/resourceGroups/mylocal-rg/providers/Microsoft.AzureStackHCI/storageContainers/mylocal-storagepath", 
    "hyperVGeneration": null, 
    "identifier": null, 
    "imagePath": null, 
    "osType": "Windows", 
    "provisioningState": "Succeeded", 
    "sourceVirtualMachineId": null, 
    "status": { 
      "downloadStatus": { 
        "downloadSizeInMb": 11482 
      }, 
      "errorCode": "", 
      "errorMessage": "", 
      "progressPercentage": 100, 
      "provisioningStatus": { 
        "operationId": "00000000-0000-0000-0000-000000000000*0000000000000000000000000000000000000000000000000000000000000000", 
        "status": "Succeeded" 
      } 
    }, 
    "version": { 
      "name": null, 
      "properties": { 
        "storageProfile": { 
          "osDiskImage": { 
            "sizeInMb": 130050 
          } 
        } 
      } 
    }, 
    "vmImageRepositoryCredentials": null 
  }, 
  "resourceGroup": "mylocal-rg", 
  "systemData": { 
    "createdAt": "2025-05-21T00:44:16.385633+00:00", 
    "createdBy": "guspinto@contoso.com", 
    "createdByType": "User", 
    "lastModifiedAt": "2025-05-21T00:48:34.016113+00:00", 
    "lastModifiedBy": "00000000-0000-0000-0000-000000000000", 
    "lastModifiedByType": "Application" 
  }, 
  "tags": null, 
  "type": "microsoft.azurestackhci/galleryimages" 
}

To avoid costs associated with a disk, make sure to delete the managed disk that was used to create this image using the following command:
```
az disk delete --name $diskName --resource-group $resourceGroupName
```

Next steps

Povratne informacije

Je li ova stranica bila od pomoći?

Last updated on 2026-04-22