Task 01: Deploy SDN
DOCUMENT CATEGORY: Implementation Runbook
SCOPE: Azure Local clusters — post-deployment SDN enablement (Arc-integrated)
PURPOSE: Enable SDN integration on Azure Local by deploying Network Controller as a Failover Cluster service, supporting NSG management on logical networks and Azure Local VMs MASTER REFERENCE: Azure Local SDN Overview
Status: Active
SDN deployment is entirely optional. Only enable SDN if your workloads require one or more of the following:
- Network Security Groups (NSGs) applied to logical networks or VM NICs
- Centralized network policy enforcement across Azure Local VMs
- Azure portal / Azure CLI–driven network access control
Once SDN is enabled, it cannot be rolled back or disabled. There is no supported procedure to remove Network Controller after it is integrated. Do not proceed unless you are certain SDN is required for this cluster.
Additionally:
- This method (SDN enabled by Arc) is mutually exclusive with on-premises SDN tools (Windows Admin Center, SDN Express). If Network Controller was previously deployed using on-premises tools, do not use this procedure.
- If logical networks and VMs already exist, enabling SDN will cause a brief network disruption on all workloads while Virtual Filtering Platform (VFP) policies are applied. Plan a maintenance window.
When To Use SDN
| Capability | Without SDN | With SDN Enabled by Arc |
|---|---|---|
| Create logical networks | ✅ Supported | ✅ Supported |
| Apply NSGs to logical networks | ❌ Not available | ✅ Supported |
| Apply NSGs to Azure Local VM NICs | ❌ Not available | ✅ Supported |
| Software Load Balancer (SLB) | ❌ Not available | ❌ Not available (on-premises tools only) |
| VPN / L3 / GRE Gateways | ❌ Not available | ❌ Not available (on-premises tools only) |
| Manage via Azure portal / CLI | ✅ (logical networks only) | ✅ (logical networks + NSGs) |
If you only need logical networks without NSG enforcement, do not enable SDN.
Deployment Ordering
SDN should be deployed before logical networks are created to avoid workload disruption. However, enabling SDN on a cluster that already has logical networks and VMs is supported — the existing logical networks and network interfaces are automatically hydrated into the Network Controller. Plan a maintenance window in that case as VFP policy application causes a brief network outage.
Recommended order:
Phase 05: Cluster Deployment
↓
Task 01: Deploy SDN ← this task (if SDN is required)
↓
Task 02: Cluster Quorum
↓
Phase 07: Logical Networks / VM Deployment
Supported Network Intent Patterns
SDN enabled by Arc supports the following host networking configurations. Verify your cluster's intent pattern before proceeding.
| Pattern | Intents | Switched Storage | Description |
|---|---|---|---|
| Group all traffic | 1 | Required (switched only) | Single virtual switch — management, compute, and storage on one intent |
| Management+Compute / Storage | 2 | Switched or switchless (up to 4 nodes); switched only for 5+ nodes | Management and compute share one intent; storage is separate |
| Custom disaggregated | 3 | Switched or switchless (up to 4 nodes); switched only for 5+ nodes | Fully separate management, compute, and storage intents |
The following are not supported for SDN enabled by Arc:
- More than three intents on any deployment size
- Combined compute and storage intent (with or without a management intent)
- Standalone compute intent on a single-node cluster
- Three-intent configuration on two-node or three-node switchless deployments
SDN Prefix Requirements
The SDN prefix is used to construct the Network Controller REST URL:
https://<SDNPrefix>-NC.<domain>/
The prefix must satisfy all of the following:
| Rule | Requirement |
|---|---|
| Length | 1–8 characters |
| Characters | Lowercase letters, uppercase letters, digits only |
| Hyphens | Allowed, but no two consecutive hyphens (--), and must not end with a hyphen |
| Uniqueness | Must be unique across all Azure Local instances on the same domain |
Example: prefix iic01 → NC REST URL https://iic01-NC.azurelocal.cloud/
If the prefix does not meet these requirements, Add-EceFeature will fail immediately.
Configuration Variables
The script reads these keys from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.
| Key | Required | What it does |
|---|---|---|
sdn.enabled | Yes | Must be true. With false or missing the script does nothing and exits 0. |
sdn.prefix | Yes | The SDN prefix (at most 8 characters). |
sdn.dns_records | Yes | dynamic or static. |
sdn.acknowledge_maintenance_window | Yes | Must be true. It is your answer to the maintenance window question that Add-EceFeature asks. |
sdn.acknowledge_dns_record | With static DNS | Your answer to the DNS record confirmation. |
networking.management.infrastructure_pool.start and .end | Yes | The Network Controller DNS record points at the fifth address of the pool. |
networking.intents[].name and .traffic | Yes | The intent layout that the script checks against what Microsoft supports. |
scenario.identity, identity.active_directory.domain_fqdn, identity.local_identity.dns_zone | Yes | The domain of the REST URL. |
scenario.storage_architecture, scenario.storage_connectivity | Yes | Used in the intent layout check. |
nodes[].name, nodes[].management.ip_address | Yes | The machine the script connects to. |
identity.local_admin.username, identity.local_admin.password | Yes | The account for the remoting session. The password is a secret reference, never a value. |
Prerequisites
- Azure Local cluster deployed (Phase 05 complete)
- OS build 26100.x or later — verify with
systeminfo.exeon a node - Azure Stack HCI Administrator role on the Azure subscription
- Azure Stack HCI Administrator role on the cluster node
- DNS A record pre-created (static DNS environments only)
- Maintenance window scheduled if existing logical networks or VMs are present
- Network Controller was NOT previously deployed using Windows Admin Center or SDN Express
Execution
One script does the whole task. It connects to a machine of the instance with PowerShell remoting, checks the prerequisites that Microsoft Learn lists, and runs Add-EceFeature -Name NC with the prefix and the two confirmations from infrastructure.yml. There are no separate steps for the virtual switch name or for DNS: the script checks the DNS name itself and reports a record that points at the wrong address.
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-01-deploy-sdn/powershell/Enable-ArcSdn.ps1 | Turns on SDN enabled by Azure Arc (Network Controller as a Failover Cluster service) when sdn.enabled is true. This cannot be undone. |
Requires PowerShell 7. Run it first with -WhatIf: it reads the machine, checks every prerequisite, prints the plan and the warnings, and changes nothing.
./Enable-ArcSdn.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Enable-ArcSdn.ps1 -InfrastructureFile ./infrastructure.yml
Run it again later and it reports AlreadyEnabled. The action plan takes up to 20 minutes. Use -ComputerName to pick the machine and -Credential to give the account; without them the script uses the first machine of nodes[] and identity.local_admin.
What the script checks before it sends anything (exit code 2 when a value or the design is not usable): the prefix rules above, sdn.dns_records, the management infrastructure pool, the intent layout, and the two acknowledgements.
What it checks on the machine (exit code 1 when a prerequisite is not met, nothing is changed): Add-EceFeature exists, the OS build is 26100 or later, and the Network Controller DNS name resolves the way the DNS mode says. It cannot check the Azure Stack HCI Administrator role or that dynamic updates are on for the DNS zone. Check those yourself.
Where you go next. After SDN is enabled, create logical networks and network security groups with New-LogicalNetwork.ps1 and New-NetworkSecurityGroup.ps1 (Tasks 07 and 08). They read sdn.enabled. Nothing else comes with SDN enabled by Arc: no virtual networks, no software load balancer, no gateways.
Validation Summary
| Check | Command | Expected Result |
|---|---|---|
| OS build | systeminfo.exe | Select-String "OS Version" | 10.0.26100 |
| NC cluster group | Get-ClusterGroup | Where-Object Name -match "Network Controller" | State: Online |
| NC cluster resources | Get-ClusterResource | Where-Object ResourceType -match "Network" | All State: Online |
| DNS resolution | Resolve-DnsName "<SDNPrefix>-NC.<domain>" | Resolves to reserved IP |
| Azure portal | Navigate to Azure Local instance → Networking | Network Controller listed |
Validation Checklist
-
sdn.enabled,sdn.prefixand the two acknowledgements are set ininfrastructure.yml - DNS record resolves correctly (
Resolve-DnsName <SDNPrefix>-NC.<domain>) -
Add-EceFeaturecompletes with a successful action plan outcome -
Get-ClusterGroup | Where-Object Name -match "Network Controller"— stateOnline - Azure portal: Azure Local instance → Networking → Network Controller is listed
Values from infrastructure.yml
See Configuration Variables above. The sdn keys were added to schema 5 (see the infrastructure file page); the old sdn and sdn keys do not exist any more.
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
Add-EceFeature fails with action plan error | OS build mismatch or missing prerequisites | Verify OS build is 10.0.26100 with systeminfo; ensure all nodes are Arc-registered and cluster is healthy |
Network Controller cluster group shows Offline | NC VMs failed to start or quorum lost | Check NC VM status: Get-ClusterGroup | Where-Object Name -match "Network Controller"; restart the group: Start-ClusterGroup <NCGroupName> |
| DNS resolution fails for NC FQDN | DNS record not created or propagated | Create the DNS record manually: Add-DnsServerResourceRecordA -Name "<SDNPrefix>-NC" -ZoneName "<domain>" -IPv4Address "<NC-IP>" |
| SDN feature not visible in Azure portal | Arc resource bridge not synced | Wait 10-15 minutes for sync; verify bridge health: az arcappliance show --resource-group <rg> --name <appliance> |
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 |
|---|---|---|
| Phase 05: Cluster Deployment | Phase 06 Index | Task 02: Cluster Quorum |
Document maintained by Azure Local Cloud Team. Part of the Azure Local Implementation Guide.
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |