Set up and manage VPC Network Peering

Google Cloud VPC Network Peering enables internal IP address connectivity across two Virtual Private Cloud (VPC) networks, regardless of whether they belong to the same project or the same organization. Peering supports connectivity between networks having any combination of IPv4-only, dual-stack, and IPv6-only (Preview) subnets.

For more information, see VPC Network Peering.

Create a peering configuration

Before you begin, you must have the name of the VPC network to which you will peer with. If that network is located in another project, you must also have the project ID of that project. You can't list peering requests for your VPC network. If necessary, ask the administrator of the network that you intend to peer with for the network and project names.

A peering configuration establishes the intent to connect to another VPC network. Your network and the other network are not connected until each one has a peering configuration for the other. After the other network has a corresponding configuration to peer with your network, the peering state changes to ACTIVE in both networks, and they are connected. If there's no matching peering configuration in the other network, the peering state remains INACTIVE, indicating that your network is not connected to the other one.

Google Cloud allows only one peering-related activity at a time across peered networks. For example, if you set up peering with one network and immediately try to set up another, the operation fails with the following: Error: There is a peering operation in progress on the local or peer network. Try again later.

After connected, the two VPC networks always exchange IPv4 subnet routes (primary and secondary IPv4 subnet ranges) that use private IPv4 address ranges. For more information about subnet route exchange options, see Options for exchanging subnet routes. For details about exchanging static or dynamic routes, see Options for exchanging static routes and Options for exchanging dynamic routes.

Update strategy

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

The update strategy is a property of a peering configuration. VPC Network Peering supports two update strategies: INDEPENDENT (default) and CONSENSUS. By default, either side of a peering connection can update or delete the connection at any time. You can optionally restrict this behavior by configuring the CONSENSUS update strategy for the peering connection.

The following applies to peering connections that use the CONSENSUS update strategy:

• After a request to configure the CONSENSUS update strategy for a peering connection is initiated, no other changes can be proposed until the request is accepted or reverted.
• To delete a peering connection, both sides of the connection must submit a deletion request before the connection can be deleted. If a deletion request is in progress, all update requests are rejected.
• Pending requests don't cause downtime, and the connection remains active while the request is in progress.
• Limitation: updating a peering connection that is configured to use the CONSENSUS update strategy isn't supported.

Create a configuration

To create a peering configuration, do the following.

Console

1. In the Google Cloud console, go to the VPC Network Peering page .
   Go to VPC Network Peering
2. Click Create connection.
3. Click Continue.
4. In the Name field, enter a name for your peering configuration.
5. Under Your VPC network, select a network you want to peer.

6. Select the network to peer with.

   • If the network that you want to peer with is in the same project, select In project [NAME-OF-YOUR-PROJECT] and then the network to peer with.
   • If the network that you want to peer with is in a different project, select In another project. Specify the project ID that includes the network you want to peer with and the name of the VPC network.

7. Under IP stack type, specify which subnet routes should be exchanged between the peered networks:

   • IPv4 (single-stack): Exchange IPv4 routes only.
   • IPv4 and IPv6 (dual-stack): Exchange both IPv4 and IPv6 routes.

8. To import or export IPv4 and IPv6 custom routes, choose one or both of the following options:

   • Import custom routes: Import custom routes from the peer network. The peer network must enable custom route export for routes to be imported.
   • Export custom routes: Export custom routes to the peer network. The peer network must enable custom route import for routes to be exported.

9. If your network or the peer network uses privately used public IPv4 ranges in their subnets, these routes are exported by default, but not imported by default. To import privately used public IPv4 subnet routes, select:

   • Import subnet routes with public IP to import privately used public IPv4 subnet routes exported by the other network

10. Click Create.

gcloud

Create a peering configuration by using the gcloud compute networks peerings create command. Use the beta version of the command if you want to change the default update strategy for the peering connection.

The square brackets [] in the following commands indicate optional flags:

• --import-custom-routes tells the network to accept custom routes from the peered network. The peered network must export the routes first.
• --export-custom-routes tells the network to export custom routes to the peered network. The peered network must be set to import the routes.
• --import-subnet-routes-with-public-ip tells the network to accept subnet routes from the peered network if that network is using privately used public IPv4 addresses in its subnets. The peered network must export the routes first.
• --export-subnet-routes-with-public-ip tells the network to export subnet routes that contain privately used public IPv4 addresses. The peered network must be set to import the routes.

