Edit

Share via

Create Azure Local VM image using existing Arc VMs

  • Article

Applies to: Azure Local 2311.2 and later

This article describes how to create virtual machine (VM) images for your Azure Local using existing Arc VMs via the Azure CLI. The operating system (OS) disk of the Arc VM is used to create a gallery image on your Azure Local.

Prerequisites

Before you begin, make sure that:

Create VM image from existing Arc VM

You create a VM image starting from the OS disk of the Arc VM and then use this image to deploy VMs on your Azure Local.

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

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>"
$custom_location = "<Custom location for your Azure Local>"
$osType = "<OS of source VM>"
$imageName = "<VM image name>"
$sourceVmName = "<Name of source VM  in the Storage account>"

The parameters are described in the following table:

Parameter Description
subscription Subscription for the Azure Local instance that you associate with this image.
resource_group Resource group for the Azure Local instance that you associate with this image.
location Location for your Azure Local. For example, this could be eastus.
custom-location Custom location ID for your Azure Local.
name 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.
source-vm Name of an existing Arc VM that you'll use to create the VM image.
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 = "mysub-id"
PS C:\Users\azcli> $resource_group = "mylocal-rg"
PS C:\Users\azcli> $location = "eastus"
PS C:\Users\azcli> $custom_location = "mylocal-cl"
PS C:\Users\azcli> $osType = "Windows"
PS C:\Users\azcli> $imageName = "mylocal-image"
PS C:\Users\azcli> $sourceVmName = "mysourcevm"

Create VM image from an Arc VM

Create the VM image from an existing Arc VM. Run the following command:

az stack-hci-vm image create -resource-group $resource_group --location $location --custom-location $custom_location --os-type $osType --source-vm $sourceVmName --name $imageName

A deployment job starts for the VM image. The image deployment takes a few minutes to complete.

Here's a sample output:

{
  "extendedLocation": {
    "name": "/subscriptions/mysub-id/resourceGroups/mylocal-rg/providers/Microsoft.ExtendedLocation/customLocations/mylocal-cl",
    "type": "CustomLocation"
  },
  "id": "/subscriptions/mysub-id/resourceGroups/mylocal-rg/providers/Microsoft.AzureStackHCI/galleryImages/mylocal-image",
  "location": "eastus",
  "name": "mylocal-image",
  "properties": {
    "cloudInitDataSource": null,
    "containerId": null,
    "hyperVGeneration": null,
    "identifier": null,
    "imagePath": null,
    "osType": "Windows",
    "provisioningState": "Succeeded",
    "sourceVirtualMachineId": "/subscriptions/mysub-id/resourceGroups/mylocal-rg/providers/Microsoft.HybridCompute/machines/mysourcevm/providers/Microsoft.AzureStackHCI/virtualMachineInstances/default",
    "status": {
      "downloadStatus": {
        "downloadSizeInMb": null
      },
      "errorCode": "",
      "errorMessage": "",
      "progressPercentage": null,
      "provisioningStatus": {
        "operationId": null,
        "status": null
      }
    },
    "version": {
      "name": null,
      "properties": {
        "storageProfile": {
          "osDiskImage": {
            "sizeInMb": null
          }
        }
      }
    }
  },
  "resourceGroup": "mylocal-rg",
  "systemData": {
    "createdAt": "2024-09-26T20:16:17.625002+00:00",
    "createdBy": "a5e473cb-e3e7-4035-b4da-290a65350ae1",
    "createdByType": "Application",
    "lastModifiedAt": "2024-09-26T20:16:17.625002+00:00",
    "lastModifiedBy": "a5e473cb-e3e7-4035-b4da-290a65350ae1",
    "lastModifiedByType": "Application"
  },
  "tags": null,
  "type": "microsoft.azurestackhci/galleryimages"
}

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 Azure Local>"
$resource_group = "<Resource group name for your Azure Local>"

  3. List all the VM images associated with your Azure Local. 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 your Azure Local 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 system or a client connected to your system.

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": "mylocal-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 = "<Azure Local 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/mylocal-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/mylocal-cl",
    "type": "CustomLocation"
  },
  "id": "/subscriptions/<Subscription ID>/resourceGroups/myhci-rg/providers/Microsoft.AzureStackHCI/galleryimages/mylocal-marketplaceimage",
  "location": "eastus",
  "name": "mylocal-marketplaceimage",
  "properties": {
    "containerName": null,
    "hyperVGeneration": null,
    "identifier": null,
    "imagePath": null,
    "osType": "Windows",
    "provisioningState": "Succeeded",
    "status": null,
    "version": null
  },
  "resourceGroup": "mylocal-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 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 = "<Azure Local 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 = "mylocal-rg"
PS C:\Users\azcli> $mktplaceImage = "mymylocal-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 'mylocal-rg' was not found. For more details please go to https://aka.ms/ARMResourceNotFoundFix
PS C:\Users\azcli>

Next steps