Create a virtual network peering - different deployment models and subscriptions

In this tutorial, you learn to create a virtual network peering between virtual networks created through different deployment models. The virtual networks exist in different subscriptions. Peering two virtual networks enables resources in different virtual networks to communicate with each other with the same bandwidth and latency as though the resources were in the same virtual network. Learn more about Virtual network peering.

The steps to create a virtual network peering are different, depending on whether the virtual networks are in the same, or different, subscriptions, and which Azure deployment model the virtual networks are created through. Learn how to create a virtual network peering in other scenarios by clicking the scenario from the following table:

Azure deployment model Azure subscription
Both Resource Manager Same
Both Resource Manager Different
One Resource Manager, one classic Same

A virtual network peering cannot be created between two virtual networks deployed through the classic deployment model. The ability to peer virtual networks created through different deployment models that exist in different subscriptions is currently in preview. To complete this tutorial, you must first register to use the capability. This tutorial uses virtual networks that exist in the same region. The ability to peer virtual networks in different regions is also in preview. To use that capability, you must also register for it. The two capabilities are independent. To complete this tutorial, you must only register for the capability to peer virtual networks created through different deployment models that exist in different subscriptions.

When creating a virtual network peering between virtual networks that exist in different subscriptions, the subscriptions must both be associated to the same Azure Active Directory tenant. If you don't already have an Azure Active Directory tenant, you can quickly create one.

The ability to connect virtual networks created through either deployment model, different deployment models, different regions, or subscriptions associated to the same or different Azure Active Directory tenants using an Azure VPN Gateway is in preview release, and does not require registration.

You can use the Azure portal, the Azure command-line interface (CLI), or Azure PowerShell to create a virtual network peering. Click any of the previous tool links to go directly to the steps for creating a virtual network peering using your tool of choice.

Create peering - Azure portal

This tutorial uses different accounts for each subscription. If you're using an account that has permissions to both subscriptions, you can use the same account for all steps, skip the steps for logging out of the portal, and skip the steps for assigning another user permissions to the virtual networks. Before completing any of the following steps, you must register for the preview. To register, complete the steps in the Register for the preview section of this article. The remaining steps fail if you do not register both subscriptions for the preview.

  1. Log in to the Azure portal as UserA. The account you log in with must have the necessary permissions to create a virtual network peering. See the Permissions section of this article for details.
  2. Click + New, click Networking, then click Virtual network.
  3. In the Create virtual network blade, enter, or select values for the following settings, then click Create:
    • Name: myVnetA
    • Address space: 10.0.0.0/16
    • Subnet name: default
    • Subnet address range: 10.0.0.0/24
    • Subscription: Select subscription A.
    • Resource group: Select Create new and enter myResourceGroupA
    • Location: East US
  4. In the Search resources box at the top of the portal, type myVnetA. Click myVnetA when it appears in the search results. A blade appears for the myVnetA virtual network.
  5. In the myVnetA blade that appears, click Access control (IAM) from the vertical list of options on the left side of the blade.
  6. In the myVnetA - Access control (IAM) blade that appears, click + Add.
  7. In the Add permissions blade that appears, select Network contributor in the Role box.
  8. In the Select box, select UserB, or type UserB's email address to search for it. The list of users shown is from the same Azure Active Directory tenant as the virtual network you're setting up the peering for. Click UserB when it appears in the list.
  9. Click Save.
  10. Log out of the portal as UserA, then log in as UserB.
  11. Click + New, type Virtual network in the Search the Marketplace box, then click Virtual network in the search results.
  12. In the Virtual Network blade that appears, select Classic in the Select a deployment model box, then click Create.
  13. In the Create virtual network (classic) box that appears, enter the following values:

    • Name: myVnetB
    • Address space: 10.1.0.0/16
    • Subnet name: default
    • Subnet address range: 10.1.0.0/24
    • Subscription: Select subscription B.
    • Resource group: Select Create new and enter myResourceGroupB
    • Location: East US
  14. In the Search resources box at the top of the portal, type myVnetB. Click myVnetB when it appears in the search results. A blade appears for the myVnetB virtual network.

  15. In the myVnetB blade that appears, click Properties from the vertical list of options on the left side of the blade. Copy the RESOURCE ID, which is used in a later step. The resource ID is similar to the following example: /subscriptions//resourceGroups/myResoureGroupB/providers/Microsoft.ClassicNetwork/virtualNetworks/myVnetB
  16. Complete steps 5-9 for myVnetB, entering UserA in step 8.
  17. Log out of the portal as UserB and log in as UserA.
  18. In the Search resources box at the top of the portal, type myVnetA. Click myVnetA when it appears in the search results. A blade appears for the myVnet virtual network.
  19. Click myVnetA.
  20. In the myVnetA blade that appears, click Peerings from the vertical list of options on the left side of the blade.
  21. In the myVnetA - Peerings blade that appeared, click + Add
  22. In the Add peering blade that appears, enter, or select the following options, then click OK:
    • Name: myVnetAToMyVnetB
    • Virtual network deployment model: Select Classic.
    • I know my resource ID: Check this box.
    • Resource ID: Enter the resource ID of myVnetB from step 15.
    • Allow virtual network access: Ensure that Enabled is selected. No other settings are used in this tutorial. To learn about all peering settings, read Manage virtual network peerings.
  23. After clicking OK in the previous step, the Add peering blade closes and you see the myVnetA - Peerings blade again. After a few seconds, the peering you created appears in the blade. Connected is listed in the PEERING STATUS column for the myVnetAToMyVnetB peering you created. The peering is now established. There is no need to peer the virtual network (classic) to the virtual network (Resource Manager).

    Any Azure resources you create in either virtual network are now able to communicate with each other through their IP addresses. If you're using default Azure name resolution for the virtual networks, the resources in the virtual networks are not able to resolve names across the virtual networks. If you want to resolve names across virtual networks in a peering, you must create your own DNS server. Learn how to set up Name resolution using your own DNS server.

  24. Optional: Though creating virtual machines is not covered in this tutorial, you can create a virtual machine in each virtual network and connect from one virtual machine to the other, to validate connectivity.

  25. Optional: To delete the resources that you create in this tutorial, complete the steps in the Delete resources section of this article.

Create peering - Azure CLI

This tutorial uses different accounts for each subscription. If you're using an account that has permissions to both subscriptions, you can use the same account for all steps, skip the steps for logging out of Azure, and remove the lines of script that create user role assignments. Replace UserA@azure.com and UserB@azure.com in all of the following scripts with the usernames you're using for UserA and UserB.

Before completing any of the following steps, you must register for the preview. To register, complete the steps in the Register for the preview section of this article. The remaining steps fail if you do not register both subscriptions for the preview.

  1. Install the Azure CLI 1.0 to create the virtual network (classic).
  2. Open a CLI session and log in to Azure as UserB using the azure login command.
  3. Run the CLI in Service Management mode by entering the azure config mode asm command.
  4. Enter the following command to create the virtual network (classic):

    azure network vnet create --vnet myVnetB --address-space 10.1.0.0 --cidr 16 --location "East US"
    
  5. The remaining steps must be completed using a bash shell with the Azure CLI 2.0.4 or later installed, or by using the Azure Cloud Shell. The Azure Cloud Shell is a free Bash shell that you can run directly within the Azure portal. It has the Azure CLI preinstalled and configured to use with your account. Click the Try it button in the scripts that follow, which opens a Cloud Shell that logs you in to your Azure account. For options on running bash CLI scripts on a Windows client, see Running the Azure CLI in Windows.
  6. Copy the following script to a text editor on your PC. Replace <SubscriptionB-Id> with your subscription ID. If you don't know your subscription Id, enter the az account show command. The value for id in the output is your subscription Id. Copy the modified script, paste it in to your CLI 2.0 session, and then press Enter.

    az role assignment create \
      --assignee UserA@azure.com \
      --role "Classic Network Contributor" \
      --scope /subscriptions/<SubscriptionB-Id>/resourceGroups/Default-Networking/providers/Microsoft.ClassicNetwork/virtualNetworks/myVnetB
    

    When you created the virtual network (classic) in step 4, Azure created the virtual network in the Default-Networking resource group.

  7. Log UserB out of Azure and log in as UserA in the CLI 2.0.
  8. Create a resource group and a virtual network (Resource Manager). Copy the following script, paste it in to your CLI session, and then press Enter.

    #!/bin/bash
    
    # Variables for common values used throughout the script.
    rgName="myResourceGroupA"
    location="eastus"
    
    # Create a resource group.
    az group create \
      --name $rgName \
      --location $location
    
    # Create virtual network A (Resource Manager).
    az network vnet create \
      --name myVnetA \
      --resource-group $rgName \
      --location $location \
      --address-prefix 10.0.0.0/16
    
    # Get the id for myVnetA.
    vNetAId=$(az network vnet show \
      --resource-group $rgName \
      --name myVnetA \
      --query id --out tsv)
    
    # Assign UserB permissions to myVnetA.
    az role assignment create \
      --assignee UserB@azure.com \
      --role "Network Contributor" \
      --scope $vNetAId
    
  9. Create a virtual network peering between the two virtual networks created through the different deployment models. Copy the following script to a text editor on your PC. Replace <SubscriptionB-id> with your subscription Id. If you don't know your subscription Id, enter the az account show command. The value for id in the output is your subscription Id. Azure created the virtual network (classic) you created in step 4 in a resource group named Default-Networking. Paste the modified script in your CLI session, and then press Enter.

    # Peer VNet1 to VNet2.
    az network vnet peering create \
      --name myVnetAToMyVnetB \
      --resource-group $rgName \
      --vnet-name myVnetA \
      --remote-vnet-id  /subscriptions/<SubscriptionB-id>/resourceGroups/Default-Networking/providers/Microsoft.ClassicNetwork/virtualNetworks/myVnetB \
      --allow-vnet-access
    
  10. After the script executes, review the peering for the virtual network (Resource Manager). Copy the following script, and then paste it in your CLI session:

    az network vnet peering list \
      --resource-group $rgName \
      --vnet-name myVnetA \
      --output table
    

    The output shows Connected in the PeeringState column.

    Any Azure resources you create in either virtual network are now able to communicate with each other through their IP addresses. If you're using default Azure name resolution for the virtual networks, the resources in the virtual networks are not able to resolve names across the virtual networks. If you want to resolve names across virtual networks in a peering, you must create your own DNS server. Learn how to set up Name resolution using your own DNS server.

  11. Optional: Though creating virtual machines is not covered in this tutorial, you can create a virtual machine in each virtual network and connect from one virtual machine to the other, to validate connectivity.

  12. Optional: To delete the resources that you create in this tutorial, complete the steps in Delete resources in this article.

Create peering - PowerShell

This tutorial uses different accounts for each subscription. If you're using an account that has permissions to both subscriptions, you can use the same account for all steps, skip the steps for logging out of Azure, and remove the lines of script that create user role assignments. Replace UserA@azure.com and UserB@azure.com in all of the following scripts with the usernames you're using for UserA and UserB.

Before completing any of the following steps, you must register for the preview. To register, complete the steps in the Register for the preview section of this article. The remaining steps fail if you do not register both subscriptions for the preview.

  1. Install the latest version of the PowerShell Azure and AzureRm modules. If you're new to Azure PowerShell, see Azure PowerShell overview.
  2. Start a PowerShell session.
  3. In PowerShell, log in to UserB's subscription as UserB by entering the Add-AzureAccount command.
  4. To create a virtual network (classic) with PowerShell, you must create a new, or modify an existing, network configuration file. Learn how to export, update, and import network configuration files. The file should include the following VirtualNetworkSite element for the virtual network used in this tutorial:

    <VirtualNetworkSite name="myVnetB" Location="East US">
      <AddressSpace>
        <AddressPrefix>10.1.0.0/16</AddressPrefix>
      </AddressSpace>
      <Subnets>
        <Subnet name="default">
          <AddressPrefix>10.1.0.0/24</AddressPrefix>
        </Subnet>
      </Subnets>
    </VirtualNetworkSite>
    

    Warning

    Importing a changed network configuration file can cause changes to existing virtual networks (classic) in your subscription. Ensure you only add the previous virtual network and that you don't change or remove any existing virtual networks from your subscription.

  5. Log in to UserB's subscription as UserB to use Resource Manager commands by entering the login-azurermaccount command.

  6. Assign UserA permissions to virtual network B. Copy the following script to a text editor on your PC and replace <SubscriptionB-id> with the ID of subscription B. If you don't know the subscription Id, enter the Get-AzureRmSubscription command to view it. The value for Id in the returned output is your subscription ID. Azure created the virtual network (classic) you created in step 4 in a resource group named Default-Networking. To execute the script, copy the modified script, paste it in to PowerShell, and then press Enter.

    New-AzureRmRoleAssignment `
      -SignInName UserA@azure.com `
      -RoleDefinitionName "Classic Network Contributor" `
      -Scope /subscriptions/<SubscriptionB-id>/resourceGroups/Default-Networking/providers/Microsoft.ClassicNetwork/virtualNetworks/myVnetB
    
  7. Log out of Azure as UserB and log in to UserA's subscription as UserA by entering the login-azurermaccount command. The account you log in with must have the necessary permissions to create a virtual network peering. See the Permissions section of this article for details.

  8. Create the virtual network (Resource Manager) by copying the following script, pasting it in to PowerShell, and then pressing Enter:

    # Variables for common values
      $rgName='MyResourceGroupA'
      $location='eastus'
    
    # Create a resource group.
    New-AzureRmResourceGroup `
      -Name $rgName `
      -Location $location
    
    # Create virtual network A.
    $vnetA = New-AzureRmVirtualNetwork `
      -ResourceGroupName $rgName `
      -Name 'myVnetA' `
      -AddressPrefix '10.0.0.0/16' `
      -Location $location
    
  9. Assign UserB permissions to myVnetA. Copy the following script to a text editor on your PC and replace <SubscriptionA-Id> with the ID of subscription A. If you don't know the subscription Id, enter the Get-AzureRmSubscription command to view it. The value for Id in the returned output is your subscription ID. Paste the modified version of the script in PowerShell, and then press Enter to execute it.

    New-AzureRmRoleAssignment `
      -SignInName UserB@azure.com `
      -RoleDefinitionName "Network Contributor" `
      -Scope /subscriptions/<SubscriptionA-Id>/resourceGroups/myResourceGroupA/providers/Microsoft.Network/VirtualNetworks/myVnetA
    
  10. Copy the following script to a text editor on your PC, and replace <SubscriptionB-id> with the ID of subscription B. To peer myVnetA to myVNetB, copy the modified script, paste it in to PowerShell, and then press Enter.

    Add-AzureRmVirtualNetworkPeering `
      -Name 'myVnetAToMyVnetB' `
      -VirtualNetwork $vnetA `
      -RemoteVirtualNetworkId /subscriptions/<SubscriptionB-id>/resourceGroups/Default-Networking/providers/Microsoft.ClassicNetwork/virtualNetworks/myVnetB
    
  11. View the peering state of myVnetA by copying the following script, pasting it into PowerShell, and pressing Enter.

    Get-AzureRmVirtualNetworkPeering `
      -ResourceGroupName $rgName `
      -VirtualNetworkName myVnetA `
      | Format-Table VirtualNetworkName, PeeringState
    

    The state is Connected. It changes to Connected once you set up the peering to myVnetA from myVnetB.

    Any Azure resources you create in either virtual network are now able to communicate with each other through their IP addresses. If you're using default Azure name resolution for the virtual networks, the resources in the virtual networks are not able to resolve names across the virtual networks. If you want to resolve names across virtual networks in a peering, you must create your own DNS server. Learn how to set up Name resolution using your own DNS server.

  12. Optional: Though creating virtual machines is not covered in this tutorial, you can create a virtual machine in each virtual network and connect from one virtual machine to the other, to validate connectivity.

  13. Optional: To delete the resources that you create in this tutorial, complete the steps in Delete resources in this article.

