Add a virtual gateway to a tenant virtual network

Article
03/28/2023

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

Learn how to use Windows PowerShell cmdlets and scripts to provide site-to-site connectivity for your tenant's virtual networks. In this topic, you add tenant virtual gateways to instances of RAS gateway that are members of gateways pools, using Network Controller. RAS gateway supports up to one hundred tenants, depending on the bandwidth used by each tenant. Network Controller automatically determines the best RAS Gateway to use when you deploy a new virtual gateway for your tenants.

Each virtual gateway corresponds to a particular tenant and consists of one or more network connections (site-to-site VPN tunnels) and, optionally, Border Gateway Protocol (BGP) connections. When you provide site-to-site connectivity, your customers can connect their tenant virtual network to an external network, such as a tenant enterprise network, a service provider network, or the Internet.

When you deploy a Tenant Virtual Gateway, you have the following configuration options:

Network connection options	BGP configuration options
IPSec site-to-site virtual private network (VPN) Generic Routing Encapsulation (GRE) Layer 3 forwarding	BGP router configuration BGP peer configuration BGP routing policies configuration

The Windows PowerShell example scripts and commands in this topic demonstrate how to deploy a tenant virtual gateway on a RAS Gateway with each of these options.

Important

Before you run any of the example Windows PowerShell commands and scripts provided, you must change all variable values so that the values are appropriate for your deployment.

Verify that the gateway pool object exists in network controller.

$uri = "https://ncrest.contoso.com"

# Retrieve the Gateway Pool configuration
$gwPool = Get-NetworkControllerGatewayPool -ConnectionUri $uri

# Display in JSON format
$gwPool | ConvertTo-Json -Depth 2

Verify that the subnet used for routing packets out of the tenant's virtual network exists in Network Controller. You also retrieve the virtual subnet used for routing between the tenant gateway and virtual network.

$uri = "https://ncrest.contoso.com"

# Retrieve the Tenant Virtual Network configuration
$Vnet = Get-NetworkControllerVirtualNetwork -ConnectionUri $uri  -ResourceId "Contoso_Vnet1"

# Display in JSON format
$Vnet | ConvertTo-Json -Depth 4

# Retrieve the Tenant Virtual Subnet configuration
$RoutingSubnet = Get-NetworkControllerVirtualSubnet -ConnectionUri $uri  -ResourceId "Contoso_WebTier" -VirtualNetworkID $vnet.ResourceId

# Display in JSON format
$RoutingSubnet | ConvertTo-Json -Depth 4

Create a new object for the tenant virtual gateway and then update the gateway pool reference. You also specify the virtual subnet used for routing between the gateway and virtual network. After specifying the virtual subnet you update the rest of the virtual gateway object properties and then add the new virtual gateway for the tenant.

# Create a new object for Tenant Virtual Gateway
$VirtualGWProperties = New-Object Microsoft.Windows.NetworkController.VirtualGatewayProperties

# Update Gateway Pool reference
$VirtualGWProperties.GatewayPools = @()
$VirtualGWProperties.GatewayPools += $gwPool

# Specify the Virtual Subnet that is to be used for routing between the gateway and Virtual Network
$VirtualGWProperties.GatewaySubnets = @()
$VirtualGWProperties.GatewaySubnets += $RoutingSubnet

# Update the rest of the Virtual Gateway object properties
$VirtualGWProperties.RoutingType = "Dynamic"
$VirtualGWProperties.NetworkConnections = @()
$VirtualGWProperties.BgpRouters = @()

# Add the new Virtual Gateway for tenant
$virtualGW = New-NetworkControllerVirtualGateway -ConnectionUri $uri  -ResourceId "Contoso_VirtualGW" -Properties $VirtualGWProperties -Force

Create a site-to-site VPN connection with IPsec, GRE, or Layer 3 (L3) forwarding.

Tip

Optionally, you can combine all the previous steps and configure a tenant virtual gateway with all three connection options. For more details, see Configure a gateway with all three connection types (IPsec, GRE, L3) and BGP.

Note

PerfectForwardSecrecy must match for the local and remote sites.

IPsec VPN site-to-site network connection

# Create a new object for Tenant Network Connection
$nwConnectionProperties = New-Object Microsoft.Windows.NetworkController.NetworkConnectionProperties

# Update the common object properties
$nwConnectionProperties.ConnectionType = "IPSec"
$nwConnectionProperties.OutboundKiloBitsPerSecond = 10000
$nwConnectionProperties.InboundKiloBitsPerSecond = 10000

# Update specific properties depending on the Connection Type
$nwConnectionProperties.IpSecConfiguration = New-Object Microsoft.Windows.NetworkController.IpSecConfiguration
$nwConnectionProperties.IpSecConfiguration.AuthenticationMethod = "PSK"
$nwConnectionProperties.IpSecConfiguration.SharedSecret = "P@ssw0rd"

$nwConnectionProperties.IpSecConfiguration.QuickMode = New-Object Microsoft.Windows.NetworkController.QuickMode
$nwConnectionProperties.IpSecConfiguration.QuickMode.PerfectForwardSecrecy = "PFS2048"
$nwConnectionProperties.IpSecConfiguration.QuickMode.AuthenticationTransformationConstant = "SHA256128"
$nwConnectionProperties.IpSecConfiguration.QuickMode.CipherTransformationConstant = "DES3"
$nwConnectionProperties.IpSecConfiguration.QuickMode.SALifeTimeSeconds = 1233
$nwConnectionProperties.IpSecConfiguration.QuickMode.IdleDisconnectSeconds = 500
$nwConnectionProperties.IpSecConfiguration.QuickMode.SALifeTimeKiloBytes = 1048576

$nwConnectionProperties.IpSecConfiguration.MainMode = New-Object Microsoft.Windows.NetworkController.MainMode
$nwConnectionProperties.IpSecConfiguration.MainMode.DiffieHellmanGroup = "Group2"
$nwConnectionProperties.IpSecConfiguration.MainMode.IntegrityAlgorithm = "SHA256"
$nwConnectionProperties.IpSecConfiguration.MainMode.EncryptionAlgorithm = "AES256"
$nwConnectionProperties.IpSecConfiguration.MainMode.SALifeTimeSeconds = 1234
$nwConnectionProperties.IpSecConfiguration.MainMode.SALifeTimeKiloBytes = 1048576

# L3 specific configuration (leave blank for IPSec)
$nwConnectionProperties.IPAddresses = @()
$nwConnectionProperties.PeerIPAddresses = @()

# Update the IPv4 Routes that are reachable over the site-to-site VPN Tunnel
$nwConnectionProperties.Routes = @()
$ipv4Route = New-Object Microsoft.Windows.NetworkController.RouteInfo
$ipv4Route.DestinationPrefix = "14.1.10.1/32"
$ipv4Route.metric = 10
$nwConnectionProperties.Routes += $ipv4Route

# Tunnel Destination (Remote Endpoint) Address
$nwConnectionProperties.DestinationIPAddress = "10.127.134.121"

# Add the new Network Connection for the tenant
New-NetworkControllerVirtualGatewayNetworkConnection -ConnectionUri $uri -VirtualGatewayId $virtualGW.ResourceId -ResourceId "Contoso_IPSecGW" -Properties $nwConnectionProperties -Force

GRE VPN site-to-site network connection

# Create a new object for the Tenant Network Connection
$nwConnectionProperties = New-Object Microsoft.Windows.NetworkController.NetworkConnectionProperties

# Update the common object properties
$nwConnectionProperties.ConnectionType = "GRE"
$nwConnectionProperties.OutboundKiloBitsPerSecond = 10000
$nwConnectionProperties.InboundKiloBitsPerSecond = 10000

# Update specific properties depending on the Connection Type
$nwConnectionProperties.GreConfiguration = New-Object Microsoft.Windows.NetworkController.GreConfiguration
$nwConnectionProperties.GreConfiguration.GreKey = 1234

# Update the IPv4 Routes that are reachable over the site-to-site VPN Tunnel
$nwConnectionProperties.Routes = @()
$ipv4Route = New-Object Microsoft.Windows.NetworkController.RouteInfo
$ipv4Route.DestinationPrefix = "14.2.20.1/32"
$ipv4Route.metric = 10
$nwConnectionProperties.Routes += $ipv4Route

# Tunnel Destination (Remote Endpoint) Address
$nwConnectionProperties.DestinationIPAddress = "10.127.134.122"

# L3 specific configuration (leave blank for GRE)
$nwConnectionProperties.L3Configuration = New-Object Microsoft.Windows.NetworkController.L3Configuration
$nwConnectionProperties.IPAddresses = @()
$nwConnectionProperties.PeerIPAddresses = @()

# Add the new Network Connection for the tenant
New-NetworkControllerVirtualGatewayNetworkConnection -ConnectionUri $uri -VirtualGatewayId $virtualGW.ResourceId -ResourceId "Contoso_GreGW" -Properties $nwConnectionProperties -Force

L3 forwarding network connection

For a L3 forwarding network connection to work properly, you must configure a corresponding logical network.

Configure a logical network for the L3 forwarding Network Connection.

# Create a new object for the Logical Network to be used for L3 Forwarding
$lnProperties = New-Object Microsoft.Windows.NetworkController.LogicalNetworkProperties

$lnProperties.NetworkVirtualizationEnabled = $false
$lnProperties.Subnets = @()

# Create a new object for the Logical Subnet to be used for L3 Forwarding and update properties
$logicalsubnet = New-Object Microsoft.Windows.NetworkController.LogicalSubnet
$logicalsubnet.ResourceId = "Contoso_L3_Subnet"
$logicalsubnet.Properties = New-Object Microsoft.Windows.NetworkController.LogicalSubnetProperties
$logicalsubnet.Properties.VlanID = 1001
$logicalsubnet.Properties.AddressPrefix = "10.127.134.0/25"
$logicalsubnet.Properties.DefaultGateways = "10.127.134.1"

$lnProperties.Subnets += $logicalsubnet

# Add the new Logical Network to Network Controller
$vlanNetwork = New-NetworkControllerLogicalNetwork -ConnectionUri $uri -ResourceId "Contoso_L3_Network" -Properties $lnProperties -Force

Create a Network Connection JSON Object and add it to Network Controller.

# Create a new object for the Tenant Network Connection
$nwConnectionProperties = New-Object Microsoft.Windows.NetworkController.NetworkConnectionProperties

# Update the common object properties
$nwConnectionProperties.ConnectionType = "L3"
$nwConnectionProperties.OutboundKiloBitsPerSecond = 10000
$nwConnectionProperties.InboundKiloBitsPerSecond = 10000

# GRE specific configuration (leave blank for L3)
$nwConnectionProperties.GreConfiguration = New-Object Microsoft.Windows.NetworkController.GreConfiguration

# Update specific properties depending on the Connection Type
$nwConnectionProperties.L3Configuration = New-Object Microsoft.Windows.NetworkController.L3Configuration
$nwConnectionProperties.L3Configuration.VlanSubnet = $vlanNetwork.properties.Subnets[0]

$nwConnectionProperties.IPAddresses = @()
$localIPAddress = New-Object Microsoft.Windows.NetworkController.CidrIPAddress
$localIPAddress.IPAddress = "10.127.134.55"
$localIPAddress.PrefixLength = 25
$nwConnectionProperties.IPAddresses += $localIPAddress

$nwConnectionProperties.PeerIPAddresses = @("10.127.134.65")

# Update the IPv4 Routes that are reachable over the site-to-site VPN Tunnel
$nwConnectionProperties.Routes = @()
$ipv4Route = New-Object Microsoft.Windows.NetworkController.RouteInfo
$ipv4Route.DestinationPrefix = "14.2.20.1/32"
$ipv4Route.metric = 10
$nwConnectionProperties.Routes += $ipv4Route

# Add the new Network Connection for the tenant
New-NetworkControllerVirtualGatewayNetworkConnection -ConnectionUri $uri -VirtualGatewayId $virtualGW.ResourceId -ResourceId "Contoso_L3GW" -Properties $nwConnectionProperties -Force

Configure the gateway as a BGP router and add it to Network Controller.

Add a BGP router for the tenant.

# Create a new object for the Tenant BGP Router
$bgpRouterproperties = New-Object Microsoft.Windows.NetworkController.VGwBgpRouterProperties

# Update the BGP Router properties
$bgpRouterproperties.ExtAsNumber = "0.64512"

# Add the new BGP Router for the tenant
$bgpRouter = New-NetworkControllerVirtualGatewayBgpRouter -ConnectionUri $uri -VirtualGatewayId $virtualGW.ResourceId -ResourceId "Contoso_BgpRouter1" -Properties $bgpRouterProperties -Force

Add a BGP Peer for this tenant, corresponding to the site-to-site VPN Network Connection added above.

# Create a new object for Tenant BGP Peer
$bgpPeerProperties = New-Object Microsoft.Windows.NetworkController.VGwBgpPeerProperties

# Update the BGP Peer properties
$bgpPeerProperties.PeerIpAddress = "14.1.10.1"
$bgpPeerProperties.AsNumber = 64521
$bgpPeerProperties.ExtAsNumber = "0.64521"

# Add the new BGP Peer for tenant
New-NetworkControllerVirtualGatewayBgpPeer -ConnectionUri $uri -VirtualGatewayId $virtualGW.ResourceId -BgpRouterName $bgpRouter.ResourceId -ResourceId "Contoso_IPSec_Peer" -Properties $bgpPeerProperties -Force

(Optional step) Configure a gateway with all three connection types (IPsec, GRE, L3) and BGP

Optionally, you can combine all previous steps and configure a tenant virtual gateway with all three connection options:

Note

PerfectForwardSecrecy must match for the local and remote sites.

# Create a new Virtual Gateway Properties type object
$VirtualGWProperties = New-Object Microsoft.Windows.NetworkController.VirtualGatewayProperties

# Update GatewayPool reference
$VirtualGWProperties.GatewayPools = @()
$VirtualGWProperties.GatewayPools += $gwPool

# Specify the Virtual Subnet that is to be used for routing between GW and VNET
$VirtualGWProperties.GatewaySubnets = @()
$VirtualGWProperties.GatewaySubnets += $RoutingSubnet

# Update some basic properties
$VirtualGWProperties.RoutingType = "Dynamic"

# Update Network Connection object(s)
$VirtualGWProperties.NetworkConnections = @()

# IPSec Connection configuration
$ipSecConnection = New-Object Microsoft.Windows.NetworkController.NetworkConnection
$ipSecConnection.ResourceId = "Contoso_IPSecGW"
$ipSecConnection.Properties = New-Object Microsoft.Windows.NetworkController.NetworkConnectionProperties
$ipSecConnection.Properties.ConnectionType = "IPSec"
$ipSecConnection.Properties.OutboundKiloBitsPerSecond = 10000
$ipSecConnection.Properties.InboundKiloBitsPerSecond = 10000

$ipSecConnection.Properties.IpSecConfiguration = New-Object Microsoft.Windows.NetworkController.IpSecConfiguration

$ipSecConnection.Properties.IpSecConfiguration.AuthenticationMethod = "PSK"
$ipSecConnection.Properties.IpSecConfiguration.SharedSecret = "P@ssw0rd"

$ipSecConnection.Properties.IpSecConfiguration.QuickMode = New-Object Microsoft.Windows.NetworkController.QuickMode

$ipSecConnection.Properties.IpSecConfiguration.QuickMode.PerfectForwardSecrecy = "PFS2048"
$ipSecConnection.Properties.IpSecConfiguration.QuickMode.AuthenticationTransformationConstant = "SHA256128"
$ipSecConnection.Properties.IpSecConfiguration.QuickMode.CipherTransformationConstant = "DES3"
$ipSecConnection.Properties.IpSecConfiguration.QuickMode.SALifeTimeSeconds = 1233
$ipSecConnection.Properties.IpSecConfiguration.QuickMode.IdleDisconnectSeconds = 500
$ipSecConnection.Properties.IpSecConfiguration.QuickMode.SALifeTimeKiloBytes = 1048576

$ipSecConnection.Properties.IpSecConfiguration.MainMode = New-Object Microsoft.Windows.NetworkController.MainMode

$ipSecConnection.Properties.IpSecConfiguration.MainMode.DiffieHellmanGroup = "Group2"
$ipSecConnection.Properties.IpSecConfiguration.MainMode.IntegrityAlgorithm = "SHA256"
$ipSecConnection.Properties.IpSecConfiguration.MainMode.EncryptionAlgorithm = "AES256"
$ipSecConnection.Properties.IpSecConfiguration.MainMode.SALifeTimeSeconds = 1234
$ipSecConnection.Properties.IpSecConfiguration.MainMode.SALifeTimeKiloBytes = 1048576

$ipSecConnection.Properties.IPAddresses = @()
$ipSecConnection.Properties.PeerIPAddresses = @()

$ipSecConnection.Properties.Routes = @()

$ipv4Route = New-Object Microsoft.Windows.NetworkController.RouteInfo
$ipv4Route.DestinationPrefix = "14.1.10.1/32"
$ipv4Route.metric = 10
$ipSecConnection.Properties.Routes += $ipv4Route

$ipSecConnection.Properties.DestinationIPAddress = "10.127.134.121"

# GRE Connection configuration
$greConnection = New-Object Microsoft.Windows.NetworkController.NetworkConnection
$greConnection.ResourceId = "Contoso_GreGW"

$greConnection.Properties = New-Object Microsoft.Windows.NetworkController.NetworkConnectionProperties
$greConnection.Properties.ConnectionType = "GRE"
$greConnection.Properties.OutboundKiloBitsPerSecond = 10000
$greConnection.Properties.InboundKiloBitsPerSecond = 10000

$greConnection.Properties.GreConfiguration = New-Object Microsoft.Windows.NetworkController.GreConfiguration
$greConnection.Properties.GreConfiguration.GreKey = 1234

$greConnection.Properties.IPAddresses = @()
$greConnection.Properties.PeerIPAddresses = @()

$greConnection.Properties.Routes = @()

$ipv4Route = New-Object Microsoft.Windows.NetworkController.RouteInfo
$ipv4Route.DestinationPrefix = "14.2.20.1/32"
$ipv4Route.metric = 10
$greConnection.Properties.Routes += $ipv4Route

$greConnection.Properties.DestinationIPAddress = "10.127.134.122"

$greConnection.Properties.L3Configuration = New-Object Microsoft.Windows.NetworkController.L3Configuration

# L3 Forwarding connection configuration
$l3Connection = New-Object Microsoft.Windows.NetworkController.NetworkConnection
$l3Connection.ResourceId = "Contoso_L3GW"

$l3Connection.Properties = New-Object Microsoft.Windows.NetworkController.NetworkConnectionProperties
$l3Connection.Properties.ConnectionType = "L3"
$l3Connection.Properties.OutboundKiloBitsPerSecond = 10000
$l3Connection.Properties.InboundKiloBitsPerSecond = 10000

$l3Connection.Properties.GreConfiguration = New-Object Microsoft.Windows.NetworkController.GreConfiguration
$l3Connection.Properties.L3Configuration = New-Object Microsoft.Windows.NetworkController.L3Configuration
$l3Connection.Properties.L3Configuration.VlanSubnet = $vlanNetwork.properties.Subnets[0]

$l3Connection.Properties.IPAddresses = @()
$localIPAddress = New-Object Microsoft.Windows.NetworkController.CidrIPAddress
$localIPAddress.IPAddress = "10.127.134.55"
$localIPAddress.PrefixLength = 25
$l3Connection.Properties.IPAddresses += $localIPAddress

$l3Connection.Properties.PeerIPAddresses = @("10.127.134.65")

$l3Connection.Properties.Routes = @()
$ipv4Route = New-Object Microsoft.Windows.NetworkController.RouteInfo
$ipv4Route.DestinationPrefix = "14.2.20.1/32"
$ipv4Route.metric = 10
$l3Connection.Properties.Routes += $ipv4Route

# Update BGP Router Object
$VirtualGWProperties.BgpRouters = @()

$bgpRouter = New-Object Microsoft.Windows.NetworkController.VGwBgpRouter
$bgpRouter.ResourceId = "Contoso_BgpRouter1"
$bgpRouter.Properties = New-Object Microsoft.Windows.NetworkController.VGwBgpRouterProperties

$bgpRouter.Properties.ExtAsNumber = "0.64512"
$bgpRouter.Properties.BgpPeers = @()

