Skip to main content

Task 02: Register Cluster Nodes with Azure Arc

Runbook Phase 04 Platform

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.

Azure Authentication

Arc registration requires authenticating to Azure (not the node OS). Two methods are available:

  • ARM access token — Pass -ArmAccessToken (and -AccountID) to Invoke-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.

OEM Image Bootstrap

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:

  1. Scan — detect current OS version vs. latest baseline
  2. Download — download update package (~40-60 min depending on network)
  3. Install — apply the OS update
  4. Reboot — node reboots to complete the update (WinRM session disconnects)
  5. 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​

RequirementDetails
Task 01 passedConnectivity validation succeeded on all nodes
Registering identityThe 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)
CredentialsFor a service principal: App ID and secret available (Key Vault or secure store). For device code: an account that can sign in interactively
Machine releaseAzure Local release 2505 or later on every machine
Local administratorThe script runs as a local administrator on every machine
Node accessRDP/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​

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

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.

SettingValueSource
AuthenticationInteractive or Service PrincipalUser preference
Tenant IDFrom infrastructure.ymlazure.tenant_id
Subscription IDFrom infrastructure.ymlazure.subscription_id
Resource GroupFrom infrastructure.ymlazure.resource_group
RegionFrom infrastructure.ymlazure.location
Arc GatewayEnablednetworking.outbound.arc_gateway.name
  1. Download from aka.ms/ashciconfigurator
  2. Launch → Register with Azure Arc
  3. Fill in settings from the table above
  4. Authenticate (device code or SPN)
  5. 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
CheckExpected
himds serviceRunning
azcmagent show statusConnected
Azure Portal → Arc serversAll nodes visible

Troubleshooting​

IssueResolution
SPN auth failsVerify 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 versionTargetSolutionVersion not supplied; pass it (for example 12.2610.1004.50) for unattended, reproducible runs
Token expired mid-runRe-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 timeoutCheck node internet connectivity (Task 01)
Bootstrap reports InProgressOEM 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.

← Task 01: Pre-Registration Validation · Task 03: Monitor Bootstrap →


Version Control​

VersionDateAuthorChanges
1.0.02025-03-25Azure Local CloudInitial release
1.1.02026-11-08Azure Local CloudAligned to Learn 2610: TargetSolutionVersion, 2505 or later and local administrator prerequisites, Arc role requirements, token or device code authentication