Task 01: Pre-Registration Environment Validation
DOCUMENT CATEGORY: Runbook SCOPE: Validate identity, permissions, and connectivity before Arc registration PURPOSE: Validate identity, permissions, and connectivity before Arc registration MASTER REFERENCE: Azure Arc Requirements
Status: Active
Overview
Before registering nodes with Azure Arc, validate three categories of prerequisites:
- Identity & Permissions — verify the service principal exists, has the correct RBAC roles on the Arc resource group, and that its secret is accessible in Key Vault. If deploying interactively, verify your own account permissions.
- Connectivity — run the Environment Checker on each cluster node to confirm end-to-end reachability to all required Azure endpoints.
- Arc onboarding — run the Environment Checker Arc integration validator to confirm no existing Arc resource, subscription, region or limit problem will stop registration.
Step 1 (Identity & Permissions) runs from the management server or any Azure-authenticated machine — it validates Azure-side prerequisites. Step 2 (Connectivity) runs on or against each cluster node — it validates network-level reachability from the node OS itself.
Prerequisites
| Requirement | Details |
|---|---|
| Phase 03 complete | OS configured, hostnames set, nodes restarted |
| Node access | RDP or console access to each node |
| Internet connectivity | Nodes can reach PSGallery and Azure endpoints |
| Azure modules | Az.Accounts, Az.Resources, Az.KeyVault installed on management machine |
| Service principal | Created with App ID; secret stored in Key Vault |
| Registering user permissions | Resource group owner, or both Azure Connected Machine Onboarding and Azure Connected Machine Resource Administrator on the Arc resource group (Learn: Assign required permissions for Azure Local deployment) |
| Domain join (optional, 2604 and later) | If the nodes were domain joined before deployment, the deployment user is in the local Administrators group of every node. If they were not, the deployment joins them to the domain, so being in a workgroup at this point is expected. Run the Environment Checker software validator with -Exclude Test-IsNotPartofDomain |
| Resource providers | All 13 required resource providers registered, including Microsoft.KeyVault and Microsoft.Insights (see the prerequisites page) |
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.
Step 1: Identity & Permission Checks
Verify the service principal (or interactive user) has the required Azure permissions before connecting to cluster nodes. Run from the management server or any machine with Azure authentication.
Learn 2610 says the person who registers the machines must be the resource group owner or have both Azure Connected Machine Onboarding and Azure Connected Machine Resource Administrator on the resource group. The check below passes when it finds any one accepted role, so confirm both roles under Access control (IAM) on the Arc resource group. The deployment user (not the registering user) needs a separate set of roles on the resource group: Azure Stack HCI Administrator, Reader, Key Vault Data Access Administrator, Key Vault Secrets Officer, Key Vault Contributor and Storage Account Contributor, and on the subscription both user access administrator and contributor.
- SPN exists in Entra ID with the configured App ID
- RBAC roles — SPN has required permissions on the Arc resource group
- Key Vault — SPN secret is stored and accessible
- Arc Gateway — Gateway resource exists and is provisioned (only when the outbound path uses an Arc gateway)
- Direct (Manual)
- Orchestrated Script
- Azure CLI
Run from any machine with an active Azure session.
# Task 01 Step 1 — Identity & Permission Checks (manual)
Connect-AzAccount -TenantId "REPLACE_TENANT_ID" -SubscriptionId "REPLACE_SUBSCRIPTION_ID"
$SpnAppId = "REPLACE_SPN_APP_ID"
$ResourceGroup = "REPLACE_RESOURCE_GROUP"
$VaultName = "REPLACE_VAULT_NAME"
$SecretName = "REPLACE_SECRET_NAME"
if ($SpnAppId -match '^REPLACE_') { throw 'Edit the REPLACE_ variables before running.' }
# --- Check 1: Verify SPN exists in Entra ID ---
$spn = Get-AzADServicePrincipal -ApplicationId $SpnAppId -ErrorAction SilentlyContinue
if ($spn) {
Write-Host "[PASS] SPN exists: $($spn.DisplayName) ($SpnAppId)" -ForegroundColor Green
} else {
Write-Host "[FAIL] SPN not found: $SpnAppId" -ForegroundColor Red
}
# --- Check 2: Verify RBAC roles on the Arc resource group ---
if ($spn) {
$roles = Get-AzRoleAssignment -ObjectId $spn.Id -ResourceGroupName $ResourceGroup `
-ErrorAction SilentlyContinue
$roles | Format-Table RoleDefinitionName, Scope -AutoSize
$accepted = @(
'Contributor',
'Azure Connected Machine Onboarding',
'Azure Connected Machine Resource Administrator',
'Azure Stack HCI Administrator'
)
$matched = $roles | Where-Object { $_.RoleDefinitionName -in $accepted }
if ($matched) {
$matched | ForEach-Object {
Write-Host "[PASS] Role: $($_.RoleDefinitionName)" -ForegroundColor Green
}
} else {
Write-Host "[FAIL] No recognized Arc role on '$ResourceGroup'" -ForegroundColor Red
Write-Host " Assign: Azure Connected Machine Onboarding (minimum)" -ForegroundColor Yellow
}
}
# --- Check 3: Verify Key Vault has SPN secret ---
$secret = Get-AzKeyVaultSecret -VaultName $VaultName -Name $SecretName -ErrorAction SilentlyContinue
if ($secret -and $secret.Enabled) {
Write-Host "[PASS] KV secret '$SecretName' accessible and enabled" -ForegroundColor Green
if ($secret.Expires -and $secret.Expires -lt (Get-Date).AddDays(30)) {
Write-Host "[WARN] Secret expires $($secret.Expires) — renew soon" -ForegroundColor Yellow
}
} elseif ($secret) {
Write-Host "[WARN] KV secret '$SecretName' exists but is DISABLED" -ForegroundColor Yellow
} else {
Write-Host "[FAIL] KV secret '$SecretName' not found in vault '$VaultName'" -ForegroundColor Red
}
PowerShell
No PowerShell script in this task folder.
Invoke-ArcPrerequisites-Orchestrated.ps1is a placeholder: it printsNOT IMPLEMENTED, changes nothing and exits with code 3. The earlierTest-ArcPrerequisites.ps1andTest-ArcPrerequisites-Orchestrated.ps1are removed. The pre-cluster verification checks the Azure side, and the Azure CLI tab has a script for it.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-05-cluster-deployment/Invoke-AzureLocalPreClusterVerification.ps1 | The pre-cluster verification. Read only. Its azure category checks the subscription, the resource group, the resource providers, the Key Vault references and the Arc endpoints. |
Run
./Invoke-AzureLocalPreClusterVerification.ps1 -InfrastructureFile ./infrastructure.yml -Mode Verify -Category azure
A run with -Category is partial: it ends with exit code 3 when nothing blocks, and it never passes the ARM precondition.
Azure CLI
When to use: Check the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
azand only reads Azure.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-04-arc-registration/task-01-pre-registration-validation/azurecli/Test-ArcPrerequisites.azcli.ps1 | Checks the Azure side of the Arc registration with the Azure CLI: the subscription, the resource group, the resource providers and the roles of the signed-in account. Read only. Supports -WhatIf (lists the checks and runs none). |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
Azure side only: the Environment Checker of the next step runs on the machines and is not an Azure CLI task. It does not change the Azure CLI default subscription. Reading the role assignments of the account needs permission to read role assignments and, for a signed-in user, its own directory object.
Run
./Test-ArcPrerequisites.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Test-ArcPrerequisites.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Step 2: Connectivity Validation
Run the Environment Checker on each cluster node to confirm end-to-end connectivity to all required Azure endpoints.
OS configuration is now complete on the cluster nodes. Running Environment Checker directly from the nodes confirms that DNS, firewall, and NIC configuration all work end-to-end from the node itself — not just from the management network.
- Orchestrated Script
PowerShell
No script in this task folder. The pre-cluster verification probes the endpoints from each node: check
AZ-023(the Azure Arc endpoints on 443) and checkNW-005(the documented outbound endpoints, directly or through the proxy).
Run
./Invoke-AzureLocalPreClusterVerification.ps1 -InfrastructureFile ./infrastructure.yml -Mode Verify -Category azure,network
Step 3: Arc Integration Validation and Cleanup
Run the Environment Checker Arc integration validator from any Azure Local machine, signed in to the account that will register the machines. It checks that the Arc resource group has no Arc resources with the node names, that no node is already Arc-enabled in another subscription or resource group, that the Azure region is valid, and that the resource group, Azure Local resource and role assignment count limits are not reached. Full detail: Phase 02 Task 05: Environment Checker Readiness.
Connect-AzAccount -Tenant <tenant-id> -Subscription <subscription-id> -DeviceCode
$nodes = [string[]]("node1","node2","node3","node4")
Invoke-AzStackHciArcIntegrationValidation `
-SubscriptionID <subscription-id> `
-RegistrationResourceGroupName <arc-resource-group> `
-ArcResourceGroupName <arc-resource-group> `
-NodeNames $nodes
The Environment Checker ships with Azure Local. A copy you installed from the PowerShell Gallery on a node for Step 2 or Step 3 must be uninstalled from every Azure Local machine before the deployment begins, to avoid potential conflicts. The cleanup is in Task 05, Step 8. Do it after Arc registration (Task 02) and before Phase 05.
Expected Results
Identity & Permissions
| Check | Expected |
|---|---|
| SPN exists (Entra ID) | Found with correct App ID and Display Name |
| RBAC role on Arc resource group | Contributor or Azure Connected Machine Onboarding |
| Key Vault secret | Accessible and enabled (not expired) |
| Arc Gateway | Exists in Azure, provisioning state Succeeded (skip with -NoArcGateway) |
| Current user context | Authenticated to correct tenant and subscription |
| Required roles for the registering user | Resource group owner, or both Azure Connected Machine Onboarding and Azure Connected Machine Resource Administrator on the Arc resource group |
Connectivity
All Environment Checker tests should show Succeeded:
| Validation | Expected |
|---|---|
| Azure Resource Manager endpoint | Succeeded |
| Azure Active Directory endpoint | Succeeded |
| Azure Arc endpoints | Succeeded |
| Graph API endpoints | Succeeded |
| Azure Storage endpoints | Succeeded |
| Windows Update endpoints | Succeeded |
Troubleshooting
| Issue | Resolution |
|---|---|
| SPN not found | Verify azure.automation_identity.client_id in infrastructure.yml matches Entra ID app registration |
| No RBAC role on RG | Assign both Azure Connected Machine Onboarding and Azure Connected Machine Resource Administrator on the Arc resource group (Learn requires both, or resource group owner) |
| KV secret not accessible | Check Key Vault access policies or RBAC; verify secret name matches the keyvault:// URI in YAML |
| Secret expired or disabled | Rotate the SPN secret in Entra ID and update Key Vault |
| DNS resolution failures | Verify DNS servers in node network config (Phase 03 Task 05) |
| Timeout errors | Check firewall rules for node IPs |
| Certificate errors | Add Azure endpoints to TLS inspection bypass |
| Module install fails | Allow *.powershellgallery.com outbound |
| Arc integration validator reports existing Arc resources | Use another resource group, or remove the Arc resources that carry the node names |
Scripts for this task are located in the azurelocal-toolkit repository under scripts/deploy/ in the appropriate task folder.
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
↑ Phase 04 · Task 02: Register Nodes with Arc →
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |