Skip to main content

Task 01: Pre-Registration Environment Validation

Runbook Phase 04 Platform

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:

  1. 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.
  2. Connectivity — run the Environment Checker on each cluster node to confirm end-to-end reachability to all required Azure endpoints.
  3. Arc onboarding — run the Environment Checker Arc integration validator to confirm no existing Arc resource, subscription, region or limit problem will stop registration.
Two-Part Validation

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​

RequirementDetails
Phase 03 completeOS configured, hostnames set, nodes restarted
Node accessRDP or console access to each node
Internet connectivityNodes can reach PSGallery and Azure endpoints
Azure modulesAz.Accounts, Az.Resources, Az.KeyVault installed on management machine
Service principalCreated with App ID; secret stored in Key Vault
Registering user permissionsResource 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 providersAll 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.

The script accepts any one of these roles

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.

What Gets Checked
  1. SPN exists in Entra ID with the configured App ID
  2. RBAC roles — SPN has required permissions on the Arc resource group
  3. Key Vault — SPN secret is stored and accessible
  4. Arc Gateway — Gateway resource exists and is provisioned (only when the outbound path uses an Arc gateway)

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
}

Step 2: Connectivity Validation​

Run the Environment Checker on each cluster node to confirm end-to-end connectivity to all required Azure endpoints.

Why Run From the Nodes?

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.

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 check NW-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
Uninstall the Environment Checker before the deployment

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​

CheckExpected
SPN exists (Entra ID)Found with correct App ID and Display Name
RBAC role on Arc resource groupContributor or Azure Connected Machine Onboarding
Key Vault secretAccessible and enabled (not expired)
Arc GatewayExists in Azure, provisioning state Succeeded (skip with -NoArcGateway)
Current user contextAuthenticated to correct tenant and subscription
Required roles for the registering userResource 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:

ValidationExpected
Azure Resource Manager endpointSucceeded
Azure Active Directory endpointSucceeded
Azure Arc endpointsSucceeded
Graph API endpointsSucceeded
Azure Storage endpointsSucceeded
Windows Update endpointsSucceeded

Troubleshooting​

IssueResolution
SPN not foundVerify azure.automation_identity.client_id in infrastructure.yml matches Entra ID app registration
No RBAC role on RGAssign 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 accessibleCheck Key Vault access policies or RBAC; verify secret name matches the keyvault:// URI in YAML
Secret expired or disabledRotate the SPN secret in Entra ID and update Key Vault
DNS resolution failuresVerify DNS servers in node network config (Phase 03 Task 05)
Timeout errorsCheck firewall rules for node IPs
Certificate errorsAdd Azure endpoints to TLS inspection bypass
Module install failsAllow *.powershellgallery.com outbound
Arc integration validator reports existing Arc resourcesUse another resource group, or remove the Arc resources that carry the node names

Toolkit Reference

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.

↑ Phase 04 · Task 02: Register Nodes with Arc →


Version Control​

VersionDateAuthorChanges
1.0.02025-03-25Azure Local CloudInitial release