Prerequisites

Before running any conversion scripts, ensure the following requirements are met.

---

Azure Local Cluster

Requirement	Details
Version	23H2 recommended; 22H2 supported
Cluster health	All nodes healthy, no active cluster events
CSV availability	Sufficient free space on the target CSV (~1x total VHDX size of VMs being converted)
Maintenance window	Each VM will be offline from shutdown through Gen 2 first boot (typically 5–15 minutes plus VHDX backup time)

---

PowerShell Modules

Hyper-V Path (scripts/hyperv/)

Only built-in Windows Server modules are required:

# Verify both are available (they ship with Windows Server)
Get-Module -ListAvailable Hyper-V, FailoverClusters

Module	Purpose
Hyper-V	VM management (built into Windows Server)
FailoverClusters	Cluster role management (built into Windows Server)

Azure Local Path (scripts/azurelocal/)

All of the above, plus the Az modules:

# Check installed modules
Get-Module -ListAvailable Az.Accounts, Az.Resources, Az.StackHCI, Az.ConnectedMachine

# Install Az modules if missing
Install-Module -Name Az.Accounts, Az.Resources, Az.StackHCI, Az.ConnectedMachine -Scope CurrentUser -Force

Module	Purpose
Az.Accounts	Azure authentication
Az.Resources	Azure resource management
Az.StackHCI	Azure Local / Stack HCI registration
Az.ConnectedMachine	Azure Arc connected machine management

---

Azure CLI (Azure Local Path Only)

Not required for scripts/hyperv/. Required for scripts/azurelocal/ for two purposes:

• 03-Convert-Gen1toGen2.ps1 — logs a manual az stack-hci-vm create fallback command if Arc auto-registration times out
• 05-Reconnect-AzureLocalVM.ps1 — calls az stack-hci-vm reconnect-to-azure to project the Gen 2 VM into the Azure portal

# Verify Azure CLI is installed
az --version

# Install the Stack HCI VM extension
az extension add --name stack-hci-vm

# Verify
az extension list --query "[?name=='stack-hci-vm']"

---

Azure Permissions

On Azure Local, VMs are Arc-projected by the platform through the Azure Arc resource bridge — not through an in-guest Connected Machine agent. The Azure Connected Machine Resource Administrator role applies to traditional Arc-enabled servers and is not used here.

The account running the scripts needs the following Azure Stack HCI roles on the target Azure Local instance or resource group:

Role	Reason
Azure Stack HCI Administrator	Required to register the system, create shared resources (logical networks, VM images, storage paths), and assign roles to other users. Use this role for the account running conversion scripts.
Azure Stack HCI VM Contributor	Sufficient for creating, deleting, starting, and stopping VMs and their attached resources. Use this role for scoped service accounts that don't need cluster-level access.

To verify or assign roles:

# In the Azure portal: go to your Azure Local resource
# > Access control (IAM) > Role assignments
# Assign 'Azure Stack HCI Administrator' to the account running the scripts

# Verify current Azure login
Connect-AzAccount
Get-AzContext

---

Guest VM Requirements

For each VM being converted, the guest OS must meet these requirements before running 02-Convert-MBRtoGPT.ps1:

Requirement	Details
OS bitness	64-bit only — mbr2gpt.exe does not support 32-bit Windows
Windows version	Windows Server 2019 or later (build 17763+), or Windows 10 1703 or later (build 15063+). mbr2gpt.exe ships only with those: Windows Server 2016 does not include it, and offline conversion of Windows 7, 8 and 8.1 is not supported (Learn). Upgrade older guests first. Script 02 also confirms the file exists.
BitLocker	Protection must be suspended while MBR2GPT runs. Script 02 suspends it (after asking), verifies that, and you recreate the protectors afterwards.
Partition count	Maximum 3 primary partitions on the boot disk
Partition type	No extended or logical partitions on the boot disk
Integration Services	Hyper-V Integration Services installed and current (required for synthetic NIC handoff)
Linux	See Linux VMs — requires manual GRUB reconfiguration

Checking mbr2gpt Compatibility Inside a Guest

# Run inside the guest VM — validates without making changes
.\02-Convert-MBRtoGPT.ps1 -ValidateOnly

If validation fails, check C:\Windows\setupact.log inside the guest for detailed diagnostics.

---

Finding Required Azure Resource IDs

You'll need these IDs for scripts 03 and 04:

# Custom Location ID
az customlocation list --resource-group "rg-azurelocal-prod" --query "[].id" -o tsv

# Logical Network ID
az stack-hci-vm network lnet list --resource-group "rg-azurelocal-prod" --query "[].id" -o tsv

# Subscription ID
az account show --query id -o tsv