Create a site-to-site connection to Azure Virtual WAN using PowerShell

This article shows you how to use Virtual WAN to connect to your resources in Azure over an IPsec/IKE (IKEv1 and IKEv2) VPN connection via PowerShell. This type of connection requires a VPN device located on-premises that has an externally facing public IP address assigned to it. For more information about Virtual WAN, see the Virtual WAN overview.

Screenshot shows a networking diagram for Virtual WAN.


  • Verify that you have an Azure subscription. If you don't already have an Azure subscription, you can activate your MSDN subscriber benefits or sign up for a free account.

  • Decide the IP address range that you want to use for your virtual hub private address space. This information is used when configuring your virtual hub. A virtual hub is a virtual network that is created and used by Virtual WAN. It's the core of your Virtual WAN network in a region. The address space range must conform to certain rules.

    • The address range that you specify for the hub can't overlap with any of the existing virtual networks that you connect to.
    • The address range can't overlap with the on-premises address ranges that you connect to.
    • If you're unfamiliar with the IP address ranges located in your on-premises network configuration, coordinate with someone who can provide those details for you.

Azure PowerShell

This article uses PowerShell cmdlets. To run the cmdlets, you can use Azure Cloud Shell. Cloud Shell is a free interactive shell that you can use to run the steps in this article. It has common Azure tools preinstalled and configured to use with your account.

To open Cloud Shell, just select Try it from the upper-right corner of a code block. You can also open Cloud Shell on a separate browser tab by going to Select Copy to copy the blocks of code, paste them into Cloud Shell, and select the Enter key to run them.

You can also install and run the Azure PowerShell cmdlets locally on your computer. PowerShell cmdlets are updated frequently. If you have not installed the latest version, the values specified in the instructions may fail. To find the versions of Azure PowerShell installed on your computer, use the Get-Module -ListAvailable Az cmdlet. To install or update, see Install the Azure PowerShell module.

Sign in

If you're running PowerShell locally, open the PowerShell console with elevated privileges and connect to your Azure account. The Connect-AzAccount cmdlet prompts you for credentials. After you authenticate, it downloads your account settings so that they're available to Azure PowerShell.

If you're using Azure Cloud Shell instead of running PowerShell locally, you'll notice that you don't need to run Connect-AzAccount. Azure Cloud Shell connects to your Azure account automatically after you select Try It.

  1. If you're running PowerShell locally, sign in.

  2. If you have more than one subscription, get a list of your Azure subscriptions.

  3. Specify the subscription that you want to use.

    Select-AzSubscription -SubscriptionName "Name of subscription"

Create a virtual WAN

Before you can create a virtual wan, you have to create a resource group to host the virtual wan or use an existing resource group. Use one of the following examples.

New resource group - This example creates a new resource group named testRG in the West US location.

  1. Create a resource group.

    New-AzResourceGroup -Location "West US" -Name "testRG" 
  2. Create the virtual wan.

    $virtualWan = New-AzVirtualWan -ResourceGroupName testRG -Name myVirtualWAN -Location "West US"

Existing resource group - Use the following steps if you want to create the virtual wan in an already existing resource group.

  1. Set the variables for the existing resource group.

    $resourceGroup = Get-AzResourceGroup -ResourceGroupName "testRG" 
  2. Create the virtual wan.

    $virtualWan = New-AzVirtualWan -ResourceGroupName testRG -Name myVirtualWAN -Location "West US"

Create the hub and configure hub settings

A hub is a virtual network that can contain gateways for site-to-site, ExpressRoute, or point-to-site functionality. Create a virtual hub with New-AzVirtualHub. This example creates a default virtual hub named westushub with the specified address prefix and a location for the hub.

$virtualHub = New-AzVirtualHub -VirtualWan $virtualWan -ResourceGroupName "testRG" -Name "westushub" -AddressPrefix "" -Location "westus"

Create a site-to-site VPN gateway

In this section, you create a site-to-site VPN gateway that will be in the same location as the referenced virtual hub. When you create the VPN gateway, you specify the scale units that you want. It takes about 30 minutes for the gateway to create.

  1. Create a VPN gateway.

    New-AzVpnGateway -ResourceGroupName "testRG" -Name "testvpngw" -VirtualHubId $virtualHub.Id -VpnGatewayScaleUnit 2
  2. Once your VPN gateway is created, you can view it using the following example.

    Get-AzVpnGateway -ResourceGroupName "testRG" -Name "testvpngw"

Create a site and connections

