Task 06 — VM Image Downloads
DOCUMENT CATEGORY: Implementation Guide
SCOPE: Phase 06 — Post-Deployment | Azure Local
PURPOSE: Register standard Azure Marketplace VM images on the cluster so they are MASTER REFERENCE: Azure Local VM Images available for Arc VM deployment
Status: Active
Objective: Download and register the three standard Azure Marketplace VM images on the Azure Local cluster. Once registered, images are stored on the cluster's CSV storage and available for Arc VM provisioning.
This task covers Azure Marketplace image downloads only. Workflows for creating custom images (sysprep, generalize, upload, or convert from VHDX/VHD) are covered in a dedicated appendix or in the custom image management section of this documentation.
Prerequisites:
- Azure Local cluster deployed and Arc-enabled (Phase 05 complete)
- CSV volumes created and healthy (Task 05 complete)
- Azure identity authenticated:
az loginor Az PowerShellConnect-AzAccount az stack-hci-vmCLI extension installed (az extension add --name stack-hci-vm)marketplace_imagesblock populated ininfrastructure.yml
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
azure.tenant_id, azure.subscription_id, azure.resource_group, azure.location, azure.custom_location, tags
storage.paths[]: name
storage.vm_images[]: name, os_type, publisher, offer, sku, version, storage_path
Download Images
- Azure Portal
- Orchestrated Script
- Azure CLI
When to use: Single image creation, visual confirmation of marketplace offer details, or when CLI access is unavailable.
Prerequisites: Access to the Azure Portal with Contributor rights on the resource group.
Steps (repeat for each image):
-
Navigate to your Azure Local cluster resource: Azure Portal → Azure Local →
iic-clus01 -
In the left navigation, select Resources → VM images
-
Click + Add VM image → Add VM image from Azure Marketplace
-
Search for the image and select it:
| Image | Search term |
|---|---|
| Windows Server 2025 Datacenter Azure Edition Gen 2 | Windows Server 2025 Datacenter Azure Edition |
| Windows Server 2022 Datacenter Azure Edition Hotpatch Gen 2 | Windows Server 2022 Datacenter Azure Edition |
| Windows 11 Enterprise Multi-Session 25H2 + Microsoft 365 Apps Gen 2 | Windows 11 Enterprise multi-session |
Confirm Gen 2 in the image name before selecting. Gen 1 images are not supported on Azure Local Arc VMs and will fail to deploy.
- On the Create VM image blade, fill in:
- Subscription:
00000000-0000-0000-0000-000000000000 - Resource group:
rg-iic01-azl-eus-01 - Custom location:
cl-iic01 - Image name: e.g.
img-iic01-ws2025-azedition-g2 - Image version:
latest(or a specific version) - Storage path: select a registered storage path (e.g.
sp-iic01-clus01-m2-vmstore-prd-01)
-
Click Review + create → Create
-
Image download starts immediately. Progress is visible on the VM images blade. A 40–60 GB image typically takes 15–30 minutes depending on cluster network speed.
-
Repeat for the remaining two images.
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-06-image-downloads/powershell/New-VmImage.ps1 | Downloads the Azure Marketplace images that storage.vm_images of infrastructure.yml lists to Azure Local, as Azure Local VM images. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./New-VmImage.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-06-image-downloads/azurecli/New-VmImage.azcli.ps1 | Downloads the Azure Marketplace images that storage.vm_images of infrastructure.yml lists to Azure Local, as Azure Local VM images, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>. Needs the Azure CLI extension stack-hci-vm (az extension add --name stack-hci-vm); the script does not install it.
Only Azure Marketplace images are supported. The images are created one after the other and each command waits until its image is downloaded. latest takes the newest version at creation, and the script reports the version it got without writing it to the file. An image that exists is left alone; an image that failed is reported as Failed and is not deleted or recreated (delete it with az stack-hci-vm image delete, then run the script again). The Microsoft.EdgeMarketplace provider must be registered in the subscription (the script checks this).
Run
./New-VmImage.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-VmImage.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
After all images are created, confirm they are in a Succeeded provisioning state and are visible on the cluster's VM images blade.
az stack-hci-vm image list `
--subscription 00000000-0000-0000-0000-000000000000 `
--resource-group rg-iic01-azl-eus-01 `
--output table
az stack-hci-vm image show `
--subscription 00000000-0000-0000-0000-000000000000 `
--resource-group rg-iic01-azl-eus-01 `
--name img-iic01-ws2025-azedition-g2 `
--query "{Name:name, State:provisioningState, OS:properties.osType}" `
--output table
Expected results:
| Name | State | OS |
|---|---|---|
img-iic01-ws2025-azedition-g2 | Succeeded | Windows |
img-iic01-ws2022-azedition-hotpatch-g2 | Succeeded | Windows |
img-iic01-win11-25h2-avd-m365-g2 | Succeeded | Windows |
If an image stays in Downloading for more than 60 minutes or enters Failed state:
- Check cluster storage health — CSV volumes must be online and have sufficient free space
- Verify the cluster has outbound internet access to
*.blob.core.windows.net(image source) - Delete the failed image and re-run:
az stack-hci-vm image delete --name <img> --resource-group <rg> --yes
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
Image stuck in Downloading for over 60 minutes | Insufficient CSV free space or blocked outbound connectivity | Check CSV free space: Get-ClusterSharedVolume; verify outbound to *.blob.core.windows.net on port 443 |
Image provisioning state is Failed | Invalid image source URL or Arc resource bridge issue | Delete and recreate: az stack-hci-vm image delete --name <img> --resource-group <rg> --yes; verify bridge health first |
| Image not visible in Azure portal | Sync delay between cluster and Azure | Wait 10-15 minutes; if still missing, verify the custom location resource is healthy: az customlocation show |
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| ← Previous | Task 05 — Storage Configuration |
| ↑ Phase Index | Phase 06 — Post-Deployment Index |
| → Next | Task 07 — Configure NSGs |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |