Migrate a service subnet from peering to Private Service Connect

This document describes how service producers can migrate their peering-based services to Private Service Connect and preserve the IP address that is used to access the service. This migration process requires that all resources that are connected to a given subnet must be migrated at the same time.

The migration process is initiated by the service producer, but involves tasks that are completed by both the producer and consumer. Google-managed services can use a service agent to perform tasks on behalf of the consumer. The migration involves a downtime and a change in pricing for both the producer and the consumer.

Each service producer determines whether and when they are going to migrate to Private Service Connect. To learn whether a service producer is migrating from VPC Network Peering to Private Service Connect, check the service documentation or contact the service producer.

Before you begin

Make sure that you understand the migration process, including considerations for migration.
Make sure that you understand the pricing for Private Service Connect consumers and producers.
Make sure that you are familiar with publishing a service through Private Service Connect.

Deploy the service by using Private Service Connect

Create a new VPC network, deploy service resources in the network, and publish the service through Private Service Connect.

When you create the load balancer for the service, use a different IP address than the one that was previously used by the load balancer. The original IP address is needed later to create the endpoint.

When you publish a service, you create a service attachment. The service attachment URI is also needed later to create the endpoint.

Shut down the peering-based service

To shut down the peering-based service, you must create an internal range to reserve the service's IP address range before you delete the producer subnet.

Create an internal range

Before you delete the producer subnet, create an internal range to prevent the subnet's IP address range from being reused by other subnets in either the producer or consumer network.

For more information about this internal range, see Internal ranges for migration.

gcloud

Use the internal-ranges create command.

gcloud network-connectivity internal-ranges create RANGE_NAME \
    --project=PRODUCER_PROJECT_ID \
    --ip-cidr-range=CIDR_RANGE \
    --network=PRODUCER_NETWORK_NAME \
    --usage=FOR_MIGRATION \
    --migration-source=PRODUCER_SUBNET_URI \
    --migration-target=CONSUMER_SUBNET_URI

Replace the following:

RANGE_NAME: the name of the new internal range.
PRODUCER_PROJECT_ID: the ID of the producer project.
CIDR_RANGE: the CIDR range to allocate to the new internal range.
PRODUCER_NETWORK_NAME: the name of the network to create the internal range in.
PRODUCER_SUBNET_URI: the URI of the producer subnet that contains the load balancer for the service.
CONSUMER_SUBNET_URI: the URI of the intended consumer subnet. This subnet does not exist at the time you run this command.

Delete the peering producer subnet

You must delete all resources in the producer subnet before you can delete the subnet—for example, virtual machine (VM) instances, forwarding rules, instance groups, health checks, and reserved IP addresses. After you have deleted the resources, you can delete the subnet.

Create consumer resources

Work with the service consumer to create the following resources in their VPC network. The resources can be created manually, or for Google-managed services, can be automated through a service agent.

Create a peer migration subnet

Create a peer migration subnet in the consumer's VPC network to provide the IP address for the Private Service Connect endpoint. The subnet has the purpose PEER_MIGRATION which prevents the subnet from being used for resources other than Private Service Connect endpoints.

For more information, see Peer migration subnets.

gcloud

Use the networks subnets create command.

gcloud compute networks subnets create CONSUMER_SUBNET \
    --purpose=PEER_MIGRATION \
    --project=CONSUMER_PROJECT \
    --network=CONSUMER_NETWORK \
    --range=CIDR_RANGE \
    --region=REGION

Replace the following:

CONSUMER_SUBNET: the name of the consumer subnet
CONSUMER_PROJECT: the ID of the consumer project
CONSUMER_NETWORK: the name of the consumer network
CIDR_RANGE: the CIDR range to allocate to the new subnet; this range must match the CIDR range of the internal range
REGION: the region to create the subnet in

Create a Private Service Connect endpoint

Create a Private Service Connect endpoint in the consumer's peer migration subnet. The consumer needs the service attachment URI to create the endpoint.

gcloud

Reserve an internal IP address for the endpoint.

Use the addresses create command.
```
gcloud compute addresses create ENDPOINT_ADDRESS_NAME \
    --project=CONSUMER_PROJECT \
    --region=REGION \
    --address=ENDPOINT_ADDRESS \
    --subnet=CONSUMER_SUBNET
```
Replace the following:
- ENDPOINT_ADDRESS_NAME: a name for the IP address resource
- CONSUMER_PROJECT: the ID of the consumer project
- REGION: the region to create the IP address in
- ENDPOINT_ADDRESS: the IP address to assign to the IP address resource; this address must be the same IP address that was used in the service's load balancer
- CONSUMER_SUBNET: the name of the consumer subnet
Create the endpoint.

Use the forwarding-rules create command.
```
gcloud compute forwarding-rules create ENDPOINT \
    --region=REGION \
    --network=CONSUMER_NETWORK \
    --address=ENDPOINT_ADDRESS \
    --target-service-attachment=SERVICE_ATTACHMENT_URI
```
Replace the following:
- ENDPOINT: a name for the endpoint
- REGION: the region to create the endpoint in
- CONSUMER_NETWORK: the name of the consumer network
- ENDPOINT_ADDRESS: the reserved IP address to assign to the endpoint; you can specify the IP address directly, or use the IP address resource name
- SERVICE_ATTACHMENT_URI: the URI of the service attachment

Delete the producer's internal range

After the consumer migration subnet is created, the internal range is no longer needed and can be deleted.

gcloud

Use the internal-ranges delete command.

gcloud network-connectivity internal-ranges delete RANGE_NAME \
    --project=PRODUCER_PROJECT_ID

Replace the following:

RANGE_NAME: the name of the internal range
PRODUCER_PROJECT_ID: the ID of the producer project

Validate that the endpoint works

Ask the consumer to confirm that they can connect to the service through the endpoint.

If the endpoint isn't working, and troubleshooting doesn't resolve the issue, you can roll back the migration.

Finalize the migration

If the endpoint is working as expected, you can finalize the migration by updating the consumer's peer migration subnet to a regular subnet.

Update the consumer's peer migration subnet

Updating the consumer's peer migration subnet to a regular subnet lets the consumer use the subnet for any type of resource.

gcloud

Use the networks subnets create command.

gcloud compute networks subnets update CONSUMER_SUBNET \
    --purpose=PRIVATE \
    --region=REGION \
    --project=CONSUMER_PROJECT

Replace the following:

CONSUMER_SUBNET: the name of the consumer subnet
REGION: the region of the consumer subnet
CONSUMER_PROJECT: the ID of the consumer project

Delete the peering connections

If the peering connection is no longer needed, delete the peering configurations for both the consumer and the producer.

Roll back the migration

You can only roll back the migration if the consumer subnet hasn't yet been updated to a regular subnet. If you roll back, the service is made available through VPC Network Peering.

If it still exists, delete the internal range in the producer's project.

Create an internal range in the consumer's project. When rolling back, the migration source is the consumer subnet, and the migration target is the producer subnet.

gcloud network-connectivity internal-ranges create RANGE_NAME \
    --project=CONSUMER_PROJECT \
    --ip-cidr-range=CIDR_RANGE \
    --network=CONSUMER_NETWORK \
    --usage=FOR_MIGRATION \
    --migration-source=CONSUMER_SUBNET_URI \
    --migration-target=PRODUCER_SUBNET_URI

Delete the consumer's Private Service Connect endpoint.
Delete the consumer's IP address resource.
Recreate the producer's subnet using the same name and CIDR range. Set the subnet purpose to PRIVATE.
Recreate the resources needed to provide the service in the producer's subnet.
The consumer validates that they can access the service through the peering connection.