Task 02: Register Cluster Nodes with Azure Arc
DOCUMENT CATEGORY: Runbook SCOPE: Arc-enable each Azure Local cluster node using Invoke-AzStackHciArcInitializa... PURPOSE: Arc-enable each Azure Local cluster node using Invoke-AzStackHciArcInitialization MASTER REFERENCE: Register Azure Local with Azure Arc
Status: Active
Overview
Register all cluster nodes with Azure Arc using Invoke-AzStackHciArcInitialization. Arc registration is a mandatory prerequisite for Azure Local cloud deployment — without it, the deployment orchestrator cannot communicate with the cluster.
Arc registration requires authenticating to Azure (not the node OS). Two methods are available:
- ARM access token — Pass
-ArmAccessToken(and-AccountID) toInvoke-AzStackHciArcInitialization. Microsoft Learn documents this as the non-interactive option; if you omit-ArmAccessToken, the script prompts for device code authentication. The token can come from a service principal sign-in (Connect-AzAccount -ServicePrincipal) or from your own interactive sign-in. Using a service principal to obtain the token is an Azure Local Cloud organisation choice for unattended runs, not a Learn requirement. - Device code — Interactive browser-based login. Learn's default when no token is supplied; also available in the Direct tab through
Connect-AzAccount -DeviceCode.
Run the script as a local administrator on every machine you intend to cluster. The machines must run release 2505 or later. Microsoft Learn 2610 also notes that Invoke-AzStackHciArcInitialization accepts an optional TargetSolutionVersion: the Azure Local solution version used for the initial deployment after registration. If you omit it, the script prompts you to choose from the available versions. Pin it (for 2610 deployments, 12.2610.1004.50, the 2610 build in the release information) so that every machine gets the same, reproducible version.
Node access (RDP for Direct, WinRM for Orchestrated) is separate — it uses the management server session context or your RDP session. No node credentials are passed to Azure.
When nodes ship with a preinstalled or outdated Azure Stack HCI OS image (Dell, HPE, Lenovo, etc.), Invoke-AzStackHciArcInitialization triggers an automatic OS update cycle:
- Scan — detect current OS version vs. latest baseline
- Download — download update package (~40-60 min depending on network)
- Install — apply the OS update
- Reboot — node reboots to complete the update (WinRM session disconnects)
- Resume — bootstrap service resumes Arc registration using cached SPN token
This is expected behavior. The Invoke-AzStackHciArcInitialization cmdlet manages the full update + reboot + resume cycle internally. The synchronous Invoke-Command session stays alive through reboots — no manual intervention required. Run Task 03 in a separate window to monitor OEM update progress.
See: Handle preinstalled or outdated OS images during Azure Arc registration
Prerequisites
| Requirement | Details |
|---|---|
| Task 01 passed | Connectivity validation succeeded on all nodes |
| Registering identity | The identity whose token is used has Azure Connected Machine Onboarding and Azure Connected Machine Resource Administrator on the Arc resource group (or is the resource group owner), per Microsoft Learn. If you use a service principal, give it those roles (Contributor alone is not what Learn specifies) |
| Credentials | For a service principal: App ID and secret available (Key Vault or secure store). For device code: an account that can sign in interactively |
| Machine release | Azure Local release 2505 or later on every machine |
| Local administrator | The script runs as a local administrator on every machine |
| Node access | RDP/console (Direct) or WinRM from mgmt server (Orchestrated) |
Values from infrastructure.yml
The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.
Execution
- Direct (On Node)
- Orchestrated Script
Run on each node individually via RDP or console.
Option A: Service Principal Authentication (Production)
# Task 02 - Register Node with Azure Arc (SPN auth, run on each node)
$TenantId = "REPLACE_TENANT_ID"
$SubscriptionId = "REPLACE_SUBSCRIPTION_ID"
$ResourceGroup = "REPLACE_RESOURCE_GROUP"
$Region = "REPLACE_REGION"
$Cloud = "AzureCloud"
$ArcGatewayId = "REPLACE_ARC_GATEWAY_ID"
$TargetSolutionVersion = "REPLACE_TARGET_SOLUTION_VERSION" # e.g. 12.2610.1004.50 (omit the parameter to be prompted)
$SpnId = "REPLACE_SPN_ID"
if ($TenantId -match '^REPLACE_') { throw 'Edit the REPLACE_ variables before running.' }
# Prompt for SPN secret securely (never hardcode secrets in scripts)
$SpnSecure = Read-Host "Enter SPN secret" -AsSecureString
$SpnSecret = [System.Net.NetworkCredential]::new('', $SpnSecure).Password
# Authenticate with service principal
$SecurePassword = ConvertTo-SecureString $SpnSecret -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential($SpnId, $SecurePassword)
Connect-AzAccount -ServicePrincipal -TenantId $TenantId -Credential $Credential -SubscriptionId $SubscriptionId
# Get ARM access token
$ArmToken = (Get-AzAccessToken).Token
$AccountId = $SpnId
# Register this node with Arc
Invoke-AzStackHciArcInitialization `
-SubscriptionID $SubscriptionId `
-ResourceGroup $ResourceGroup `
-TenantID $TenantId `
-Region $Region `
-Cloud $Cloud `
-ArmAccessToken $ArmToken `
-AccountID $AccountId `
-ArcGatewayID $ArcGatewayId `
-TargetSolutionVersion $TargetSolutionVersion
Option B: Device Code Authentication (Lab/Test)
# Task 02 - Register Node with Azure Arc (device code auth, run on each node)
$TenantId = "REPLACE_TENANT_ID"
$SubscriptionId = "REPLACE_SUBSCRIPTION_ID"
$ResourceGroup = "REPLACE_RESOURCE_GROUP"
$Region = "REPLACE_REGION"
$Cloud = "AzureCloud"
$ArcGatewayId = "REPLACE_ARC_GATEWAY_ID"
$TargetSolutionVersion = "REPLACE_TARGET_SOLUTION_VERSION" # e.g. 12.2610.1004.50 (omit the parameter to be prompted)
if ($TenantId -match '^REPLACE_') { throw 'Edit the REPLACE_ variables before running.' }
# Authenticate interactively — opens a browser prompt via device code
Connect-AzAccount -TenantId $TenantId -SubscriptionId $SubscriptionId -DeviceCode
# Get ARM access token
$ArmToken = (Get-AzAccessToken).Token
$AccountId = (Get-AzContext).Account.Id
# Register this node with Arc
Invoke-AzStackHciArcInitialization `
-SubscriptionID $SubscriptionId `
-ResourceGroup $ResourceGroup `
-TenantID $TenantId `
-Region $Region `
-Cloud $Cloud `
-ArmAccessToken $ArmToken `
-AccountID $AccountId `
-ArcGatewayID $ArcGatewayId `
-TargetSolutionVersion $TargetSolutionVersion
PowerShell
No script in this task folder. The folder holds only a placeholder (
Invoke-ArcRegistration-Orchestrated.ps1). A placeholder printsNOT IMPLEMENTED, changes nothing and exits with code 3. The task has no Azure CLI script: the registration runs on each node, and the Azure CLI has no command that registers an Azure Local machine. The Azure side is checked in Task 01 and Task 04, which have Azure CLI scripts. The earlierRegister-NodesWithArc.ps1andRegister-AzureLocalArc-Remote.ps1are removed. The OS configuration registers a machine that was installed from an ISO in its ArcRegistration step. A machine that ZTP provisioned is already registered.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-03-os-configuration/Invoke-AzureLocalOsConfiguration.ps1 | The ArcRegistration step looks the Arc machine up in Azure. When it is missing or not Connected, it runs Invoke-AzStackHciArcInitialization on the node over WinRM, with an ARM token from the run's own Azure sign-in. |
The step reads azure.subscription_id, azure.resource_group, deployment.solution_version (passed as TargetSolutionVersion, so the cmdlet never asks), and the proxy and bypass list of the outbound path (networking.outbound.proxy or networking.outbound.private_path). When the path needs a value the file does not give, the node is Blocked in the plan. The nodes' local administrator comes from identity.local_admin (a secret reference) or -Credential. The script never prompts.
The tries and the wait are run settings (registry 5.0.60), given in the JSON file of -SettingsFile or in -Settings:
| Setting | Default | What it does |
|---|---|---|
arcRegistrationTries | 3 | Tries of the registration when a new try can fix the failure (stale resource, token, logon session) |
arcRegistrationWaitMinutes | 20 | How long the run waits for the node's Arc machine to be Connected after the registration |
Run
Connect-AzAccount # the run uses this sign-in for the ARM token
# Plan (the default): which machines would be registered
./Invoke-AzureLocalOsConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -Step ArcRegistration
# Apply
./Invoke-AzureLocalOsConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -Step ArcRegistration -Mode Apply
Alternative: Configurator App (Preview)
Microsoft provides a GUI wizard — the Azure Stack HCI Configurator App — that simplifies Arc registration for smaller or first-time deployments.
| Setting | Value | Source |
|---|---|---|
| Authentication | Interactive or Service Principal | User preference |
| Tenant ID | From infrastructure.yml | azure.tenant_id |
| Subscription ID | From infrastructure.yml | azure.subscription_id |
| Resource Group | From infrastructure.yml | azure.resource_group |
| Region | From infrastructure.yml | azure.location |
| Arc Gateway | Enabled | networking.outbound.arc_gateway.name |
- Download from aka.ms/ashciconfigurator
- Launch → Register with Azure Arc
- Fill in settings from the table above
- Authenticate (device code or SPN)
- Click Register and wait for completion
Reference: Microsoft Learn — Use Configurator for Arc Registration
Watch the Registration
For OEM image scenarios the nodes can reboot during registration while they install OEM updates. Do not restart the registration script when a node reboots: the bootstrap service resumes by itself.
The toolkit has no monitoring script for this. Watch the registration and the bootstrap with Azure Local Sonar. Start it in a second window before you register:
Connect-AzAccount
./Start-AzlSonar.ps1 -InfrastructureFile ./infrastructure.yml
Sonar reads the nodes and the Azure targets from the same infrastructure.yml. It only reads. Task 03 shows the status commands you can run on a node.
Expected Outcomes
After registration completes on each node, confirm:
# Quick check — run on any node
Get-Service himds | Select-Object Name, Status
& "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" show
| Check | Expected |
|---|---|
himds service | Running |
azcmagent show status | Connected |
| Azure Portal → Arc servers | All nodes visible |
Troubleshooting
| Issue | Resolution |
|---|---|
| SPN auth fails | Verify App ID/Secret and that the identity has Azure Connected Machine Onboarding and Azure Connected Machine Resource Administrator on the Arc resource group |
| Prompted to choose a solution version | TargetSolutionVersion not supplied; pass it (for example 12.2610.1004.50) for unattended, reproducible runs |
| Token expired mid-run | Re-run Connect-AzAccount and get a fresh token |
| WinRM denied (OS configuration) | Confirm WinRM is enabled from Phase 03 and that identity.local_admin holds the local administrator. Pass -Credential to use another account |
| Arc init timeout | Check node internet connectivity (Task 01) |
| Bootstrap reports InProgress | OEM updates or registration still running — run Task 03 to monitor |
| Bootstrap reports Failed (401) | SPN token expired or session lost — re-run registration with fresh auth |
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
← Task 01: Pre-Registration Validation · Task 03: Monitor Bootstrap →
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |
| 1.1.0 | 2026-11-08 | Azure Local Cloud | Aligned to Learn 2610: TargetSolutionVersion, 2505 or later and local administrator prerequisites, Arc role requirements, token or device code authentication |