Create, change, or delete a virtual network peering

Learn how to create, change, or delete a virtual network peering. Virtual network peering enables you to connect virtual networks through the Azure backbone network. Once peered, the virtual networks are still managed as separate resources. If you're new to virtual network peering, you can learn more about it in the virtual network peering overview or by completing a tutorial.

Before you begin

Complete the following tasks before completing steps in any section of this article:

  • If you don't already have an Azure account, sign up for a free trial account.
  • If using the portal, open https://portal.azure.com, and log in with an account that has the necessary permissions to work with peerings.
  • If using PowerShell commands to complete tasks in this article, either run the commands in the Azure Cloud Shell, or by running PowerShell from your computer. The Azure 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. This tutorial requires the Azure PowerShell module version 5.7.0 or later. Run Get-Module -ListAvailable AzureRM to find the installed version. If you need to upgrade, see Install Azure PowerShell module. If you are running PowerShell locally, you also need to run Connect-AzureRmAccount with an account that has the necessary permissions to work with peering, to create a connection with Azure.
  • If using Azure Command-line interface (CLI) commands to complete tasks in this article, either run the commands in the Azure Cloud Shell, or by running the CLI from your computer. This tutorial requires the Azure CLI version 2.0.31 or later. Run az --version to find the installed version. If you need to install or upgrade, see Install Azure CLI 2.0. If you are running the Azure CLI locally, you also need to run az login with an account that has the necessary permissions to work with peering, to create a connection with Azure.

The account you log into, or connect to Azure with, must be assigned to the network contributor role or to a custom role that is assigned the appropriate actions listed in Permissions.

Create a peering

Before creating a peering, familiarize yourself with the requirements and constraints and necessary permissions.

  1. In the search box at the top of the Azure portal, enter virtual networks in the search box. When Virtual networks appear in the search results, select it. Do not select Virtual networks (classic) if it appears in the list, as you cannot create a peering from a virtual network deployed through the classic deployment model.
  2. Select the virtual network in the list that you want to create a peering for.
  3. From the list of virtual networks, select the virtual network you want to create a peering for.
  4. Under SETTINGS, select Peerings.
  5. Select + Add.
  6. Enter or select values for the following settings:

    • Name: The name for the peering must be unique within the virtual network.
    • Virtual network deployment model: Select which deployment model the virtual network you want to peer with was deployed through.
    • I know my resource ID: If you have read access to the virtual network you want to peer with, leave this checkbox unchecked. If you don't have read access to the virtual network or subscription you want to peer with, check this box. Enter the full resource ID of the virtual network you want to peer with in the Resource ID box that appeared when you checked the box. The resource ID you enter must be for a virtual network that exists in the same, or supported different Azure region as this virtual network. The full resource ID looks similar to /subscriptions//resourceGroups//providers/Microsoft.Network/virtualNetworks/. You can get the resource ID for a virtual network by viewing the properties for a virtual network. To learn how to view the properties for a virtual network, see Manage virtual networks.
    • Subscription: Select the subscription of the virtual network you want to peer with. One or more subscriptions are listed, depending on how many subscriptions your account has read access to. If you checked the Resource ID checkbox, this setting isn't available.
    • Virtual network: Select the virtual network you want to peer with. You can select a virtual network created through either Azure deployment model. If you want to select a virtual network in a different region, you must select a virtual network in a supported region. You must have read access to the virtual network for it to be visible in the list. If a virtual network is listed, but grayed out, it may be because the address space for the virtual network overlaps with the address space for this virtual network. If virtual network address spaces overlap, they cannot be peered. If you checked the Resource ID checkbox, this setting isn't available.
    • Allow virtual network access: Select Enabled (default) if you want to enable communication between the two virtual networks. Enabling communication between virtual networks allows resources connected to either virtual network to communicate with each other with the same bandwidth and latency as if they were connected to the same virtual network. All communication between resources in the two virtual networks is over the Azure private network. The VirtualNetwork service tag for network security groups encompasses the virtual network and peered virtual network. To learn more about network security group service tags, see Network security groups overview. Select Disabled if you don't want traffic to flow to the peered virtual network. You might select Disabled if you've peered a virtual network with another virtual network, but occasionally want to disable traffic flow between the two virtual networks. You may find enabling/disabling is more convenient than deleting and re-creating peerings. When this setting is disabled, traffic doesn't flow between the peered virtual networks.
    • Allow forwarded traffic: Check this box to allow traffic forwarded by a network virtual appliance in a virtual network (that didn't originate from the virtual network) to flow to this virtual network through a peering. For example, consider three virtual networks named Spoke1, Spoke2, and Hub. A peering exists between each spoke virtual network and the Hub virtual network, but peerings don't exist between the spoke virtual networks. A network virtual appliance is deployed in the Hub virtual network, and user-defined routes are applied to each spoke virtual network that route traffic between the subnets through the network virtual appliance. If this checkbox is not checked for the peering between each spoke virtual network and the hub virtual network, traffic doesn't flow between the spoke virtual networks because the hub is forwarding the traffic between the virtual networks. While enabling this capability allows the forwarded traffic through the peering, it does not create any user-defined routes or network virtual appliances. User-defined routes and network virtual appliances are created separately. Learn about user-defined routes. You don't need to check this setting if traffic is forwarded between virtual networks through an Azure VPN Gateway.
    • Allow gateway transit: Check this box if you have a virtual network gateway attached to this virtual network and want to allow traffic from the peered virtual network to flow through the gateway. For example, this virtual network may be attached to an on-premises network through a virtual network gateway. The gateway can be an ExpressRoute or VPN gateway. Checking this box allows traffic from the peered virtual network to flow through the gateway attached to this virtual network to the on-premises network. If you check this box, the peered virtual network cannot have a gateway configured. The peered virtual network must have the Use remote gateways checkbox checked when setting up the peering from the other virtual network to this virtual network. If you leave this box unchecked (default), traffic from the peered virtual network still flows to this virtual network, but cannot flow through a virtual network gateway attached to this virtual network. If the peering is between a virtual network (Resource Manager) and a virtual network (classic), the gateway must be in the virtual network (Resource Manager). You cannot enable this option if you're peering virtual networks in different regions.

      In addition to forwarding traffic to an on-premises network, a VPN gateway can forward network traffic between virtual networks that are peered with the virtual network the gateway is in, without the virtual networks needing to be peered with each other. Using a VPN gateway to forward traffic is useful when you want to use a VPN gateway in a hub (see the hub and spoke example described for Allow forwarded traffic) virtual network to route traffic between spoke virtual networks that aren't peered with each other. To learn more about allowing use of a gateway for transit, see Configure a VPN gateway for transit in a virtual network peering. This scenario requires implementing user-defined routes that specify the virtual network gateway as the next hop type. Learn about user-defined routes. You can only specify a VPN gateway as a next hop type in a user-defined route, you cannot specify an ExpressRoute gateway as the next hop type in a user-defined route. You cannot enable this option if you're peering virtual networks in different regions.

    • Use remote gateways: Check this box to allow traffic from this virtual network to flow through a virtual network gateway attached to the virtual network you're peering with. For example, the virtual network you're peering with has a VPN gateway attached that enables communication to an on-premises network. Checking this box allows traffic from this virtual network to flow through the VPN gateway attached to the peered virtual network. If you check this box, the peered virtual network must have a virtual network gateway attached to it and must have the Allow gateway transit checkbox checked. If you leave this box unchecked (default), traffic from the peered virtual network can still flow to this virtual network, but cannot flow through a virtual network gateway attached to this virtual network. Only one peering for this virtual network can have this setting enabled.

      You cannot use remote gateways if you already have a gateway configured in your virtual network. You cannot enable this option if you're peering virtual networks in different regions. To learn more about using a gateway for transit, see Configure a VPN gateway for transit in a virtual network peering

  7. Select OK to add the peering to the virtual network you selected.

For step-by-step instructions for implementing peering between virtual networks in different subscriptions and deployment models, see next steps.

Commands

View or change peering settings

Before changing a peering, familiarize yourself with the requirements and constraints and necessary permissions.

  1. In the search box at the top of the portal, enter virtual networks in the search box. When Virtual networks appear in the search results, select it. Do not select Virtual networks (classic) if it appears in the list, as you cannot create a peering from a virtual network deployed through the classic deployment model.
  2. Select the virtual network in the list that you want to change peering settings for.
  3. From the list of virtual networks, select the virtual network you want to change peering settings for.
  4. Under SETTINGS, select Peerings.
  5. Select the peering you want to view or change settings for.
  6. Change the appropriate setting. Read about the options for each setting in step 6 of Create a peering.
  7. Select Save.

Commands

Delete a peering

Before deleting a peering, ensure your account has the necessary permissions.

When a peering is deleted, traffic from a virtual network no longer flows to the peered virtual network. When virtual networks deployed through Resource Manager are peered, each virtual network has a peering to the other virtual network. Though deleting the peering from one virtual network disables the communication between the virtual networks, it does not delete the peering from the other virtual network. The peering status for the peering that exists in the other virtual network is Disconnected. You cannot recreate the peering until you re-create the peering in the first virtual network and the peering status for both virtual networks changes to Connected.

If you want virtual networks to communicate sometimes, but not always, rather than deleting a peering, you can set the Allow virtual network access setting to Disabled instead. To learn how, read step 6 of the Create a peering section of this article. You may find disabling and enabling network access easier than deleting and recreating peerings.

  1. In the search box at the top of the portal, enter virtual networks in the search box. When Virtual networks appear in the search results, select it. Do not select Virtual networks (classic) if it appears in the list, as you cannot create a peering from a virtual network deployed through the classic deployment model.
  2. Select the virtual network in the list that you want to delete a peering for.
  3. From the list of virtual networks, select the virtual network you want to delete a peering for.
  4. Under SETTINGS, select Peerings.
  5. On the right side of the peering you want to delete, select ..., select Delete, then select Yes to delete the peering from the first virtual network.
  6. Complete the previous steps to delete the peering from the other virtual network in the peering.

Commands

Requirements and constraints

  • You can peer virtual networks in the same region, or different regions. The following constraints do not apply when both virtual networks are in the same region, but do apply when the virtual networks are globally peered:
    • The virtual networks can exist in any Azure public cloud region, but not in Azure national clouds.
    • Resources in one virtual network cannot communicate with the IP address of an Azure internal load balancer in the peered virtual network. The load balancer and the resources that communicate with it must be in the same virtual network.
    • You cannot use remote gateways or allow gateway transit. To use remote gateways or allow gateway transit, both virtual networks in the peering must exist in the same region.
  • The virtual networks can be in the same, or different subscriptions. When the virtual networks are in different subscriptions, both subscriptions must be associated to the same Azure Active Directory tenant. If you don't already have an AD tenant, you can quickly create one. You can use a VPN Gateway to connect two virtual networks that exist in different subscriptions that are associated to different Active Directory tenants.
  • The virtual networks you peer must have non-overlapping IP address spaces.
  • You can't add address ranges to, or delete address ranges from a virtual network's address space once a virtual network is peered with another virtual network. To add or remove address ranges, delete the peering, add or remove the address ranges, then re-create the peering. To add address ranges to, or remove address ranges from virtual networks, see Manage virtual networks.
  • You can peer two virtual networks deployed through Resource Manager or a virtual network deployed through Resource Manager with a virtual network deployed through the classic deployment model. You cannot peer two virtual networks created through the classic deployment model. If you're not familiar with Azure deployment models, read the Understand Azure deployment models article. You can use a VPN Gateway to connect two virtual networks created through the classic deployment model.
  • When peering two virtual networks created through Resource Manager, a peering must be configured for each virtual network in the peering. You see one of the following types for peering status:
    • Initiated: When you create the peering to the second virtual network from the first virtual network, the peering status is Initiated.
    • Connected: When you create the peering from the second virtual network to the first virtual network, its peering status is Connected. If you view the peering status for the first virtual network, you see its status changed from Initiated to Connected. The peering is not successfully established until the peering status for both virtual network peerings is Connected.
  • When peering a virtual network created through Resource Manager with a virtual network created through the classic deployment model, you only configure a peering for the virtual network deployed through Resource Manager. You cannot configure peering for a virtual network (classic), or between two virtual networks deployed through the classic deployment model. When you create the peering from the virtual network (Resource Manager) to the virtual network (Classic), the peering status is Updating, then shortly changes to Connected.
  • A peering is established between two virtual networks. Peerings are not transitive. If you create peerings between:

    • VirtualNetwork1 & VirtualNetwork2
    • VirtualNetwork2 & VirtualNetwork3

    There is no peering between VirtualNetwork1 and VirtualNetwork3 through VirtualNetwork2. If you want to create a virtual network peering between VirtualNetwork1 and VirtualNetwork3, you have to create a peering between VirtualNetwork1 and VirtualNetwork3.

  • You can't resolve names in peered virtual networks using default Azure name resolution. To resolve names in other virtual networks, you must use Azure DNS for private domains or a custom DNS server. To learn how to set up your own DNS server, see Name resolution using your own DNS server.
  • Resources in peered virtual networks in the same region can communicate with each other with the same bandwidth and latency as if they were in the same virtual network. Each virtual machine size has its own maximum network bandwidth however. To learn more about maximum network bandwidth for different virtual machine sizes, see Windows or Linux virtual machine sizes.
  • A virtual network can be peered to another virtual network, and also be connected to another virtual network with an Azure virtual network gateway. When virtual networks are connected through both peering and a gateway, traffic between the virtual networks flows through the peering configuration, rather than the gateway.
  • There is a nominal charge for ingress and egress traffic that utilizes a virtual network peering. For more information, see the pricing page.

Permissions

The accounts you use to work with virtual network peering must be assigned to the following roles:

If your account is not assigned to one of the previous roles, it must be assigned to a custom role that is assigned the necessary actions from the following table:

Action Name
Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write Required to create a peering from virtual network A to virtual network B. Virtual network A must be a virtual network (Resource Manager)
Microsoft.Network/virtualNetworks/peer/action Required to create a peering from virtual network B (Resource Manager) to virtual network A
Microsoft.ClassicNetwork/virtualNetworks/peer Required to create a peering from virtual network B (classic) to virtual network A
Microsoft.Network/virtualNetworks/virtualNetworkPeerings/read Read a virtual network peering
Microsoft.Network/virtualNetworks/virtualNetworkPeerings/delete Delete a virtual network peering

Next steps

  • A virtual network peering is created between virtual networks created through the same, or different deployment models that exist in the same, or different subscriptions. Complete a tutorial for one of the following scenarios:

    Azure deployment model Subscription
    Both Resource Manager Same
    Different
    One Resource Manager, one classic Same
    Different
  • Learn how to create a [hub and spoke network topology](/azure/architecture/reference-architectures/hybrid-networking/hub-spoke?toc=%2fazure%2fvirtual-network%2ftoc.json#virtual network-peering)

  • Create a virtual network peering using PowerShell or Azure CLI sample scripts, or using Azure Resource Manager templates
  • Create and apply Azure policy for virtual networks