In this section, you create sites that correspond to your physical locations and the connections. These sites contain your on-premises VPN device endpoints, you can create up to 1000 sites per virtual hub in a virtual WAN. If you have multiple hubs, you can create 1000 per each of those hubs.

  1. Set the variable for the VPN gateway and for the IP address space that is located on your on-premises site. Traffic destined for this address space is routed to your local site. This is required when BGP isn't enabled for the site.

    $vpnGateway = Get-AzVpnGateway -ResourceGroupName "testRG" -Name "testvpngw"
    $vpnSiteAddressSpaces = New-Object string[] 2
    $vpnSiteAddressSpaces[0] = ""
    $vpnSiteAddressSpaces[1] = ""
  2. Create links to add information about the physical links at the branch including metadata about the link speed, link provider name, and the public IP address of the on-premises device.

    $vpnSiteLink1 = New-AzVpnSiteLink -Name "testVpnSiteLink1" -IpAddress "" -LinkProviderName "SomeTelecomProvider" -LinkSpeedInMbps "10"
    $vpnSiteLink2 = New-AzVpnSiteLink -Name "testVpnSiteLink2" -IpAddress "" -LinkProviderName "SomeTelecomProvider2" -LinkSpeedInMbps "100"
  3. Create the VPN site, referencing the variables of the VPN site links you just created.

    $vpnSite = New-AzVpnSite -ResourceGroupName "testRG" -Name "testVpnSite" -Location "West US" -VirtualWan $virtualWan -AddressSpace $vpnSiteAddressSpaces -DeviceModel "SomeDevice" -DeviceVendor "SomeDeviceVendor" -VpnSiteLink @($vpnSiteLink1, $vpnSiteLink2)
  4. Create the site link connection. The connection is composed of 2 active-active tunnels from a branch/site to the scalable gateway.

    $vpnSiteLinkConnection1 = New-AzVpnSiteLinkConnection -Name "testLinkConnection1" -VpnSiteLink $vpnSite.VpnSiteLinks[0] -ConnectionBandwidth 100
    $vpnSiteLinkConnection2 = New-AzVpnSiteLinkConnection -Name "testLinkConnection2" -VpnSiteLink $vpnSite.VpnSiteLinks[1] -ConnectionBandwidth 10

Connect the VPN site to a hub

Connect your VPN site to the hub site-to-site VPN gateway.

New-AzVpnConnection -ResourceGroupName $vpnGateway.ResourceGroupName -ParentResourceName $vpnGateway.Name -Name "testConnection" -VpnSite $vpnSite -VpnSiteLinkConnection @($vpnSiteLinkConnection1, $vpnSiteLinkConnection2)

Clean up resources

When you no longer need the resources that you created, delete them. Some of the Virtual WAN resources must be deleted in a certain order due to dependencies. Deleting can take about 30 minutes to complete.

  1. Delete all gateway entities following the below order for the VPN gateway.

  2. Declare the variables.

    $resourceGroup = Get-AzResourceGroup -ResourceGroupName "testRG" 
    $virtualWan = Get-AzVirtualWan -ResourceGroupName "testRG" -Name "myVirtualWAN"
    $virtualHub = Get-AzVirtualHub -ResourceGroupName "testRG" -Name "westushub"
    $vpnGateway = Get-AzVpnGateway -ResourceGroupName "testRG" -Name "testvpngw"
  3. Delete the VPN gateway connection to the VPN sites.

    Remove-AzVpnConnection -ResourceGroupName $vpnGateway.ResourceGroupName -ParentResourceName $vpnGateway.Name -Name "testConnection"
  4. Delete the VPN gateway. Deleting a VPN gateway will also remove all VPN ExpressRoute connections associated with it.

    Remove-AzVpnGateway -ResourceGroupName "testRG" -Name "testvpngw"
  5. You can delete the entire resource group in order to delete all the remaining resources it contains, including the hubs, sites, and the virtual WAN.

    Remove-AzResourceGroup -Name "testRG"
  6. Or, you can choose to delete each of the resources in the Resource Group.

    Delete the VPN site.

    Remove-AzVpnSite -ResourceGroupName "testRG" -Name "testVpnSite"

    Delete the virtual hub.

    Remove-AzVirtualHub -ResourceGroupName "testRG" -Name "westushub"

    Delete the virtual WAN.

    Remove-AzVirtualWan -Name "MyVirtualWan" -ResourceGroupName "testRG"

Next steps

Next, to learn more about Virtual WAN, see the Virtual WAN FAQ.