Permissions

The accounts you use to create a virtual network peering must have the necessary role or permissions. For example, if you were peering two virtual networks named myVnetA and myVnetB, your account must be assigned the following minimum role or permissions for each virtual network:

Virtual network Deployment model Role Permissions
myVnetA Resource Manager Network Contributor Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write
Classic Classic Network Contributor N/A
myVnetB Resource Manager Network Contributor Microsoft.Network/virtualNetworks/peer
Classic Classic Network Contributor Microsoft.ClassicNetwork/virtualNetworks/peer

Learn more about built-in roles and assigning specific permissions to custom roles (Resource Manager only).

Delete resources

When you've finished this tutorial, you might want to delete the resources you created in the tutorial, so you don't incur usage charges. Deleting a resource group also deletes all resources that are in the resource group.

Azure portal

  1. In the portal search box, enter myResourceGroupA. In the search results, click myResourceGroupA.
  2. On the myResourceGroupA blade, click the Delete icon.
  3. To confirm the deletion, in the TYPE THE RESOURCE GROUP NAME box, enter myResourceGroupA, and then click Delete.
  4. In the Search resources box at the top of the portal, type myVnetB. Click myVnetB when it appears in the search results. A blade appears for the myVnetB virtual network.
  5. In the myVnetB blade, click Delete.
  6. To confirm the deletion, click Yes in the Delete virtual network box.

