Deploy an SDN infrastructure using SDN Express

Article
11/19/2024

Applies to: Azure Stack HCI, versions 22H2 and 21H2; Windows Server 2022, Windows Server 2019, Windows Server 2016

Important

Azure Stack HCI is now part of Azure Local. Product documentation renaming is in progress. However, older versions of Azure Stack HCI, for example 22H2 will continue to reference Azure Stack HCI and won't reflect the name change. Learn more.

In this topic, you deploy an end-to-end Software Defined Network (SDN) infrastructure using SDN Express PowerShell scripts. The infrastructure includes a highly available (HA) Network Controller (NC), and optionally, a highly available Software Load Balancer (SLB), and a highly available Gateway (GW). The scripts support a phased deployment, where you can deploy just the Network Controller component to achieve a core set of functionality with minimal network requirements.

You can also deploy an SDN infrastructure using Windows Admin Center or using System Center Virtual Machine Manager (VMM). For more information, see Create a cluster - Step 5: SDN and Manage SDN resources in the VMM fabric.

Important

You can't use Microsoft System Center Virtual Machine Manager 2019 to manage clusters running Azure Stack HCI, version 21H2 or Windows Server 2022.

Before you begin

Before you begin an SDN deployment, plan out and configure your physical and host network infrastructure. See the following articles:

You don't have to deploy all SDN components. See the Phased deployment section of Plan a Software Defined Network infrastructure to determine which infrastructure components you need, and then run the scripts accordingly.

Make sure all host servers have the Azure Stack HCI operating system installed. See Deploy the Azure Stack HCI operating system on how to do this.

Requirements

The following requirements must be met for a successful SDN deployment:

All host servers must have Hyper-V enabled.
All host servers must be joined to Active Directory.
A virtual switch must be created.
The physical network must be configured for the subnets and VLANs defined in the configuration file.
The SDN Express script needs to be run from a Windows Server 2016 or later computer.
The VHDX file specified in the configuration file must be reachable from the computer where the SDN Express script is run.

Download the VHDX file

SDN uses a VHDX file containing either the Azure Stack HCI or Windows Server operating system (OS) as a source for creating the SDN virtual machines (VMs).

Note

The version of the OS in your VHDX must match the version used by the Azure Local Hyper-V machines. This VHDX file is used by all SDN infrastructure components.

To download an English-language version of the VHDX file, see Download the operating system from the Azure portal. Make sure to select English VHDX from the Choose language dropdown list.

Currently, a non-English VHDX file isn't available for download. If you require a non-English version, download the corresponding ISO file and convert it to VHDX using the Convert-WindowsImage cmdlet. You must run this script from a Windows client computer. You'll probably need to run this script as Administrator and modify the execution policy for scripts using the Set-ExecutionPolicy command.

The following syntax shows an example of using Convert-WindowsImage:

Install-Module -Name Convert-WindowsImage
Import-Module Convert-WindowsImage

$wimpath = "E:\sources\install.wim"
$vhdpath = "D:\temp\AzureStackHCI.vhdx"
$edition=1
Convert-WindowsImage -SourcePath $wimpath -Edition $edition -VHDPath $vhdpath -SizeBytes 500GB -DiskLayout UEFI

Note

The SDN Express script files are no longer available on GitHub.

Install the SDN Express PowerShell module

Run the following command to install the latest version of the SDN Express PowerShell module on the machine on which you want to run the SDN installation:

Install-Module -Name SDNExpress

The files automatically install in the default PowerShell module directory: **C:\Program Files\WindowsPowerShell\Modules\SdnExpress**.

Edit the configuration file

The PowerShell MultiNodeSampleConfig.psd1 configuration data file (located at the above mentioned install path) contains all the parameters and settings that are needed for the SDN Express script as input for the various parameters and configuration settings. This file has specific information about what needs to be filled out based on whether you are deploying only the network controller component, or the software load balancer and gateway components as well. For detailed information, see Plan a Software Defined Network infrastructure.

Navigate to the *C:\Program Files\WindowsPowerShell\Modules\SdnExpress* folder and open the MultiNodeSampleConfig.psd1 file in a text editor. Change specific parameter values to fit your infrastructure and deployment, as described in the next section.

General settings and parameters