gcloud compute networks peerings create PEERING_NAME \
    --network=NETWORK \
    --peer-project=PEER_PROJECT_ID \
    --peer-network=PEER_NETWORK_NAME \
    [--stack-type=STACK_TYPE] \
    [--import-custom-routes] \
    [--export-custom-routes] \
    [--import-subnet-routes-with-public-ip] \
    [--export-subnet-routes-with-public-ip]

Use the --update-strategy flag (Preview) to set the update strategy for the peering connection:

gcloud beta compute networks peerings create PEERING_NAME \
    --network=NETWORK \
    --peer-project=PEER_PROJECT_ID \
    --peer-network=PEER_NETWORK_NAME \
    [--stack-type=STACK_TYPE] \
    [--import-custom-routes] \
    [--export-custom-routes] \
    [--import-subnet-routes-with-public-ip] \
    [--export-subnet-routes-with-public-ip] \
    [--update-strategy=UPDATE_STRATEGY]

Replace the following:

• PEERING_NAME: the name of the peering configuration.
• NETWORK: the name of the network in your project that you want to peer.
• PEER_PROJECT_ID: the ID of the project containing the network that you want to peer with.
• PEER_NETWORK_NAME: the name of the network that you want to peer with.
• STACK_TYPE: the stack type for the peering connection. Specify IPV4_ONLY to exchange only IPv4 routes. Alternatively, specify IPV4_IPV6 to exchange both IPv4 and IPv6 routes. IPV4_ONLY is the default value.
• UPDATE_STRATEGY: the update strategy for the peering connection. Specify CONSENSUS. When the flag isn't specified, the value is set to INDEPENDENT (default). The update strategy must be the same for both sides of the connection.

Terraform

You can use a Terraform module to create a peering configuration.

module "peering1" {
  source        = "terraform-google-modules/network/google//modules/network-peering"
  version       = "~> 10.0"
  local_network = var.local_network # Replace with self link to VPC network "foobar" in quotes
  peer_network  = var.peer_network  # Replace with self link to VPC network "other" in quotes
}

For the two peered VPC networks, each self link includes a project ID and the name of the VPC network. To get the self link for a VPC network, you can use the gcloud compute networks describe command or the networks.get method in each VPC network's project.

When you create a peering from the local_network to the peer_network, the peering relationship is bidirectional. The peering from the peer_network to the local_network gets created automatically.

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Verify that traffic is passing between peered VPC networks

You can use VPC Flow Logs to view network flows sent from and received by VM instances. You can also use Firewall Rules Logging to verify that traffic is passing between the networks. Create VPC firewall rules that allow (or deny) traffic between the peered networks, and turn on Firewall Rules Logging for those rules. You can then view which firewall rules were hit using Cloud Logging.

Update a peering connection

When you update an existing VPC Network Peering connection, you can do the following:

• Change whether your VPC network exports or imports custom routes or privately used public IPv4 subnet routes to or from the peer VPC network.
• Update an existing peering connection to enable or disable the exchange of IPv6 routes between the peered networks.
• Change the update strategy for the peering connection from INDEPENDENT (default) to CONSENSUS. Changing the update strategy from CONSENSUS to INDEPENDENT isn't supported.

Your network imports routes only if the peer network is also exporting the routes, and the peer network receives routes only if it imports them.

Important: Even if the dynamic routing mode of the VPC network is set to global, IPv6 routes learned from the Cloud Router are regional. For more information, see Limitations.

Update a connection

Console

1. In the Google Cloud console, go to the VPC Network Peering page.
   Go to VPC Network Peering
2. Select the peering connection to update.
3. Click Edit.
4. Update the IP stack type selection to specify which subnet routes should be exchanged between the peered networks:
   • IPv4 (single-stack): Stop the existing exchange of IPv6 routes over the peering and continue exchanging only IPv4 routes.
   • IPv4 and IPv6 (dual-stack): Start exchanging both IPv4 and IPv6 routes, provided that the matching peering connection also has IP stack type set to IPv4 and IPv6 (dual-stack).
5. To import or export IPv4 and IPv6 custom routes, choose one or both of the following options:
   • Import custom routes to import custom routes exported by the other network
   • Export custom routes to export custom routes to the other network. The other network must import the routes to see them.
6. If your network or the peer network uses privately used public IPv4 ranges in their subnets, these routes are exported by default, but not imported by default. To import privately used public IPv4 subnet routes, select:
   • Import subnet routes with public IP to import privately used public IPv4 subnet routes exported by the other network
   • Click Save.

gcloud

Use the gcloud compute networks peerings update command. The square brackets [] in the following command indicate optional flags:

• --import-custom-routes tells the network to accept custom routes from the peered network. The peered network must export the routes first.
• --export-custom-routes tells the network to export custom routes to the peered network. The peered network must be set to import the routes.
• --import-subnet-routes-with-public-ip tells the network to accept subnet routes from the peered network if that network is using privately used public IPv4 addresses in its subnets. The peered network must export the routes first.
• --export-subnet-routes-with-public-ip tells the network to export subnet routes that contain privately used public IPv4 addresses. The peered network must be set to import the routes.

gcloud compute networks peerings update PEERING_NAME \
    --network=NETWORK \
    [--stack-type=STACK_TYPE] \
    [--import-custom-routes] \
    [--export-custom-routes] \
    [--export-subnet-routes-with-public-ip] \
    [--import-subnet-routes-with-public-ip]

Replace the following:

• PEERING_NAME: the name of the existing peering connection.
• NETWORK: the name of the network in your project that is peered.
• STACK_TYPE: the stack type for the peering connection.
  • Specify IPV4_ONLY to stop the existing exchange of IPv6 routes over the peering and continue exchanging only IPv4 routes.
  • Specify IPV4_IPV6 to start exchanging both IPv4 and IPv6 routes, provided the matching peering connection also has stack_type set to IPV4_IPV6.

Change the default update strategy

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To change the update strategy for a peering connection from INDEPENDENT (default) to CONSENSUS, both the local and peer sides of the connection must be updated. Before changing the update strategy, make sure the configuration from both sides matches. If any values don't match, either update them beforehand or as part of the update request that changes the update strategy for the connection.

gcloud

Use the gcloud beta compute networks peerings update command.

1. Update the local peering configuration:

   gcloud beta compute networks peerings update PEERING_NAME \
       --network=NETWORK \
       --update-strategy=CONSENSUS
   

   Replace the following:

   • PEERING_NAME: the name of the existing peering connection.
   • NETWORK: the name of the network in your project that is peered.

2. View the status of the update request:

   gcloud beta compute networks describe NETWORK
   

   Replace NETWORK with the name of the network in your project that is peered.

   In the output, view the consensusState field. For the local network, the value is set to PENDING_PEER_ACKNOWLEDGMENT.

   In the matching configuration for the peer network, this field is set to PENDING_LOCAL_ACKNOWLEDGMENT.

3. To complete the update request, a network administrator for the peer network must accept it by running the command in step 1 for the matching configuration. The effective update strategy of the peering connection remains INDEPENDENT until the peer network accepts the update request.

   After the request is complete, the consensusState field changes to IN_SYNC for both networks.

To revert a change that isn't accepted by the peer network, reset the --update-strategy parameter to INDEPENDENT.

List peering connections

List existing peering connections to view their status and whether they're importing or exporting custom routes.

Console

1. In the Google Cloud console, go to the VPC Network Peering page.
   Go to VPC Network Peering
2. Select the peering connection to view its details.

gcloud

gcloud compute networks peerings list

View a peering connection

gcloud

Use the gcloud beta compute networks describe command.

gcloud beta compute networks describe NETWORK

Replace NETWORK with the name of the network in your project that is peered.

In the output, the connectionStatus field describes the effective status of the peering connection.

List peering routes

Console

Use the Effective routes tab to view all applicable route types in a VPC network, including imported peering subnet, peering static, and peering dynamic routes.

1. In the Google Cloud console, go to the Routes page.

   Go to Routes