# Create BGP Peer Object(s)
# BGP Peer for IPSec Connection
$bgpPeer_IPSec = New-Object Microsoft.Windows.NetworkController.VGwBgpPeer
$bgpPeer_IPSec.ResourceId = "Contoso_IPSec_Peer"

$bgpPeer_IPSec.Properties = New-Object Microsoft.Windows.NetworkController.VGwBgpPeerProperties
$bgpPeer_IPSec.Properties.PeerIpAddress = "14.1.10.1"
$bgpPeer_IPSec.Properties.AsNumber = 64521
$bgpPeer_IPSec.Properties.ExtAsNumber = "0.64521"

$bgpRouter.Properties.BgpPeers += $bgpPeer_IPSec

# BGP Peer for GRE Connection
$bgpPeer_Gre = New-Object Microsoft.Windows.NetworkController.VGwBgpPeer
$bgpPeer_Gre.ResourceId = "Contoso_Gre_Peer"

$bgpPeer_Gre.Properties = New-Object Microsoft.Windows.NetworkController.VGwBgpPeerProperties
$bgpPeer_Gre.Properties.PeerIpAddress = "14.2.20.1"
$bgpPeer_Gre.Properties.AsNumber = 64522
$bgpPeer_Gre.Properties.ExtAsNumber = "0.64522"

$bgpRouter.Properties.BgpPeers += $bgpPeer_Gre

# BGP Peer for L3 Connection
$bgpPeer_L3 = New-Object Microsoft.Windows.NetworkController.VGwBgpPeer
$bgpPeer_L3.ResourceId = "Contoso_L3_Peer"

$bgpPeer_L3.Properties = New-Object Microsoft.Windows.NetworkController.VGwBgpPeerProperties
$bgpPeer_L3.Properties.PeerIpAddress = "14.3.30.1"
$bgpPeer_L3.Properties.AsNumber = 64523
$bgpPeer_L3.Properties.ExtAsNumber = "0.64523"

$bgpRouter.Properties.BgpPeers += $bgpPeer_L3

$VirtualGWProperties.BgpRouters += $bgpRouter

# Finally Add the new Virtual Gateway for tenant
New-NetworkControllerVirtualGateway -ConnectionUri $uri  -ResourceId "Contoso_VirtualGW" -Properties $VirtualGWProperties -Force

Modify a gateway for a virtual network

Retrieve the configuration for the component and store it in a variable

$nwConnection = Get-NetworkControllerVirtualGatewayNetworkConnection -ConnectionUri $uri -VirtualGatewayId "Contoso_VirtualGW" -ResourceId "Contoso_IPSecGW"

Navigate the variable structure to reach the required property and set it to the updates value

$nwConnection.properties.IpSecConfiguration.SharedSecret = "C0mplexP@ssW0rd"

Add the modified configuration to replace the older configuration on Network Controller

New-NetworkControllerVirtualGatewayNetworkConnection -ConnectionUri $uri -VirtualGatewayId "Contoso_VirtualGW" -ResourceId $nwConnection.ResourceId -Properties $nwConnection.Properties -Force

Remove a gateway from a virtual network

You can use the following Windows PowerShell commands to remove either individual gateway features or the entire gateway.

Remove a network connection

Remove-NetworkControllerVirtualGatewayNetworkConnection -ConnectionUri $uri -VirtualGatewayId "Contoso_VirtualGW" -ResourceId "Contoso_IPSecGW" -Force

Remove a BGP peer

Remove-NetworkControllerVirtualGatewayBgpPeer -ConnectionUri $uri -VirtualGatewayId "Contoso_VirtualGW" -BgpRouterName "Contoso_BgpRouter1" -ResourceId "Contoso_IPSec_Peer" -Force

Remove a BGP router

Remove-NetworkControllerVirtualGatewayBgpRouter -ConnectionUri $uri -VirtualGatewayId "Contoso_VirtualGW" -ResourceId "Contoso_BgpRouter1" -Force

Remove a gateway

Remove-NetworkControllerVirtualGateway -ConnectionUri $uri -ResourceId "Contoso_VirtualGW" -Force

Add a virtual gateway to a tenant virtual network

(Optional step) Configure a gateway with all three connection types (IPsec, GRE, L3) and BGP

Modify a gateway for a virtual network

Remove a gateway from a virtual network

Feedback

Additional resources