Azure CLI

  1. Log in to Azure using the CLI 2.0 to delete the virtual network (Resource Manager) with the following command:

    az group delete --name myResourceGroupA --yes
    
  2. Log in to Azure using the Azure CLI 1.0 to delete the virtual network (classic) with the following commands:

    azure config mode asm 
    
    azure network vnet delete --vnet myVnetB --quiet
    

PowerShell

  1. At the PowerShell command prompt, enter the following command to delete the virtual network (Resource Manager):

    Remove-AzureRmResourceGroup -Name myResourceGroupA -Force
    
  2. To delete the virtual network (classic) with PowerShell, you must modify an existing network configuration file. Learn how to export, update, and import network configuration files. Remove the following VirtualNetworkSite element for the virtual network used in this tutorial:

    <VirtualNetworkSite name="myVnetB" Location="East US">
      <AddressSpace>
        <AddressPrefix>10.1.0.0/16</AddressPrefix>
      </AddressSpace>
      <Subnets>
        <Subnet name="default">
          <AddressPrefix>10.1.0.0/24</AddressPrefix>
        </Subnet>
      </Subnets>
    </VirtualNetworkSite>
    

    Warning

    Importing a changed network configuration file can cause changes to existing virtual networks (classic) in your subscription. Ensure you only remove the previous virtual network and that you don't change or remove any other existing virtual networks from your subscription.

Register for the preview

The ability to peer virtual networks created through different Azure deployment models that exist in different subscriptions is currently in preview. Preview features may not have the same level of availability and reliability as features in general release. For the most up-to-date notifications on availability and status of preview features, check the Azure Virtual Network updates page.

You must first register for the cross-subscription, cross-deployment model feature, before you can use it. Complete the following steps within the subscription that each virtual network you want to peer is in, using Azure PowerShell or the Azure CLI:

PowerShell

  1. Install the latest version of the PowerShell AzureRm module. If you're new to Azure PowerShell, see Azure PowerShell overview.
  2. Start a PowerShell session and log in to Azure using the Login-AzureRmAccount command.
  3. Register the subscription that each virtual network you want to peer is in for the preview by entering the following commands:

    Register-AzureRmProviderFeature `
      -FeatureName AllowClassicCrossSubscriptionPeering `
      -ProviderNamespace Microsoft.Network
    
    Register-AzureRmResourceProvider `
      -ProviderNamespace Microsoft.Network
    
  4. Confirm that you are registered for the preview by entering the following command:

    Get-AzureRmProviderFeature `
      -FeatureName AllowClassicCrossSubscriptionPeering `
      -ProviderNamespace Microsoft.Network
    

    Do not complete the steps in the Portal, Azure CLI, PowerShell, or Resource Manager template sections of this article until the RegistrationState output you receive after entering the previous commands is Registered for both subscriptions.

Note

This tutorial uses virtual networks that exist in the same region. The ability to peer virtual networks in different regions is also in preview. To register for cross-region, or global peering, complete steps 1-4 again, using -FeatureName AllowGlobalVnetPeering instead of -FeatureName AllowClassicCrossSubscriptionPeering. The two capabilities are independent of each other. You do not need to register for both, unless you want to use both. The capability is available in a limited set of regions (initially, US West Central, Canada Central, and US West 2).

Azure CLI

  1. Install and configure the Azure CLI.
  2. Ensure you are using version 2.0.18 or higher of the Azure CLI by entering the az --version command. If you are not, install the most recent version.
  3. Log in to Azure with the az login command.
  4. Register for the preview by entering the following commands:

    az feature register --name AllowGlobalVnetPeering --namespace Microsoft.Network
    az provider register --name Microsoft.Network
    
  5. Confirm that you are registered for the preview by entering the following command:

    az feature show --name AllowGlobalVnetPeering --namespace Microsoft.Network
    

    Do not complete the steps in the Portal, Azure CLI, PowerShell, or Resource Manager template sections of this article until the RegistrationState output you receive after entering the previous command is Registered for both subscriptions.

Note

This tutorial uses virtual networks that exist in the same region. The ability to peer virtual networks in different regions is also in preview. To register for cross-region, or global peering, complete steps 1-5 again, using --name AllowGlobalVnetPeering instead of --name AllowClassicCrossSubscriptionPeering. The two capabilities are independent of each other. You do not need to register for both, unless you want to use both. The capability is available in a limited set of regions (initially, US West Central, Canada Central, and US West 2).

Next steps