2. On the Effective routes tab, do the following:

   • Select a VPC network.
   • Select a Region.

3. Click View.

4. Click the Filter text field, and do the following:

   • Choose Type from the Properties menu.
   • Choose one of the following from the Values menu.
     • Peering subnet: to see subnet routes from peer VPC networks.
     • Peering static: to see imported static routes from peer VPC networks.
     • Peering dynamic: to see imported dynamic routes from peer VPC networks.

5. Optionally, click Show suppressed routes to view routes that are suppressed. Place your pointer over the icon in the Status column to view the reason why a route has been suppressed. The reason includes a link to the routing order documentation with an explanation.

gcloud

Use the following Google Cloud CLI command to:

• List route exports sent from your VPC network to peer VPC networks.
• List route import candidates for your VPC network.

Important: Route exports from your VPC network always become route import candidates in each peer VPC network, but neither list takes into consideration conflict resolution in the importing VPC network. To see which routes are actually imported and which routes are omitted, use the Effective routes tab in the Google Cloud console.

gcloud compute networks peerings list-routes PEERING_NAME \
    --network=NETWORK \
    --region=REGION \
    --direction=DIRECTION

Replace the following:

• PEERING_NAME: the name of an existing peering connection.
• NETWORK: the name of the network in your project that is peered.
• REGION: the region where you want to list all dynamic routes. Subnet and static routes are global and are shown for all regions.
• DIRECTION: specifies whether to list imported (incoming) or exported (outgoing) routes.

Delete a peering connection

How you delete a VPC Network Peering connection depends on the update strategy of the connection:

• If the update strategy is set to INDEPENDENT (default), you or a network administrator for the peer VPC network can delete the connection at any time. See Delete a connection (independent).
• If the update strategy is set to CONSENSUS, both you and a network administrator for the peer VPC network must submit a delete request before the connection can be deleted. See Delete a connection (consensus).

When a peering configuration is deleted in your network, the peering connection becomes INACTIVE in the other network and all routes shared among the networks are removed.

Warning: Don't delete a VPC Network Peering connection that is already in use and is attached to Google Cloud resources. For example, if you delete a connection that is used by Google Kubernetes Engine (GKE), the cluster enters a repair state and all nodes show an UNKNOWN status. For more information, see VPC Network Peering connection is accidentally deleted.

Delete a connection (independent)

To delete a peering connection that is configured with the default update strategy (INDEPENDENT), do the following.

Console

1. Go to the VPC Network Peering page in the Google Cloud console.
   Go to VPC Network Peering
2. Select the checkbox next to the peering you want to remove.
3. Click Delete.

gcloud

gcloud compute networks peerings delete PEERING_NAME \
    --network=NETWORK

Replace the following:

• PEERING_NAME: the name of the peering connection to delete.
• NETWORK: the name of the network in your project that is peered.

Delete a connection (consensus)

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To delete a peering connection that is configured with the CONSENSUS update strategy, do the following.

gcloud

Use the gcloud beta compute networks peerings request-delete and gcloud compute networks peerings delete commands.

1. Initiate a deletion request:

   gcloud beta compute networks peerings request-delete PEERING_NAME \
       --network=NETWORK
   

   Replace the following:

   • PEERING_NAME: the name of the peering connection to delete.
   • NETWORK: the name of the network in your project that is peered.

2. View the status of the deletion request:

   gcloud beta compute networks describe NETWORK
   

   Replace NETWORK with the name of the network in your project that is peered.

   In the output, view the deleteStatus field. For the local network, the value is set to LOCAL_DELETE_REQUESTED.

   In the matching configuration for the peer network, this field is set to PEER_DELETE_REQUESTED.

3. After you initiate the request, a network administrator for the peer network must accept the request by running the command in step 1 for the matching configuration.

4. After the peer network accepts the deletion request and the status of the deleteStatus field changes to DELETE_ACKNOWLEDGED for both networks, delete the peering connection:

   gcloud compute networks peerings delete PEERING_NAME \
       --network=NETWORK
   

   Replace the following:

   • PEERING_NAME: the name of the peering connection to delete.
   • NETWORK: the name of the network in your project that is peered.

Troubleshooting

The following sections describe how to troubleshoot issues with VPC Network Peering.

Peer VMs are unreachable

After the peering connection is ACTIVE, it may take up to a minute for all the traffic flows to be set up between the peered networks. This time depends on the size of the networks that are peering. If you have recently set up the peering connection, wait up to a minute and try again. Also, ensure that there are no firewall rules blocking access to/from peer VPC network subnet CIDRs.

Custom routes are missing

This section describes how to troubleshoot missing custom routes.

Check the peering connection state

To check the state of your peering connection, do the following:

1. List peering connections.
2. Identify the peering connection to troubleshoot, and review its peering state.
   1. If the state is ACTIVE, follow the steps in the next section.
   2. If the peering state is INACTIVE, a network administrator for the other network needs to create a peering configuration to your VPC network.

Troubleshoot an ACTIVE connection

To troubleshoot missing custom routes in an ACTIVE peering connection:

1. List peering routes in your VPC network. In the Effective routes tab, do the following:

   1. Consider that the regions in which dynamic routes are programmed depends on the dynamic routing mode of the VPC network that exports custom routes. For more details, see Effects of the dynamic routing mode. In global dynamic routing mode, only the highest ranked dynamic route is programmed in regions that don't match the region of the next hop.

   2. Click the Show suppressed routes toggle to the on position, then check for your route. To view the reason why a route has been suppressed, point to the icon in the Status column. Google Cloud provides route conflict resolution on a region-by-region basis in the VPC network that imports routes using VPC Network Peering.

   3. Look for a warning indicating that your VPC network has reached the limit for the dynamic routes per region per peering group quota. If your VPC network has reached the limit for this quota, one or more peering dynamic routes aren't programmed. Because it's not possible to show exactly which peering dynamic routes aren't programmed, request a quota limit increase for the dynamic routes per region per peering group quota.

2. If you still don't see the route you expect, do the following:

   1. Review your peering configuration, and update your peering configuration if necessary so that it imports custom routes.

   2. Ensure that the route is not one of the following route types that can't be exchanged using VPC Network Peering:

      • Peering subnet, peering static, and peering dynamic routes in a peered VPC network that are received from its other peer networks cannot be exchanged to your VPC network using VPC Network Peering.

      • Static routes that use the default internet gateway next hop and static routes with network tags cannot be exchanged using VPC Network Peering.

      For more information, see Route exchange options.

   3. Ask a network administrator of the peered VPC network to:

      1. List routes in their VPC network, looking for the route you expect.

      2. Review their peering configuration, and update the peering configuration if necessary so that it exports custom routes.

Traffic destined for a peer network is being dropped

You can use Connectivity Tests to help determine why traffic destined for a peer network is being dropped. If traffic should be sent using custom routes, see Custom routes are missing.

Traffic is being sent to an unexpected next hop

You can use Connectivity Tests to help determine why traffic is being sent to an unexpected next hop. If traffic should be sent using custom routes, see Custom routes are missing.

Unable to peer with a particular VPC network

If you cannot create a peering configuration with certain VPC networks, an organization policy might be constraining the VPC networks that your network can peer with. In the organization policy, add the network to the list of allowed peers or contact your organization administrator. For more information, refer to the constraints/compute.restrictVpcPeering constraint.

IPv6 routes are not exchanged

First, verify that both your peering connection and the peering connection of the peered VPC network have their stack types set to IPV4_IPV6. If necessary:

• Update your peering connection to set its stack type to IPV4_IPV6.
• Ask a network administrator of the peered VPC network to update their peering connection, setting its stack type to IPV4_IPV6.

After both peering connections have their stack types set to IPV4_IPV6, IPv6 subnet routes (both internal and external) are exchanged. IPv6 subnet routes are unique among all Google Cloud VPC networks.

To exchange IPv6 custom routes:

• Update your peering connection to import and export custom routes.
• Ask a network administrator of the peered VPC network to update their peering connection to import and export custom routes.

What's next

• For more information about VPC routing, see Routes.
• For limits related to VPC Network Peering, see VPC Network Peering limits.
• For information about how to use an internal passthrough Network Load Balancer as the next hop for a custom static route, see Use an internal passthrough Network Load Balancer as a next hop.