DOC-1652 change from VPC peering to PSC (#408)

micheleRP · web-flow · commit 79d6d11415c2 · 2025-09-05T15:14:23.000-06:00
* DOC-1652 change from VPC peering to PSC

* coderabbit suggestions

* separate links for byoc/dedicated

* doc review feedback

* doc review feedback

* Add similar sections for AWS

* add fixes for other peering issues
diff --git a/modules/networking/pages/aws-privatelink.adoc b/modules/networking/pages/aws-privatelink.adoc
@@ -135,7 +135,12 @@ rpk cloud byoc aws apply --redpanda-id=$CLUSTER_ID
 
 == Enable PrivateLink endpoint service for existing clusters
 
-CAUTION: As soon as PrivateLink is available on your VPC, all communication on existing Redpanda bootstrap server and broker ports is interrupted due to the change on the private DNS resolution. Make sure all applications running in your VPC are ready to start using the corresponding PrivateLink ports.
+[CAUTION]
+====
+Enabling PrivateLink on your VPC interrupts all communication on existing Redpanda bootstrap server and broker ports due to the change of private DNS resolution.
+
+To avoid disruption, consider using a staged approach to enable PrivateLink. See: xref:networking:byoc/aws/vpc-peering-aws.adoc#switch-from-vpc-peering-to-privatelink[Switch from VPC peering to PrivateLink].
+====
 
 . In the Redpanda Cloud UI, go to the cluster overview and copy the cluster ID from the **Details** section.
 +
@@ -342,5 +347,5 @@ include::networking:partial$private-links-test-connection.adoc[]
 include::shared:partial$suggested-reading.adoc[]
 
 * link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API Overview]
-* xref:networking:byoc/aws/vpc-peering-aws.adoc[]
-* xref:networking:dedicated/vpc-peering.adoc[]
+* xref:networking:byoc/aws/vpc-peering-aws.adoc[Add a BYOC VPC Peering Connection]
+* xref:networking:dedicated/vpc-peering.adoc[Add a Dedicated VPC Peering Connection]
diff --git a/modules/networking/pages/azure-private-link.adoc b/modules/networking/pages/azure-private-link.adoc
@@ -156,7 +156,7 @@ rpk cloud byoc azure apply --redpanda-id=$CLUSTER_ID --subscription-id=$REDPANDA
 
 === Enable Private Link service for existing clusters
 
-CAUTION: As soon as Private Link is available on your virtual network, all communication on existing Redpanda bootstrap server and broker ports is interrupted due to the change on the private DNS resolution. Make sure all applications running in your virtual network are ready to start using the corresponding Private Link ports.
+CAUTION: Enabling Private Link on your VNet interrupts all communication on existing Redpanda bootstrap server and broker ports due to the change of private DNS resolution. Make sure all applications running in your virtual network are ready to start using the corresponding Private Link ports.
 
 . In the Redpanda Cloud UI, go to the cluster overview and copy the cluster ID from the **Details** section.
 +
diff --git a/modules/networking/pages/byoc/aws/vpc-peering-aws.adoc b/modules/networking/pages/byoc/aws/vpc-peering-aws.adoc
@@ -2,6 +2,8 @@
 :description: Use the Redpanda UI and AWS CLI to create a VPC peering connection for a BYOC cluster.
 :page-aliases: deploy:deployment-option/cloud/vpc-peering-aws.adoc
 
+A VPC peering connection is a networking connection between two VPCs. This connection allows the VPCs to communicate with each other as if they were within the same network. A route table routes traffic between the two VPCs using private IPv4 addresses.
+
 To start sending data to the Redpanda cluster, you must configure the VPC network connection by connecting your Redpanda VPC to your existing AWS VPC.
 
 == Prerequisites
@@ -56,3 +58,12 @@ There are two ways to test your connection:
 
 * Return to your cluster overview, and follow the directions in the *How to connect* panel.
 * Use the AWS https://docs.aws.amazon.com/vpc/latest/reachability/what-is-reachability-analyzer.html[Reachability Analyzer^]. Select your VM instance and a Redpanda instance as the source and destination, and test the connection between them.
+
+== Switch from VPC peering to PrivateLink
+
+VPC peering and PrivateLink use the same DNS hostnames (connection URLs) to connect to the Redpanda cluster. When you configure the PrivateLink DNS, those hostnames resolve to PrivateLink endpoints, which can interrupt existing VPC peering-based connections if clients aren't ready.
+
+To enable PrivateLink without disrupting VPC peering connections, do a controlled DNS switchover:
+
+. Enable PrivateLink on the existing cluster and configure the PrivateLink connection to Redpanda Cloud, but *do not modify VPC DNS attributes yet*. See: xref:networking:aws-privatelink.adoc#enable-privatelink-endpoint-service-for-existing-clusters[Enable PrivateLink on an existing cluster].
+. During a planned window, modify the VPC DNS attributes to switch the shared hostnames over to PrivateLink.
diff --git a/modules/networking/pages/byoc/gcp/vpc-peering-gcp.adoc b/modules/networking/pages/byoc/gcp/vpc-peering-gcp.adoc
@@ -2,6 +2,8 @@
 :description: Use the Redpanda and GCP UIs to create a VPC peering connection for a BYOC cluster.
 :page-aliases: deploy:deployment-option/cloud/vpc-peering-gcp.adoc
 
+A VPC peering connection is a networking connection between two VPCs. This connection allows the VPCs to communicate with each other as if they were within the same network. A route table routes traffic between the two VPCs using private IPv4 addresses.
+
 To start sending data to the Redpanda cluster, you must configure the VPC network connection by connecting your Redpanda VPC to your existing GCP VPC.
 
 == Prerequisites
@@ -39,3 +41,12 @@ To quickly test this quickly in GCP:
 * Create a virtual machine on your GCP network that has a firewall rule allowing ingress traffic from your IP (for example, `<your-ip>/32`)
 * Activate the Cloud Shell in your project, install `rpk` in the Cloud Shell, and run `rpk cluster info`.
 * If there is output from Redpanda, your connection is successful.
+
+== Switch from VPC peering to Private Service Connect
+
+VPC peering and Private Service Connect use the same DNS hostnames (connection URLs) to connect to the Redpanda cluster. When you configure the Private Service Connect DNS, those hostnames resolve to Private Service Connect endpoints, which can interrupt existing VPC peering-based connections if clients aren't ready.
+
+To enable Private Service Connect without disrupting VPC peering connections, do a controlled DNS switchover:
+
+. Enable Private Service Connect on the existing cluster and deploy consumer-side resources, but *do not create private DNS yet*. See: xref:networking:gcp-private-service-connect.adoc#enable-private-service-connect-on-an-existing-byoc-or-byovpc-cluster[Enable Private Service Connect on an existing cluster].
+. During a planned window, create the private DNS zone and records in your VPC to switch the shared hostnames over to Private Service Connect.
diff --git a/modules/networking/pages/dedicated/aws/vpc-peering.adoc b/modules/networking/pages/dedicated/aws/vpc-peering.adoc
@@ -22,10 +22,10 @@ To create a peering connection between your VPC and Redpanda's VPC:
 
 . In the Redpanda Cloud UI, go to the *Overview* page for your cluster.
 . In the Details section, click the name of the Redpanda network.
-. On the *Network* page, click *+ Add peering connection*.
-. In *Connection name*, enter a name. For example, the name might refer to the VPC ID of the VPC you created in AWS.
-. In *AWS account number*, enter the account number associated with the VPC you want to connect to.
-. In *AWS VPC ID*, enter the VPC ID by copying it from the AWS VPC Console.
+. On the Networks page, click *VPC peering walkthrough*.
+. For *Connection name*, enter a name. For example, the name might refer to the VPC ID of the VPC you created in AWS.
+. For *AWS account number*, enter the account number associated with the VPC you want to connect to.
+. For *AWS VPC ID*, enter the VPC ID by copying it from the AWS VPC Console.
 . Click *Create peering connection*.
 
 == Accept the peering connection request
@@ -42,3 +42,14 @@ The status should say "Pending acceptance".
 . Open the *Actions* menu and select *Accept Request*.
 . In the confirmation dialog box, verify that the requester owner ID corresponds to the Redpanda account, and select *Yes, Accept*.
 . In the next confirmation dialog box, select *Modify my route tables now*.
++
+Follow the steps in the dialog box to add routes to your route tables in the AWS console. This enables traffic to flow between the two VPCs.
+
+== Switch from VPC peering to PrivateLink
+
+VPC peering and PrivateLink use the same DNS hostnames (connection URLs) to connect to the Redpanda cluster. When you configure the PrivateLink DNS, those hostnames resolve to PrivateLink endpoints, which can interrupt existing VPC peering-based connections if clients aren't ready.
+
+To enable PrivateLink without disrupting VPC peering connections, do a controlled DNS switchover:
+
+. Enable PrivateLink on the existing cluster and configure the PrivateLink connection to Redpanda Cloud, but *do not modify VPC DNS attributes yet*. See: xref:networking:aws-privatelink.adoc#enable-privatelink-endpoint-service-for-existing-clusters[Enable PrivateLink on an existing cluster].
+. During a planned window, modify the VPC DNS attributes to switch the shared hostnames over to PrivateLink. 
diff --git a/modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc b/modules/networking/pages/dedicated/gcp/configure-psc-in-api.adoc
@@ -97,7 +97,12 @@ curl -vv -X POST \
 
 == Enable Private Service Connect on an existing cluster
 
-CAUTION: As soon as Private Service Connect is available on your VPC, all communication on existing Redpanda bootstrap server and broker ports is interrupted due to the change on the private DNS resolution. Make sure all applications running in your VPC are ready to start using the corresponding Private Service Connect ports.
+[CAUTION]
+====
+Enabling Private Service Connect on your VPC interrupts all communication on existing Redpanda bootstrap server and broker ports due to the change of private DNS resolution.
+
+To avoid disruption, consider using a staged approach. See: xref:networking:dedicated/gcp/vpc-peering-gcp.adoc#switch-from-vpc-peering-to-private-service-connect[Switch from VPC peering to Private Service Connect].
+====
 
 . In the Redpanda Cloud UI, go to the cluster overview and copy the cluster ID from the **Details** section.
 +
diff --git a/modules/networking/pages/dedicated/gcp/vpc-peering-gcp.adoc b/modules/networking/pages/dedicated/gcp/vpc-peering-gcp.adoc
@@ -17,30 +17,31 @@ TIP: Consider adding `rp` at the beginning of the VPC name to indicate that this
 
 == Create a peering connection
 
-To create a peering connection between your VPC and Redpanda's VPC:
+A peering becomes active after both Redpanda and GCP create a peering that targets the other project/network.
 
 . In the Redpanda Cloud UI, go to the *Overview* page for your cluster.
 . In the Details section, click the name of the Redpanda network.
-. On the *Network* page, click *+ Add peering connection*.
-. In *Connection name*, enter a name for the connection.
+. On the Networks page for your cluster, click *VPC peering walkthrough*.
+. For *Connection name*, enter a name for the connection.
 +
 For example, the name might refer to the VPC ID of the VPC you created in GCP.
 
-. In *GCP account number*, enter the account number associated with the VPC you want to connect to.
-. In *GCP VPC ID*, enter the VPC ID.
+. For *GCP project ID*, enter the ID of the project that contains the VPC network you want to connect to.
+. For *VPC network name*, enter the name of the VPC network.
 . Click *Create peering connection*.
 
-== Accept the peering connection request
+== Create the reciprocal peering connection
 
-Redpanda sends a peering request to the GCP. You must accept the request from the Redpanda VPC to set up the peering connection.
+. In the Google Cloud console, go to VPC network peering - Create peering connection.
+. For *Name*, enter a name for the connection (for example, `rp-peering`).
+. Select your VPC network, project, and VPC network name.
+. Click *Create*.
 
-. Log in to GCP.
-. Select the region where the VPC was created.
-. From the navigation menu, select *Peering Connections*.
-. Under *Requester VPC*, select the VPC you created for use with Redpanda.
-+
-The status should say "Pending acceptance".
+== Switch from VPC peering to Private Service Connect
+
+VPC peering and Private Service Connect use the same DNS hostnames (connection URLs) to connect to the Redpanda cluster. When you configure the Private Service Connect DNS, those hostnames resolve to Private Service Connect endpoints, which can interrupt existing VPC peering-based connections if clients aren't ready.
+
+To enable Private Service Connect without disrupting VPC peering connections, do a controlled DNS switchover:
 
-. Open the *Actions* menu and select *Accept Request*.
-. In the confirmation dialog box, verify that the requester owner ID corresponds to the Redpanda account, and select *Yes, Accept*.
-. In the next confirmation dialog box, select *Modify my route tables now*.
+. Enable Private Service Connect on the existing cluster and deploy consumer-side resources, but *do not create private DNS yet*. See: xref:networking:dedicated/gcp/configure-psc-in-api.adoc#enable-private-service-connect-on-an-existing-cluster[Enable Private Service Connect on an existing cluster].
+. During a planned window, create the private DNS zone and records in your VPC to switch the shared hostnames over to Private Service Connect.
diff --git a/modules/networking/pages/gcp-private-service-connect.adoc b/modules/networking/pages/gcp-private-service-connect.adoc
@@ -191,7 +191,12 @@ Replace the following placeholders for the request body. Variables with a `byovp
 
 == Enable Private Service Connect on an existing BYOC or BYOVPC cluster
 
-CAUTION: As soon as Private Service Connect is available on your VPC, all communication on existing Redpanda bootstrap server and  broker ports is interrupted due to the change on the private DNS resolution. Make sure all applications running in your VPC are ready to start using the corresponding Private Service Connect ports.
+[CAUTION]
+====
+Enabling Private Service Connect on your VPC interrupts all communication on existing Redpanda bootstrap server and broker ports due to the change of private DNS resolution.
+
+To avoid disruption, consider using a staged approach to enable Private Service Connect. See: xref:networking:byoc/gcp/vpc-peering-gcp.adoc#switch-from-vpc-peering-to-private-service-connect[Switch from VPC peering to Private Service Connect].
+====
 
 . In the Redpanda Cloud UI, go to the cluster overview and copy the cluster ID from the **Details** section.
 +
@@ -296,5 +301,4 @@ curl -v -X PATCH \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $AUTH_TOKEN" \
 -d "$CLUSTER_PATCH_BODY" $PUBLIC_API_ENDPOINT/v1/clusters/$CLUSTER_ID
-----
-
+----
diff --git a/modules/networking/partials/vnet-peering.adoc b/modules/networking/partials/vnet-peering.adoc
@@ -27,7 +27,7 @@ To create a peering connection between your Azure VNet and Redpanda VPC:
 
 . In the Redpanda Cloud UI, go to the *Overview* page for your cluster.
 . In the Details section, click the name of the *Redpanda network*.
-. On the *Network* page for your cluster, click *+ Add peering connection*.
+. On the Networks page for your cluster, click *VPC peering walkthrough*.
 . For *Connection name*, enter a name. For example, the name could refer to your Azure VNet ID.
 . For *Azure account number*, enter the account number associated with the VNet you want to connect to.
 . For *Azure VNet ID*, enter the VNet ID.

Original file line number	Diff line number	Diff line change
`@@ -156,7 +156,7 @@ rpk cloud byoc azure apply --redpanda-id=$CLUSTER_ID --subscription-id=$REDPANDA`
`156`	`156`
`157`	`157`	`=== Enable Private Link service for existing clusters`
`158`	`158`
`159`		`-CAUTION: As soon as Private Link is available on your virtual network, all communication on existing Redpanda bootstrap server and broker ports is interrupted due to the change on the private DNS resolution. Make sure all applications running in your virtual network are ready to start using the corresponding Private Link ports.`
	`159`	`+CAUTION: Enabling Private Link on your VNet interrupts all communication on existing Redpanda bootstrap server and broker ports due to the change of private DNS resolution. Make sure all applications running in your virtual network are ready to start using the corresponding Private Link ports.`
`160`	`160`
`161`	`161`	`. In the Redpanda Cloud UI, go to the cluster overview and copy the cluster ID from the Details section.`
`162`	`162`	`+`