Task 04 — SSH Connectivity to Nodes
DOCUMENT CATEGORY: Implementation Guide SCOPE: Azure Local Cluster Nodes — Post-Deployment PURPOSE: Deploy the Open SSH for Windows Arc VM extension on each cluster node and MASTER REFERENCE: OpenSSH in Windows Server configure Azure Arc SSH tunneled access (HybridConnectivity) so operators can reach nodes securely without opening inbound firewall ports or requiring direct network adjacency.
Status: Active
Overview
Azure Arc SSH routes connections through the HybridConnectivity relay — no public IP, no open inbound port 22 on upstream firewalls. The flow is:
Operator workstation → Azure Relay (HybridConnectivity) → Arc agent → WindowsOpenSSH (sshd)
This task installs OpenSSH using the first-party WindowsOpenSSH Arc VM extension
(publisher: Microsoft.Azure.OpenSSH, type: WindowsOpenSSH) — avoiding any WinRM/PSRemoting
dependency — and configures the HybridConnectivity endpoint on each Arc-enrolled node.
Each node must already be Arc-enrolled (completed in
Phase 01 — Arc Registration).
Arc agent version ≥ 1.31 is required. Check with azcmagent version on each node.
Extension Reference
| Field | Value |
|---|---|
| Display Name | Open SSH for Windows |
| Publisher | Microsoft.Azure.OpenSSH |
| Type | WindowsOpenSSH |
| Extension Name | WindowsOpenSSH |
| Installs | OpenSSH Server (sshd), sets service to Automatic, creates Windows Firewall rule |
Prerequisites
| Requirement | Details |
|---|---|
| Azure permissions | Contributor or Owner on the subscription (register RP + create endpoints) |
| Arc extension deploy | microsoft.hybridcompute/machines/extensions/write on each Arc machine resource |
| Azure CLI (scripts) | az CLI logged in (az account show); az extension add --name ssh |
| YAML key (toolkit script) | nodes[].arc_machine_name per node (default: nodes[].name) |
After this task, operators connecting via az ssh arc need the
Virtual Machine Local User Login role on each Arc machine resource.
RBAC assignments are out of scope for this task — assign at resource group level to avoid
hitting the per-subscription role assignment limit.
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
azure.subscription_id, azure.resource_group, azure.location
nodes[].name, nodes[].arc_machine_name
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
When to use:
- Ad-hoc installs or verifying extension state on individual nodes
- No scripting environment available
- Post-deployment check or re-install of a specific node
Step 1 — Install the WindowsOpenSSH extension (per node)
Repeat for each cluster node.
- Open the Azure portal and navigate to Azure Arc → Machines
- Select the Arc machine for the first node (e.g.
azl-demo-01-n01) - In the left menu under Settings, select Extensions
- Click + Add
- Find and select Open SSH for Windows (publisher:
Microsoft.Azure.OpenSSH) - Click Next → accept defaults → Review + create → Create
- Wait for the extension to show Succeeded in the Extensions list
- Repeat steps 2–7 for every cluster node
After install, confirm the extension state in the portal Extensions blade shows
ProvisioningState: Succeeded. You can also query via CLI:
az connectedmachine extension show `
--resource-group "rg-c01-azl-eus-01" `
--machine-name "azl-demo-01-n01" `
--name "WindowsOpenSSH"
Step 2 — Configure HybridConnectivity (once per subscription + per node)
2a — Register the resource provider (one-time per subscription):
# Register RP (one-time per subscription)
az provider register -n Microsoft.HybridConnectivity
az extension add --name ssh
# Poll until registered
do {
Start-Sleep 15
$state = az provider show -n Microsoft.HybridConnectivity --query registrationState -o tsv
Write-Host "RP state: $state"
} until ($state -eq 'Registered')
# Run the following block once per node — change $machine each time
$sub = "00000000-0000-0000-0000-000000000000"
$rg = "rg-c01-azl-eus-01"
$machine = "azl-demo-01-n01" # <-- change per node
# Create default connectivity endpoint
az rest `
--method put `
--uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.HybridCompute/machines/$machine/providers/Microsoft.HybridConnectivity/endpoints/default?api-version=2023-03-15" `
--body '{\"properties\":{\"type\":\"default\"}}'
# Configure SSH service on the endpoint
az rest `
--method put `
--uri "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.HybridCompute/machines/$machine/providers/Microsoft.HybridConnectivity/endpoints/default/serviceconfigurations/SSH?api-version=2023-03-15" `
--body '{\"properties\":{\"serviceName\":\"SSH\",\"port\":22}}'
Connecting:
az ssh arc `
--resource-group "rg-c01-azl-eus-01" `
--name "azl-demo-01-n01" `
--local-user "DOMAIN\username"
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-04-ssh-connectivity-to-nodes/powershell/Invoke-SSHConnectivity-Orchestrated.ps1 | Deploys the WindowsOpenSSH Arc extension and configures HybridConnectivity SSH access on all Azure Local cluster nodes. It reads nodes[] and nodes[].arc_machine_name. |
The earlier Enable-SshConfiguration.ps1 is removed. The script never prompts. The Azure CLI tab has a script that turns SSH on through Azure Arc from a host that has the Azure CLI.
Requires: PowerShell 7.
Run
./Invoke-SSHConnectivity-Orchestrated.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Invoke-SSHConnectivity-Orchestrated.ps1 -InfrastructureFile ./infrastructure.yml
./Invoke-SSHConnectivity-Orchestrated.ps1 -InfrastructureFile ./infrastructure.yml -TargetNode iic-azl-n01
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-04-ssh-connectivity-to-nodes/azurecli/Enable-ArcSshConnectivity.azcli.ps1 | Turns on SSH access to the Azure Local machines through Azure Arc with the Azure CLI: the WindowsOpenSSH extension, the HybridConnectivity endpoint and the SSH service configuration. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>. Needs the Azure CLI extension connectedmachine (az extension add --name connectedmachine); the script does not install it.
Nothing reaches the machines from here (no WinRM, no remoting): the Arc agent installs OpenSSH. The script registers Microsoft.HybridConnectivity when needed and waits for it (-MaxWaitMinutes). -TargetNode limits the run to some nodes; -SshdPort sets the port written to the SSH service configuration (default 22). After the task connect with az ssh arc. You need Contributor or Owner, or Azure Connected Machine Resource Administrator.
Run
./Enable-ArcSshConnectivity.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Enable-ArcSshConnectivity.azcli.ps1 -InfrastructureFile ./infrastructure.yml
./Enable-ArcSshConnectivity.azcli.ps1 -InfrastructureFile ./infrastructure.yml -TargetNode <node-name>
Validation
1 — Verify extension state on all nodes
$sub = "00000000-0000-0000-0000-000000000000"
$rg = "rg-c01-azl-eus-01"
foreach ($machine in @("azl-demo-01-n01", "azl-demo-01-n02")) {
$state = az connectedmachine extension show `
--resource-group $rg `
--machine-name $machine `
--name "WindowsOpenSSH" `
--query "provisioningState" `
-o tsv
Write-Host "$machine WindowsOpenSSH = $state" -ForegroundColor $(if ($state -eq 'Succeeded') {'Green'} else {'Red'})
}
2 — Verify HybridConnectivity SSH endpoint
$sub = "00000000-0000-0000-0000-000000000000"
$rg = "rg-c01-azl-eus-01"
foreach ($machine in @("azl-demo-01-n01", "azl-demo-01-n02")) {
$uri = "https://management.azure.com/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.HybridCompute/machines/$machine/providers/Microsoft.HybridConnectivity/endpoints/default/serviceconfigurations/SSH?api-version=2023-03-15"
Write-Host "`nNode: $machine"
az rest --method get --uri $uri | ConvertFrom-Json | Select-Object -ExpandProperty properties
}
Expected output per node:
{
"serviceName": "SSH",
"port": 22,
"resourceProvisioningState": "Succeeded"
}
3 — Test an Arc SSH connection
az ssh arc `
--resource-group "rg-c01-azl-eus-01" `
--name "azl-demo-01-n01" `
--local-user "DOMAIN\username" `
--command "hostname"
Validation Summary
| Check | Command | Expected |
|---|---|---|
| Extension installed | az connectedmachine extension show ... --query provisioningState | Succeeded |
| HybridConnectivity RP | az provider show -n Microsoft.HybridConnectivity --query registrationState -o tsv | Registered |
| SSH endpoint | az rest --method get --uri .../serviceconfigurations/SSH | resourceProvisioningState: Succeeded |
| Arc SSH connect | az ssh arc ... --command hostname | Returns node hostname |
RBAC — Operator Access
The WindowsOpenSSH extension and HybridConnectivity endpoint control infrastructure.
Each operator who needs to CONNECT via Arc SSH also needs the Virtual Machine Local User Login
role on the Arc machine resources (or the containing resource group):
$sub = "00000000-0000-0000-0000-000000000000"
$rg = "rg-c01-azl-eus-01"
$objectId = "<operator-or-group-entra-object-id>"
az role assignment create `
--role "Virtual Machine Local User Login" `
--assignee $objectId `
--scope "/subscriptions/$sub/resourceGroups/$rg"
Microsoft Entra ID SSH login (AADSSHLoginForLinux) is Linux-only. On Windows nodes,
sshd authenticates with Windows credentials (local or domain accounts). The
Virtual Machine Local User Login RBAC role only controls who can open the
HybridConnectivity tunnel — not who can authenticate to sshd itself.
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
| SSH connection refused on port 22 | sshd service not running or Windows Firewall blocking | Start service: Start-Service sshd; Set-Service sshd -StartupType Automatic; verify firewall: Get-NetFirewallRule -Name *ssh* |
| Arc SSH tunnel fails with RBAC error | User lacks Virtual Machine Local User Login role | Assign the role: az role assignment create --role "Virtual Machine Local User Login" --assignee <objectId> --scope <resourceScope> |
| Authentication fails with valid credentials | sshd_config not configured for password or key auth | Edit C:\ProgramData\ssh\sshd_config to enable PasswordAuthentication yes or configure authorized keys; restart: Restart-Service sshd |
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
| Previous | Up | Next |
|---|---|---|
| Task 3: Security Groups | Phase 06 Index | Task 5: Storage Configuration |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |