Task 02: Arc Connectivity Validation
DOCUMENT CATEGORY: Implementation Runbook
SCOPE: Every node of a deployed Azure Local cluster
PURPOSE: Check the Arc agent, its extensions and the Arc endpoints from the nodes themselves
MASTER REFERENCE: Azure Connected Machine agent CLI reference
Status: Active
What Azure shows about the Arc machines (status, extensions, identity) is Phase 04, Task 04, which has its own Azure CLI script. This task is the node side: what the machine itself reports and can reach. That is why it has no Azure CLI script. It changes nothing.
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.
| Key | What the script does with it |
|---|---|
cluster.name | The cluster whose nodes (those that are Up) are asked |
azure.location | The region of the endpoint list. The list is the one documented list of the toolkit (Learn: Firewall requirements for Azure Local); the script has no host of its own |
Execution Options
- PowerShell on a cluster machine
- PowerShell
PowerShell on a cluster machine
On each node:
& "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" show
& "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" extension list
Test-NetConnection -ComputerName <endpoint host> -Port 443
PowerShell
| Script | What it does |
|---|---|
scripts/deploy/07-validation-handover/task-02-arc-connectivity-validation/powershell/Test-ArcConnectivity.ps1 | Over PowerShell remoting, per node that is Up: the agent (Connected passes, Disconnected fails), the extensions (a state other than Succeeded warns) and a TCP connection on 443 to every endpoint of the list (a required host that cannot be reached fails, an optional one warns) |
| Parameter | Meaning |
|---|---|
-InfrastructureFile | The infrastructure.yml (schema 5). Required |
-Credential | The account for the remoting sessions. Without it the account that runs the script is used |
-OutputPath | A folder: the results are also saved there as arc-connectivity-<date>-<time>.json |
./Test-ArcConnectivity.ps1 -InfrastructureFile ./infrastructure.yml -OutputPath ./handover
Exit codes: 0 no check failed, 1 a check failed or the cluster could not be read, 2 cluster.name or azure.location is missing, or the file cannot be read.
Validation
- Every node:
AgentisPassed(Connected) - Every node:
EndpointsisPassed -
ExtensionsisPassed, or the warning is understood (they install some time after the registration)
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
Endpoints fails for one host | A firewall or proxy blocks 443 | Open the host (Learn: Firewall requirements for Azure Local). The Arc gateway and a proxy change the path: the TCP probe only describes a direct path |
Agent is Disconnected | The agent cannot reach Azure, or the machine was deleted in Azure | azcmagent show on the node shows the error |
azure.location is missing | The region is not in the file | Set azure.location |
Navigation
| Previous | Up | Next |
|---|---|---|
| Task 01: Cluster Health | Part 7 Index | Task 03: Network Configuration |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-11-15 | Azure Local Cloud | Initial release. The script was rewritten to the toolkit rules: no host of its own, no Azure call, exit codes 0, 1 and 2 |