Skip to main content

Task 01: Deploy SDN

Implementation Cluster Deployment

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

OPTIONAL — IRREVERSIBLE — READ BEFORE PROCEEDING

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​

CapabilityWithout SDNWith 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.

PatternIntentsSwitched StorageDescription
Group all traffic1Required (switched only)Single virtual switch — management, compute, and storage on one intent
Management+Compute / Storage2Switched or switchless (up to 4 nodes); switched only for 5+ nodesManagement and compute share one intent; storage is separate
Custom disaggregated3Switched or switchless (up to 4 nodes); switched only for 5+ nodesFully separate management, compute, and storage intents
Unsupported Intent Configurations

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:

RuleRequirement
Length1–8 characters
CharactersLowercase letters, uppercase letters, digits only
HyphensAllowed, but no two consecutive hyphens (--), and must not end with a hyphen
UniquenessMust 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.

KeyRequiredWhat it does
sdn.enabledYesMust be true. With false or missing the script does nothing and exits 0.
sdn.prefixYesThe SDN prefix (at most 8 characters).
sdn.dns_recordsYesdynamic or static.
sdn.acknowledge_maintenance_windowYesMust be true. It is your answer to the maintenance window question that Add-EceFeature asks.
sdn.acknowledge_dns_recordWith static DNSYour answer to the DNS record confirmation.
networking.management.infrastructure_pool.start and .endYesThe Network Controller DNS record points at the fifth address of the pool.
networking.intents[].name and .trafficYesThe intent layout that the script checks against what Microsoft supports.
scenario.identity, identity.active_directory.domain_fqdn, identity.local_identity.dns_zoneYesThe domain of the REST URL.
scenario.storage_architecture, scenario.storage_connectivityYesUsed in the intent layout check.
nodes[].name, nodes[].management.ip_addressYesThe machine the script connects to.
identity.local_admin.username, identity.local_admin.passwordYesThe 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.exe on 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.

ScriptWhat it does
scripts/deploy/04-cluster-deployment/phase-06-post-deployment/task-01-deploy-sdn/powershell/Enable-ArcSdn.ps1Turns 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​

CheckCommandExpected Result
OS buildsysteminfo.exe | Select-String "OS Version"10.0.26100
NC cluster groupGet-ClusterGroup | Where-Object Name -match "Network Controller"State: Online
NC cluster resourcesGet-ClusterResource | Where-Object ResourceType -match "Network"All State: Online
DNS resolutionResolve-DnsName "<SDNPrefix>-NC.<domain>"Resolves to reserved IP
Azure portalNavigate to Azure Local instance → NetworkingNetwork Controller listed

Validation Checklist​

  • sdn.enabled, sdn.prefix and the two acknowledgements are set in infrastructure.yml
  • DNS record resolves correctly (Resolve-DnsName <SDNPrefix>-NC.<domain>)
  • Add-EceFeature completes with a successful action plan outcome
  • Get-ClusterGroup | Where-Object Name -match "Network Controller" — state Online
  • 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​

IssueCauseResolution
Add-EceFeature fails with action plan errorOS build mismatch or missing prerequisitesVerify OS build is 10.0.26100 with systeminfo; ensure all nodes are Arc-registered and cluster is healthy
Network Controller cluster group shows OfflineNC VMs failed to start or quorum lostCheck NC VM status: Get-ClusterGroup | Where-Object Name -match "Network Controller"; restart the group: Start-ClusterGroup <NCGroupName>
DNS resolution fails for NC FQDNDNS record not created or propagatedCreate the DNS record manually: Add-DnsServerResourceRecordA -Name "<SDNPrefix>-NC" -ZoneName "<domain>" -IPv4Address "<NC-IP>"
SDN feature not visible in Azure portalArc resource bridge not syncedWait 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.

PreviousUpNext
Phase 05: Cluster DeploymentPhase 06 IndexTask 02: Cluster Quorum

Document maintained by Azure Local Cloud Team. Part of the Azure Local Implementation Guide.


Version Control​

VersionDateAuthorChanges
1.0.02025-03-25Azure Local CloudInitial release