These settings and parameters are used by SDN in general for all deployments. For specific recommendations, see SDN infrastructure VM role requirements.

VHDPath - VHD file path used by all SDN infrastructure VMs (NC, SLB, GW)
VHDFile - VHDX file name used by all SDN infrastructure VMs
VMLocation - file path to SDN infrastructure VMs. Note that Universal Naming Convention (UNC) paths aren't supported. For cluster storage-based paths, use a format like C:\ClusterStorage\...
JoinDomain - domain to which SDN infrastructure VMs are joined to
SDNMacPoolStart - beginning MAC pool address for client workload VMs
SDNMacPoolEnd - end MAC pool address for client workload VMs
ManagementSubnet - management network subnet used by NC to manage Hyper-V hosts, SLB, and GW components
ManagementGateway - Gateway address for the management network
ManagementDNS - DNS server for the management network
ManagementVLANID - VLAN ID for the management network
DomainJoinUsername - administrator username. Note that the username should be in the following format: domainname\username. For example, if the domain is contoso.com, enter the username as contoso\<username>. Don't use formats like contoso.com\<username> or username@contoso.com
LocalAdminDomainUser - local administrator username. Note that the username should be in the following format: domainname\username. For example, if the domain is contoso.com, enter the username as contoso\<username>. Don't use formats like contoso.com\<username> or username@contoso.com
RestName - DNS name used by management clients (such as Windows Admin Center) to communicate with NC
RestIpAddress - Static IP address for your REST API, which is allocated from your management network. It can be used for DNS resolution or REST IP-based deployments
HyperVHosts - host servers to be managed by Network Controller
NCUsername - Network Controller account username
ProductKey - product key for SDN infrastructure VMs
SwitchName - only required if more than one virtual switch exists on the Hyper-V hosts
VMMemory - memory (in GB) assigned to infrastructure VMs. Default is 4 GB
VMProcessorCount - number of processors assigned to infrastructure VMs. Default is 8
Locale - if not specified, locale of deployment computer is used
TimeZone - if not specified, local time zone of deployment computer is used

Passwords can be optionally included if stored encrypted as text-encoded secure strings. Passwords are only used if SDN Express scripts are run on the same computer where passwords were encrypted, otherwise it prompts for these passwords:

DomainJoinSecurePassword - for domain account
LocalAdminSecurePassword - for local administrator account
NCSecurePassword - for Network Controller account

Network Controller VM section

A minimum of three Network Controller VMs are recommended for SDN.

The NCs = @() section is used for the Network Controller VMs. Make sure that the MAC address of each NC VM is outside the SDNMACPool range listed in the general settings.

ComputerName - name of NC VM
HostName - host name of server where the NC VM is located
ManagementIP - management network IP address for the NC VM
MACAddress - MAC address for the NC VM

Software Load Balancer VM section

A minimum of two Software Load Balancer VMs are recommended for SDN.

The Muxes = @() section is used for the SLB VMs. Make sure that the MACAddress and PAMACAddress parameters of each SLB VM are outside the SDNMACPool range listed in the general settings. Ensure that you get the PAIPAddress parameter from outside the PA Pool specified in the configuration file, but part of the PASubnet specified in the configuration file.

Leave this section empty (Muxes = @()) if not deploying the SLB component:

ComputerName - name of SLB VM
HostName - host name of server where the SLB VM is located
ManagementIP - management network IP address for the SLB VM
MACAddress - MAC address for the SLB VM
PAIPAddress - Provider network IP address (PA) for the SLB VM
PAMACAddress - Provider network IP address (PA) for the SLB VM

Gateway VM section

A minimum of two Gateway VMs (one active and one redundant) are recommended for SDN.

The Gateways = @() section is used for the Gateway VMs. Make sure that the MACAddress parameter of each Gateway VM is outside the SDNMACPool range listed in the General settings. The FrontEndMac and BackendMac must be from within the SDNMACPool range. Ensure that you get the FrontEndMac and the BackendMac parameters from the end of the SDNMACPool range.

Leave this section empty (Gateways = @()) if not deploying the Gateway component:

ComputerName - name of Gateway VM
HostName - host name of server where the Gateway VM is located
ManagementIP - management network IP address for the Gateway VM
MACAddress - MAC address for the Gateway VM
FrontEndMac - Provider network front end MAC address for the Gateway VM
BackEndMac - Provider network back end MAC address for the Gateway VM

Additional settings for SLB and Gateway

The following additional parameters are used by SLB and Gateway VMs. Leave these values empty if you are not deploying SLB or Gateway VMs:

SDNASN - Autonomous System Number (ASN) used by SDN to peer with network switches
RouterASN - Gateway router ASN
RouterIPAddress - Gateway router IP address
PrivateVIPSubnet - virtual IP address (VIP) for the private subnet
PublicVIPSubnet - virtual IP address for the public subnet

The following additional parameters are only used by Gateway VMs. Leave these values blank if you are not deploying Gateway VMs:

PoolName - pool name used by all Gateway VMs
GRESubnet - VIP subnet for GRE (if using GRE connections)
Capacity - capacity in Kbps for each Gateway VM in the pool
RedundantCount - number of gateways in redundant mode. The default value is 1. Redundant gateways don't have any active connections. Once an active gateway goes down, the connections from that gateway move to the redundant gateway and the redundant gateway becomes active.

Note

If you fill in a value for RedundantCount, ensure that the total number of gateway VMs is at least one more than the RedundantCount. By default, the RedundantCount is 1, so you must have at least 2 gateway VMs to ensure that there is at least 1 active gateway to host gateway connections.

Settings for tenant overlay networks

The following parameters are used if you are deploying and managing overlay virtualized networks for tenants. If you are using Network Controller to manage traditional VLAN networks instead, these values can be left blank.

PASubnet - subnet for the Provider Address (PA) network
PAVLANID - VLAN ID for the PA network
PAGateway - IP address for the PA network Gateway
PAPoolStart - beginning IP address for the PA network pool
PAPoolEnd - end IP address for the PA network pool

Here's how Hyper-V Network Virtualization (HNV) Provider logical network allocates IP addresses. Use this to plan your address space for the HNV Provider network.

Allocates two IP addresses to each physical server
Allocates one IP address to each SLB MUX VM
Allocates one IP address to each gateway VM

Run the deployment script

The SDN Express script deploys your specified SDN infrastructure. When the script is complete, your SDN infrastructure is ready to be used for VM workload deployments.

Review the README.md file for late-breaking information on how to run the deployment script.
Run the following command from a user account with administrative credentials for the cluster host servers:
```
SDNExpress\scripts\SDNExpress.ps1 -ConfigurationDataFile MultiNodeSampleConfig.psd1 -Verbose
```
After the NC VMs are created, configure dynamic DNS updates for the Network Controller cluster name on the DNS server. For more information, see Dynamic DNS updates.

Configuration sample files

The following configuration sample files for deploying SDN are available on the Microsoft SDN GitHub repository:

Traditional VLAN networks.psd1 - Deploy Network Controller for managing network policies like microsegmentation and Quality of Service on traditional VLAN Networks.
Virtualized networks.psd1 - Deploy Network Controller for managing virtual networks and network policies on virtual networks.
Software Load Balancer.psd1 - Deploy Network Controller and Software Load Balancer for load balancing on virtual networks.
SDN Gateways.psd1 - Deploy Network Controller, Software Load Balancer and Gateway for connectivity to external networks.

Redeploy SDN Network Controller

If the Network Controller deployment fails or you want to deploy it again, do the following:

Delete all Network Controller VMs and their VHDs from all machines.

Remove the following registry keys from all machines by running this command:

 Remove-ItemProperty -path 'HKLM:\SYSTEM\CurrentControlSet\Services\NcHostAgent\Parameters\' -Name Connections
 Remove-ItemProperty -path 'HKLM:\SYSTEM\CurrentControlSet\Services\NcHostAgent\Parameters\' -Name NetworkControllerNodeNames

After removing the registry key, remove the cluster from the Windows Admin Center management, and then add it back.

Note

If you don't do this step, you may not see the SDN deployment wizard in Windows Admin Center.
(Additional step only if you plan to uninstall Network Controller and not deploy it again) Run the following cmdlet on all the machines in your Azure Local instance, and then skip the last step.
```
Disable-VMSwitchExtension -VMSwitchName "<Compute vmswitch name>" -Name "Microsoft Azure VFP Switch Extension"
```
Run the deployment wizard again.

Share via