From a2e9a37357978274f84e1b88ff57d16d41be5772 Mon Sep 17 00:00:00 2001 From: Panagiotis Panagiotopoulos Date: Tue, 23 Jun 2026 13:21:18 +0300 Subject: [PATCH 1/5] DOC-1613: Document BYOC GCP centralized egress with VPC Peering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follows the same Jira ticket as the AWS equivalent (PR #587 — the PR description notes "GCP and Azure paths are planned and will be tracked in separate DOC tickets", so you may want to swap in the actual GCP ticket number once it's created). --- modules/ROOT/nav.adoc | 2 + .../byoc/gcp/create-byoc-cluster-gcp.adoc | 5 + .../get-started/pages/whats-new-cloud.adoc | 4 + .../pages/byoc/gcp/gcp-hub-egress.adoc | 504 ++++++++++++++++++ .../pages/byoc/gcp/nat-free-egress.adoc | 208 ++++++++ 5 files changed, 723 insertions(+) create mode 100644 modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc create mode 100644 modules/networking/pages/byoc/gcp/nat-free-egress.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index fe305c72c..413b812c8 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -488,6 +488,8 @@ **** xref:networking:configure-private-service-connect-in-cloud-ui.adoc[Configure Private Service Connect in the Cloud Console] **** xref:networking:gcp-private-service-connect.adoc[Configure Private Service Connect with the Cloud API] **** xref:networking:byoc/gcp/enable-global-access.adoc[Enable Global Access] +**** xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress] +**** xref:networking:byoc/gcp/gcp-hub-egress.adoc[Create a GCP Hub for Centralized Egress] ** xref:networking:dedicated/index.adoc[Dedicated] *** xref:networking:dedicated/aws/index.adoc[AWS] **** xref:networking:dedicated/aws/vpc-peering.adoc[Add a Peering Connection] diff --git a/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc b/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc index cf7f425f3..1dbe54d93 100644 --- a/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc +++ b/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc @@ -45,6 +45,11 @@ Optionally, click *Advanced settings* to specify up to five key-value custom GCP ** Clusters with private networking include a setting for API Gateway network access. Public access exposes endpoints for Redpanda Console, the Data Plane API, but they remain protected by your authentication and authorization controls. Private access restricts endpoint access to your VPC only. + NOTE: After the cluster is created, you can change the API Gateway access on the Dataplane settings page. If you change from public to private access, users without VPN access to the Redpanda VPC will lose access to these services. ++ +[TIP] +==== +To route all cluster egress through your own GCP hub VPC and NAT VM instead of a per-cluster Cloud NAT, enter the *Hub VPC name* and *Hub project ID* on this page. These fields are only available on clusters with a private connection type, and are only visible if centralized egress is enabled for your organization. This option is in beta. See xref:networking:byoc/gcp/nat-free-egress.adoc[]. +==== . Click *Next*. . On the Deploy page, follow the steps to log in to Redpanda Cloud and deploy the agent. + diff --git a/modules/get-started/pages/whats-new-cloud.adoc b/modules/get-started/pages/whats-new-cloud.adoc index ccedee6ac..8572335a4 100644 --- a/modules/get-started/pages/whats-new-cloud.adoc +++ b/modules/get-started/pages/whats-new-cloud.adoc @@ -8,6 +8,10 @@ This page lists new features added to Redpanda Cloud. == June 2026 +=== Centralized egress for BYOC on GCP (beta) + +You can route all GCP BYOC cluster egress through your own GCP hub VPC and NAT VM instead of a per-cluster Cloud NAT, so outbound traffic exits through your centralized inspection point. This is useful for regulated environments that require a single, predictable public IP for outbound allowlisting or that prohibit per-cluster Cloud NAT. Centralized egress is in beta and is enabled per organization. Contact your account team for access. See xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering]. + === GCP Lakehouse catalog for Iceberg topics BYOC clusters on GCP can now use GCP Lakehouse as an Iceberg REST catalog. See xref:manage:iceberg/iceberg-topics-gcp-biglake.adoc[]. diff --git a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc new file mode 100644 index 000000000..5ee46ac23 --- /dev/null +++ b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc @@ -0,0 +1,504 @@ += Create a GCP Hub for Centralized Egress +:description: Provision a hub VPC and NAT VM so one or more Redpanda BYOC clusters can route their internet egress through a single, predictable public IP. +:page-beta: true +:page-topic-type: how-to +:personas: platform_admin +:learning-objective-1: Provision a hub VPC with a NAT VM on GCP +:learning-objective-2: Configure routes and VPC Network Peering to export the default route to Redpanda spoke VPCs +:learning-objective-3: Collect the hub VPC name and project ID needed for BYOC cluster configuration + +Use this guide to provision the customer-side infrastructure required for centralized egress on a Redpanda Bring Your Own Cloud (BYOC) cluster on GCP. After completing this procedure, you have a hub VPC with a NAT VM, exportable routes via VPC Network Peering, and the values needed to configure your BYOC network. You can then follow xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering] to enable centralized egress at cluster creation. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== What this sets up + +A hub VPC with a NAT VM provides centralized internet egress for one or more Redpanda spoke VPCs. All outbound traffic from clusters is routed through the hub and exits from a single, predictable public IP. + +---- +Redpanda BYOC VPC ──► VPC Network Peering ──► Hub VPC ──► NAT VM ──► Internet + (import_custom_routes) (export_custom_routes) +---- + +Traffic path: + +. Redpanda nodes send `0.0.0.0/0` traffic, which follows the imported peering route pointing to the NAT VM's internal IP. +. The NAT VM in the hub VPC performs IP masquerade and forwards packets through its public IP. +. The NAT VM uses a separate tagged route (`nat-direct`) to reach the internet directly, preventing a routing loop. + +[NOTE] +==== +Local static routes in GCP always beat imported VPC peering routes, regardless of priority numbers. The Redpanda spoke VPC must not have a local `0.0.0.0/0` route — if one exists, it will silently win over the imported route and no traffic will flow through the hub NAT. +==== + +[#automated-alternative] +== Automated alternative + +If you prefer to provision this infrastructure with Terraform, the configuration used to produce the setup in this guide is published in the Redpanda Cloud Examples repository: link:https://github.com/redpanda-data/cloud-examples/tree/main/gcp-hub-egress[gcp-hub-egress^] + +The rest of this guide covers the equivalent steps using the GCP Console or gcloud CLI. + +== Prerequisites + +* `gcloud` CLI configured with credentials for the hub project. +* Permissions: Compute Network Admin and Compute Instance Admin in the hub project. +* If the hub and Redpanda cluster are in different GCP projects, the principal also needs `roles/compute.networkPeer` in the Redpanda project. +* The hub subnet CIDR must not overlap with the Redpanda cluster VPC CIDR. VPC peering is rejected when CIDRs overlap. + +[WARNING] +==== +Hub and spoke VPC CIDRs must not overlap. GCP rejects VPC peering when CIDRs conflict. Even when CIDRs do not overlap but a spoke has a local `0.0.0.0/0` route, that local route silently wins over the imported peering route. Plan your CIDRs before you start. +==== + +== Default values + +The procedure uses the values in the following table. Replace any value that does not match your environment. + +[cols="2,2,3"] +|=== +| Parameter | Default | Notes + +| Hub project | `my-hub-project` | Replace with your GCP project ID +| Hub VPC name | `hub-vpc` | — +| Hub subnet name | `hub-subnet` | — +| Hub subnet CIDR | `100.64.0.0/20` | CGNAT range, unlikely to conflict with typical workload CIDRs +| Region | `us-central1` | Replace with your target region +| Zone | `us-central1-a` | Replace with any zone in your region +| NAT machine type | `e2-micro` | Size up if egress bandwidth becomes a bottleneck +| Redpanda spoke VPC | `redpanda-` | Visible in the Redpanda Cloud console +| Redpanda project | `my-redpanda-project` | GCP project of your BYOC cluster +|=== + +== Set environment variables + +Set these variables once and reuse them throughout the guide. + +[,bash] +---- +HUB_PROJECT="my-hub-project" +REGION="us-central1" +ZONE="us-central1-a" +VPC_NAME="hub-vpc" +SUBNET_NAME="hub-subnet" +SUBNET_CIDR="100.64.0.0/20" + +# Fill in after the Redpanda cluster network is provisioned +SPOKE_VPC="redpanda-" +SPOKE_PROJECT="my-redpanda-project" +PEERING_NAME="hub-to-redpanda-cluster-a" +---- + +== Create the hub VPC + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > VPC Networks > Create VPC Network*. +. Set the name to `hub-vpc`. +. Set *Subnet creation mode* to *Custom*. +. Click *Create*. Add the subnet in the next step. + +CLI:: ++ +[,bash] +---- +gcloud compute networks create $VPC_NAME \ + --project=$HUB_PROJECT \ + --subnet-mode=custom \ + --bgp-routing-mode=regional + +echo "VPC created: $VPC_NAME" +---- +====== + +== Create the hub subnet + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > Subnets > Add Subnet*. +. Set the network to `hub-vpc`. +. Set the name to `hub-subnet`, the region to `us-central1`, and the IPv4 range to `100.64.0.0/20`. +. Click *Add*. + +CLI:: ++ +[,bash] +---- +gcloud compute networks subnets create $SUBNET_NAME \ + --project=$HUB_PROJECT \ + --network=$VPC_NAME \ + --region=$REGION \ + --range=$SUBNET_CIDR + +echo "Subnet created: $SUBNET_NAME ($SUBNET_CIDR)" +---- +====== + +== Reserve a static public IP + +This public IP becomes the single egress address for all Redpanda cluster traffic. + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > IP Addresses > Reserve External Static Address*. +. Set the name to `hub-nat-ip`, the network service tier to *Premium*, the IP version to *IPv4*, the type to *Regional*, and the region to `us-central1`. +. Click *Reserve*. + +CLI:: ++ +[,bash] +---- +gcloud compute addresses create hub-nat-ip \ + --project=$HUB_PROJECT \ + --region=$REGION + +NAT_PUBLIC_IP=$(gcloud compute addresses describe hub-nat-ip \ + --project=$HUB_PROJECT \ + --region=$REGION \ + --format='get(address)') + +echo "NAT public IP: $NAT_PUBLIC_IP" +---- +====== + +== Reserve a static internal IP + +The exportable peering route points to the NAT VM's internal IP. A reserved static internal IP ensures the route stays valid across MIG instance replacements. + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > IP Addresses > Reserve Internal Static Address*. +. Set the name to `hub-nat-internal-ip`, the network to `hub-vpc`, the subnetwork to `hub-subnet`, the region to `us-central1`, and the static IP address to *Assign automatically*. +. Click *Reserve*. +. Note the allocated IP address — you will need it in the following steps. + +CLI:: ++ +[,bash] +---- +gcloud compute addresses create hub-nat-internal-ip \ + --project=$HUB_PROJECT \ + --region=$REGION \ + --subnet=$SUBNET_NAME + +NAT_INTERNAL_IP=$(gcloud compute addresses describe hub-nat-internal-ip \ + --project=$HUB_PROJECT \ + --region=$REGION \ + --format='get(address)') + +echo "NAT internal IP: $NAT_INTERNAL_IP" +---- +====== + +== Create the tagged route: NAT VM to internet + +This route lets the NAT VM reach the internet directly via the default internet gateway. The `nat-direct` network tag restricts it to the NAT VM only, preventing other VMs in the hub VPC from using it. + +[NOTE] +==== +Priority `100` ensures the NAT VM uses this route rather than the untagged `0.0.0.0/0 → NAT VM` route created in the next step, which would cause a routing loop. +==== + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > Routes > Create Route*. +. Set the name to `hub-nat-to-internet`, the network to `hub-vpc`, the destination IP range to `0.0.0.0/0`, the priority to `100`, and the next hop to *Default internet gateway*. +. Under *Additional fields*, add the instance tag `nat-direct`. +. Click *Create*. + +CLI:: ++ +[,bash] +---- +gcloud compute routes create hub-nat-to-internet \ + --project=$HUB_PROJECT \ + --network=$VPC_NAME \ + --destination-range=0.0.0.0/0 \ + --next-hop-gateway=default-internet-gateway \ + --tags=nat-direct \ + --priority=100 + +echo "Tagged route created: hub-nat-to-internet (priority 100, tag: nat-direct)" +---- +====== + +== Create the untagged route: spoke traffic to NAT VM + +GCP exports routes with `next_hop_ip` via VPC peering. Routes with `next_hop_gateway = default-internet-gateway` are not exportable. This route is what the Redpanda spoke VPC imports to direct all outbound traffic through the hub. + +[NOTE] +==== +Priority `900` ensures the imported copy in the Redpanda spoke VPC beats the spoke's own system default route (priority `1000`, if present). +==== + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > Routes > Create Route*. +. Set the name to `hub-spoke-to-nat`, the network to `hub-vpc`, the destination IP range to `0.0.0.0/0`, the priority to `900`, and the next hop to *Specify an IP address* with the internal IP reserved in the previous step. +. Leave *Instance tags* empty. +. Click *Create*. + +CLI:: ++ +[,bash] +---- +gcloud compute routes create hub-spoke-to-nat \ + --project=$HUB_PROJECT \ + --network=$VPC_NAME \ + --destination-range=0.0.0.0/0 \ + --next-hop-address=$NAT_INTERNAL_IP \ + --priority=900 + +echo "Untagged route created: hub-spoke-to-nat -> $NAT_INTERNAL_IP (priority 900)" +---- +====== + +== Create a firewall rule + +Allow traffic from Redpanda spoke VPCs to reach the NAT VM for forwarding. The `nat-direct` target tag restricts this rule to the NAT VM only. + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > Firewall > Create Firewall Rule*. +. Set the name to `hub-allow-nat-forward`, the network to `hub-vpc`, the direction to *Ingress*, and the action to *Allow*. +. Set *Targets* to *Specified target tags* with the value `nat-direct`. +. Set *Source filter* to *IPv4 ranges* with the value `10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10`. +. Set *Protocols and ports* to *Allow all*. +. Click *Create*. + +CLI:: ++ +[,bash] +---- +gcloud compute firewall-rules create hub-allow-nat-forward \ + --project=$HUB_PROJECT \ + --network=$VPC_NAME \ + --direction=INGRESS \ + --action=ALLOW \ + --rules=tcp,udp,icmp \ + --source-ranges=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10 \ + --target-tags=nat-direct + +echo "Firewall rule created: hub-allow-nat-forward" +---- +====== + +== Create the NAT VM instance template + +The NAT VM runs IP forwarding and iptables masquerade. It carries the `nat-direct` network tag so it picks up the direct-to-internet route created earlier. + +[NOTE] +==== +The Console path for creating an instance template is complex. The CLI is recommended for this step. +==== + +[tabs] +====== +Console:: ++ +. Go to *Compute Engine > Instance Templates > Create Instance Template*. +. Set the name to `hub-nat-template`. +. Set the machine configuration to *E2 > e2-micro*. +. Set the boot disk to *Debian GNU/Linux 13 (bookworm)*, *pd-balanced*, *10 GB*. +. Under *Advanced options > Networking*: +.. Add the network tag `nat-direct`. +.. Enable *IP forwarding*. +.. Set the network interface to `hub-vpc` / `hub-subnet`. +.. Set the external IPv4 address to `hub-nat-ip` (reserved earlier). +.. Set the internal IPv4 address to `hub-nat-internal-ip` (reserved earlier). +. Under *Advanced options > Management > Automation > Startup script*, paste the following script: ++ +[,bash] +---- +#!/bin/bash +set -e +sysctl -w net.ipv4.ip_forward=1 +echo 'net.ipv4.ip_forward = 1' > /etc/sysctl.d/99-ip-forward.conf +EXT_IF=$(ip route get 8.8.8.8 | awk '{for(i=1;i<=NF;i++) if($i=="dev") print $(i+1)}' | head -1) +iptables -t nat -A POSTROUTING -o "$EXT_IF" -j MASQUERADE +iptables -A FORWARD -i "$EXT_IF" -m state --state RELATED,ESTABLISHED -j ACCEPT +iptables -A FORWARD -j ACCEPT +apt-get update -qq && apt-get install -y -qq iptables-persistent +netfilter-persistent save +---- +. Click *Create*. + +CLI:: ++ +Save the startup script to a temporary file first to avoid quoting issues: ++ +[,bash] +---- +cat > /tmp/nat-startup.sh <<'SCRIPT' +#!/bin/bash +set -e +sysctl -w net.ipv4.ip_forward=1 +echo 'net.ipv4.ip_forward = 1' > /etc/sysctl.d/99-ip-forward.conf +EXT_IF=$(ip route get 8.8.8.8 | awk '{for(i=1;i<=NF;i++) if($i=="dev") print $(i+1)}' | head -1) +iptables -t nat -A POSTROUTING -o "$EXT_IF" -j MASQUERADE +iptables -A FORWARD -i "$EXT_IF" -m state --state RELATED,ESTABLISHED -j ACCEPT +iptables -A FORWARD -j ACCEPT +apt-get update -qq && apt-get install -y -qq iptables-persistent +netfilter-persistent save +SCRIPT + +gcloud compute instance-templates create hub-nat-template \ + --project=$HUB_PROJECT \ + --region=$REGION \ + --machine-type=e2-micro \ + --image-family=debian-13 \ + --image-project=debian-cloud \ + --boot-disk-size=10GB \ + --boot-disk-type=pd-balanced \ + --can-ip-forward \ + --tags=nat-direct \ + --network=$VPC_NAME \ + --subnet=$SUBNET_NAME \ + --private-network-ip=$NAT_INTERNAL_IP \ + --address=$NAT_PUBLIC_IP \ + --metadata-from-file=startup-script=/tmp/nat-startup.sh + +echo "Instance template created: hub-nat-template" +---- +====== + +== Create the Managed Instance Group + +A size-1 MIG ensures the NAT VM is automatically restarted if it crashes or is terminated. + +[tabs] +====== +Console:: ++ +. Go to *Compute Engine > Instance Groups > Create Instance Group*. +. Select *New managed instance group (stateful)*. +. Set the name to `hub-nat-mig`, the instance template to `hub-nat-template`, the location to *Single zone > us-central1-a*, and the number of instances to `1`. +. Click *Create*. + +CLI:: ++ +[,bash] +---- +gcloud compute instance-groups managed create hub-nat-mig \ + --project=$HUB_PROJECT \ + --zone=$ZONE \ + --template=hub-nat-template \ + --size=1 + +echo "Waiting for MIG instance to become stable..." +gcloud compute instance-groups managed wait-until hub-nat-mig \ + --project=$HUB_PROJECT \ + --zone=$ZONE \ + --stable + +echo "MIG created: hub-nat-mig" +---- +====== + +== Create VPC Network Peering (hub to Redpanda) + +Create the peering from the hub side. Redpanda creates the reciprocal peering from the spoke side during cluster provisioning. + +[NOTE] +==== +Set `--export-custom-routes` so the `0.0.0.0/0 → NAT internal IP` route is visible to the Redpanda VPC. Do not set `--import-custom-routes` — the hub does not need to import routes from the spoke. + +The peering shows as *INACTIVE* until the Redpanda cluster provisions the reciprocal peering. This is expected — proceed to create the cluster after this step. +==== + +[tabs] +====== +Console:: ++ +. Go to *VPC Network > VPC Network Peering > Create Peering Connection*. +. Set the name to `hub-to-redpanda-cluster-a` and the VPC network to `hub-vpc`. +. Under *Peered VPC network*, select *In another project* (or *In the same project* if applicable) and enter the Redpanda project ID and VPC name `redpanda-`. +. Under *Exchange custom routes*, enable *Export custom routes* and leave *Import custom routes* unchecked. +. Click *Create*. + +CLI:: ++ +[,bash] +---- +gcloud compute networks peerings create $PEERING_NAME \ + --project=$HUB_PROJECT \ + --network=$VPC_NAME \ + --peer-network=$SPOKE_VPC \ + --peer-project=$SPOKE_PROJECT \ + --export-custom-routes \ + --no-import-custom-routes + +echo "Peering created: $PEERING_NAME (hub -> $SPOKE_VPC)" +echo "Status is INACTIVE until Redpanda creates the reciprocal peering." +---- +====== + +[#collect-values] +== Collect the values to provide to Redpanda + +Record these values. Provide the hub VPC name and hub project ID when you configure centralized egress on your BYOC network. See xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering]. + +[,bash] +---- +echo "hub_vpc_name = $VPC_NAME" +echo "hub_project_id = $HUB_PROJECT" +echo "hub_subnet_name = $SUBNET_NAME" +echo "nat_internal_ip = $NAT_INTERNAL_IP" +echo "nat_public_ip = $NAT_PUBLIC_IP" +echo "peering_name = $PEERING_NAME" +---- + +All outbound internet traffic from every BYOC spoke that peers to this hub exits from the same NAT VM public IP. Use that public IP for outbound IP allowlisting on external services. + +== Plan for high availability + +The procedure in this guide deploys a single NAT VM in one zone, which is not AZ-resilient. The `e2-micro` machine type also limits egress bandwidth. For production deployments: + +* Use a larger machine type such as `e2-standard-2` or `e2-standard-4` to increase throughput. +* Consider multiple NAT VMs behind a load balancer or deploy per-zone MIGs if AZ resilience is required. +* Monitor instance health through the MIG health check and set up alerting on the MIG's `instance_count` metric. + +The <> deploys a single NAT VM. Extend it with per-zone MIGs if you need HA egress. + +== Troubleshooting + +[cols="2,2"] +|=== +| Symptom | Likely cause + +| Redpanda cluster has no outbound internet connectivity | The spoke VPC CIDR overlaps with the hub subnet CIDR. GCP rejects the peering when CIDRs overlap. Assign a unique, non-overlapping CIDR to each spoke VPC. + +| Imported `0.0.0.0/0` route is not visible in the spoke VPC | The spoke VPC has a local static `0.0.0.0/0` route that wins over the imported peering route. Local static routes always beat imported peering routes in GCP regardless of priority. Remove the local default route from the spoke VPC, or contact Redpanda Support if it is Redpanda-managed. + +| Peering is stuck in `INACTIVE` state | The reciprocal peering from the Redpanda spoke VPC has not been created yet. This is expected until `rpk byoc gcp apply` completes. If the cluster is already running, verify that `import_custom_routes = true` is set on the Redpanda-side peering. + +| Peering creation fails with a permissions error | The principal lacks `roles/compute.networkPeer` in the Redpanda project. Grant that role to the hub identity at *IAM & Admin > IAM > Grant Access* in the Redpanda project. + +| Traffic exits from an unexpected IP | The NAT VM may have been replaced and the startup script did not run correctly. SSH into the NAT VM and run `iptables -t nat -L POSTROUTING` to verify the MASQUERADE rule and `sysctl net.ipv4.ip_forward` to verify IP forwarding is enabled. + +| NAT VM is not forwarding traffic | IP forwarding is not enabled on the instance template (`--can-ip-forward`), or the iptables MASQUERADE rule was not applied. Recreate the instance template with IP forwarding enabled and check the startup script output in the GCP serial console. + +| `hub-spoke-to-nat` route is not exported to the spoke | The route uses `next_hop_gateway = default-internet-gateway` instead of `next_hop_ip`. GCP exports only routes with `next_hop_ip` or `next_hop_instance` via peering. Verify the route in *VPC Network > Routes* shows a next-hop IP address, not the internet gateway. +|=== + +== Next steps + +* xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering] +* xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc[Create a BYOC Cluster on GCP] diff --git a/modules/networking/pages/byoc/gcp/nat-free-egress.adoc b/modules/networking/pages/byoc/gcp/nat-free-egress.adoc new file mode 100644 index 000000000..61709d85a --- /dev/null +++ b/modules/networking/pages/byoc/gcp/nat-free-egress.adoc @@ -0,0 +1,208 @@ += Configure Centralized Egress with GCP VPC Peering +:description: Route all BYOC cluster egress through your own GCP hub VPC instead of a per-cluster Cloud NAT, so outbound traffic exits through your centralized inspection point. +:page-beta: true +:page-topic-type: how-to +:personas: platform_admin +:learning-objective-1: Enable centralized egress on a new BYOC cluster using the Redpanda Cloud UI +:learning-objective-2: Identify the shared responsibility boundaries between Redpanda and your hub project +:learning-objective-3: Troubleshoot egress failures caused by misconfigured hub routes or VPC peering + +[IMPORTANT] +==== +This feature is in beta and is available only on GCP BYOC clusters with private networking. Availability is controlled per organization. Contact your account team to request access to centralized egress. +==== + +Centralized egress lets your BYOC cluster send all internet-bound traffic through your own GCP hub VPC instead of a Redpanda-managed Cloud NAT in the Redpanda VPC. When centralized egress is enabled, the Redpanda spoke VPC peers to your hub VPC with `import_custom_routes = true`, all outbound traffic exits through the NAT VM in your hub, and no Cloud Router or Cloud NAT is created in the spoke VPC. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +== When to use centralized egress + +Use centralized egress when: + +* Your security policy prohibits per-VPC Cloud NAT and requires all internet-bound traffic to traverse a centralized inspection point such as a firewall appliance. +* You already operate a hub-and-spoke network in GCP and want Redpanda to fit into that topology. +* You want to consolidate egress through a single, predictable public IP for outbound allowlisting on external services. +* You want to reduce Cloud NAT fees on high-throughput Redpanda workloads. + +If none of these apply, the default Cloud NAT egress used by standard BYOC clusters is simpler and requires no extra customer-managed infrastructure. + +== How it works + +Without centralized egress, the Redpanda agent creates a Cloud Router and Cloud NAT inside the Redpanda VPC. With centralized egress enabled, the agent creates the spoke VPC without a Cloud Router or Cloud NAT and establishes VPC Network Peering to your hub VPC with `import_custom_routes = true`. The hub VPC exports a `0.0.0.0/0` route pointing to the NAT VM's internal IP. The spoke VPC imports that route and uses it for all internet-bound traffic. + +The following diagram shows the connectivity model: + +---- ++-------------------------------+ +-------------------------------+ +| Redpanda VPC | | Customer Hub VPC | +| (Redpanda project) | | (Customer project) | +| | | | +| VPC Network Peering +<------->+ VPC Network Peering | +| import_custom_routes=true | | export_custom_routes=true | +| 0.0.0.0/0 -> NAT VM IP (imp) | | 0.0.0.0/0 -> NAT VM IP (exp) | +| No Cloud Router / Cloud NAT | | NAT VM (e2-micro, MIG) | +| GKE Worker Nodes | | Static public IP | ++-------------------------------+ +----------+--------------------+ + | + v + Internet + (Cloudsmith, public.ecr.aws, + NTP, Helm) +---- + +=== Outbound traffic flow + +. A GKE node in a Redpanda subnet sends a packet destined for the internet. +. The spoke VPC has no local `0.0.0.0/0` route, so the imported peering route (`0.0.0.0/0` → NAT VM internal IP) applies. +. The packet crosses the VPC peering to the hub VPC and arrives at the NAT VM. +. The NAT VM performs IP masquerade and forwards the packet through its static public IP. + +=== Return traffic flow + +. The internet response arrives at the public IP on the NAT VM in the hub VPC. +. The NAT VM forwards it back to the originating node via the VPC peering connection. +. The packet arrives at the originating GKE node. + +[#prerequisites] +== Prerequisites + +Before you configure centralized egress, confirm all of the following: + +* Centralized egress is enabled on your Redpanda Cloud organization. Contact your account team to request access. +* Your BYOC cluster uses private networking (connection type *Private*). Centralized egress is not available on clusters with a public connection type. +* You have provisioned a hub VPC in the same GCP region as the planned Redpanda BYOC cluster. See xref:networking:byoc/gcp/gcp-hub-egress.adoc[Create a GCP Hub for Centralized Egress] if you need to provision a hub. +* The hub subnet CIDR and the planned Redpanda spoke VPC CIDR do not overlap. ++ +[WARNING] +==== +GCP rejects VPC peering when CIDRs overlap. Even when peering succeeds, a local static `0.0.0.0/0` route in the spoke VPC silently wins over the imported peering route. The Redpanda provisioner does not create a local default route when centralized egress is enabled, but verify that no pre-existing local default route exists in the spoke before provisioning. + +Use a non-overlapping range for your hub subnet. The `100.64.0.0/20` CGNAT range is a safe default because it rarely conflicts with typical RFC 1918 workload CIDRs. +==== +* You know the hub VPC name and the hub GCP project ID. These are collected at the end of xref:networking:byoc/gcp/gcp-hub-egress.adoc#collect-values[Create a GCP Hub for Centralized Egress]. + +== Shared responsibility model + +[cols="2,1"] +|=== +| Component | Owner + +| Redpanda spoke VPC, subnets, and GKE cluster | Redpanda +| Spoke VPC peering with `import_custom_routes = true` | Redpanda +| No Cloud Router or Cloud NAT in the spoke VPC | Redpanda +| Hub VPC and hub subnet | Customer +| Hub VPC peering with `export_custom_routes = true` | Customer +| Untagged route `0.0.0.0/0` → NAT VM internal IP | Customer +| NAT VM instance and Managed Instance Group | Customer +| Static public IP for NAT | Customer +| Firewall rules allowing spoke CIDR traffic to reach the NAT VM | Customer +| Egress path availability and HA | Customer +|=== + +Redpanda does not manage the availability of the egress path. Size the NAT VM appropriately for your expected egress throughput. See xref:networking:byoc/gcp/gcp-hub-egress.adoc[Create a GCP Hub for Centralized Egress] for sizing guidance. + +== Limitations + +* Centralized egress is set at network creation. The hub VPC name and project fields are immutable after the network is created. +* All clusters that peer to the same hub share a single public egress IP and the same NAT VM throughput capacity. + +== Configure egress at network creation + +Centralized egress is set at network creation. You cannot change it on an existing network. Complete all hub-side setup before you start the cluster creation flow. See xref:networking:byoc/gcp/gcp-hub-egress.adoc[Create a GCP Hub for Centralized Egress]. + +[IMPORTANT] +==== +To switch back to Cloud NAT egress, create a new network and a new cluster on it, then migrate your data. +==== + +To enable centralized egress, use the Redpanda Cloud UI: + +. Log in to https://cloud.redpanda.com[Redpanda Cloud^]. +. On the Clusters page, click *Create cluster*, then click *Create* for BYOC. +. Complete the cluster details. See xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc[Create a BYOC Cluster on GCP] for the full create flow. +. On the *Network* page, enter the *Hub VPC name* and *Hub project ID* using the values you collected in xref:networking:byoc/gcp/gcp-hub-egress.adoc#collect-values[Collect the values to provide to Redpanda]. These fields are only visible if centralized egress is enabled for your organization. +. Click *Next* and complete the remaining steps. + +[NOTE] +==== +After you click *Create*, the Redpanda provisioner creates the spoke VPC without a Cloud Router or Cloud NAT, and establishes VPC Network Peering to the hub VPC with `import_custom_routes = true`. The hub-side peering you created earlier becomes *ACTIVE* when the reciprocal peering completes. Run `rpk byoc gcp apply` to finish cluster provisioning. +==== + +=== What Redpanda provisions automatically + +When you run `rpk byoc gcp apply`, the Redpanda provisioner: + +. Creates the cluster VPC without a Cloud Router, Cloud NAT, or local default route. +. Creates the reciprocal VPC Network Peering from the Redpanda VPC to the hub VPC with `import_custom_routes = true`. +. The `0.0.0.0/0` → NAT VM internal IP route exported from the hub is imported, and all internet-bound traffic flows through the hub NAT VM. + +=== Verify egress IP + +After the cluster is running, confirm that traffic exits from the expected public IP: + +[,bash] +---- +# SSH into a Redpanda node and check the public egress IP +curl -s https://api.ipify.org +# Expected output: the NAT public IP you reserved in the hub setup +---- + +[#internet-endpoints] +== Internet endpoints required from your hub + +The NAT VM in your hub VPC must provide internet egress for the following endpoints. If your hub firewall enforces an allowlist, allow outbound traffic to these endpoints from the Redpanda spoke CIDR: + +[cols="1,1,2"] +|=== +| Endpoint | Protocol and port | Purpose + +| `docker.cloudsmith.io` | TCP/443 | Redpanda container images +| `public.ecr.aws` | TCP/443 | GKE public CNI and network policy agent images +| NTP servers | UDP/123 | Time sync +| `prometheus-community.github.io` and similar Helm repositories | TCP/443 | Monitoring stack Helm charts +|=== + +== DNS resolution + +Centralized egress does not affect DNS resolution. The Redpanda VPC uses GCP's internal DNS resolver, which resolves both internal and external hostnames as long as the `0.0.0.0/0` route is importable from the hub peering. No additional DNS configuration is required. + +== Adding more clusters + +To connect an additional Redpanda cluster to the same hub, create a new hub-side peering connection for each cluster using a unique peering name (for example, `hub-to-redpanda-cluster-b`) and then configure centralized egress at cluster creation. All clusters share the same NAT VM and exit from the same public IP. + +[NOTE] +==== +The NAT VM funnels all internet egress for all peered clusters through a single instance. If egress bandwidth becomes a bottleneck, recreate the instance template with a larger machine type (for example, `e2-standard-2`) and replace the MIG instance. +==== + +== Troubleshooting + +[cols="1,1"] +|=== +| Symptom | Likely cause + +| Cluster creation does not complete | The cluster cannot reach the external endpoints it needs during bootstrap. Verify that the hub-side VPC peering has `export_custom_routes = true`; the `0.0.0.0/0 → NAT VM internal IP` route exists in the hub VPC and uses `next_hop_ip` (not `next_hop_gateway`); the NAT VM is running and healthy; and the firewall rule allows spoke CIDR traffic to reach the NAT VM. Also confirm the endpoints listed in <> are reachable. + +| The spoke VPC has no `0.0.0.0/0` route after peering is established | The hub-side peering does not have `export_custom_routes = true`, or the route uses `next_hop_gateway = default-internet-gateway` instead of `next_hop_ip`. GCP only exports routes with `next_hop_ip` or `next_hop_instance` via peering. Verify the route at *VPC Network > Routes* and update the hub-side peering if needed. + +| Peering is stuck in `INACTIVE` state | Both sides of the peering must be established for it to become `ACTIVE`. The hub-side peering remains `INACTIVE` until `rpk byoc gcp apply` creates the reciprocal spoke-side peering. If the cluster is already running, verify that `import_custom_routes = true` is set on the Redpanda-side peering. + +| Spoke VPC has a local `0.0.0.0/0` route that overrides the imported route | Local static routes always beat imported VPC peering routes in GCP regardless of priority. The Redpanda provisioner does not create a local default route when centralized egress is enabled. If an unexpected local default route appears, contact Redpanda Support. + +| Peering creation fails with a permissions error | The principal creating the hub-side peering needs `roles/compute.networkAdmin` in the hub project. If the hub and spoke are in different GCP projects, the principal also needs `roles/compute.networkPeer` in the Redpanda project. + +| Traffic exits from an unexpected IP | The NAT VM may have been replaced and the startup script did not run correctly. SSH into the NAT VM and run `iptables -t nat -L POSTROUTING` to verify the MASQUERADE rule, and `sysctl net.ipv4.ip_forward` to verify IP forwarding is enabled. + +| All traffic appears from one IP | Correct — this is the centralized egress design. All peered clusters share the single public IP assigned to the NAT VM. +|=== + +== Next steps + +* xref:networking:byoc/gcp/gcp-hub-egress.adoc[Create a GCP Hub for Centralized Egress] +* xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc[Create a BYOC Cluster on GCP] +* xref:networking:byoc/gcp/vpc-peering-gcp.adoc[Add a BYOC VPC Peering Connection on GCP] (for routing client traffic, not egress) From 5fa0dd7aecd00b700381558a49f758de144af506 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 23 Jun 2026 15:01:13 -0600 Subject: [PATCH 2/5] Apply docs-team-standards review fixes to GCP centralized egress pages Remove em dashes, replace "via" with "through", remove directional references, rewrite the self-referential hub-egress intro, sentence-case the managed instance group heading, and match the AWS What's New entry format (glossterm:beta[]). Co-Authored-By: Claude Opus 4.8 (1M context) --- .../get-started/pages/whats-new-cloud.adoc | 4 +-- .../pages/byoc/gcp/gcp-hub-egress.adoc | 36 +++++++++---------- .../pages/byoc/gcp/nat-free-egress.adoc | 8 ++--- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/modules/get-started/pages/whats-new-cloud.adoc b/modules/get-started/pages/whats-new-cloud.adoc index 8572335a4..5498a4906 100644 --- a/modules/get-started/pages/whats-new-cloud.adoc +++ b/modules/get-started/pages/whats-new-cloud.adoc @@ -8,9 +8,9 @@ This page lists new features added to Redpanda Cloud. == June 2026 -=== Centralized egress for BYOC on GCP (beta) +=== Centralized egress for BYOC on GCP: beta -You can route all GCP BYOC cluster egress through your own GCP hub VPC and NAT VM instead of a per-cluster Cloud NAT, so outbound traffic exits through your centralized inspection point. This is useful for regulated environments that require a single, predictable public IP for outbound allowlisting or that prohibit per-cluster Cloud NAT. Centralized egress is in beta and is enabled per organization. Contact your account team for access. See xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering]. +You can route all GCP BYOC cluster egress through your own GCP hub VPC and NAT VM instead of a per-cluster Cloud NAT, so outbound traffic exits through your centralized inspection point. This is useful for regulated environments that require a single, predictable public IP for outbound allowlisting or that prohibit per-cluster Cloud NAT. Centralized egress is in a glossterm:beta[] release and is enabled per organization. Contact your account team for access. See xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering]. === GCP Lakehouse catalog for Iceberg topics diff --git a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc index 5ee46ac23..52fd3be43 100644 --- a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc +++ b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc @@ -7,7 +7,7 @@ :learning-objective-2: Configure routes and VPC Network Peering to export the default route to Redpanda spoke VPCs :learning-objective-3: Collect the hub VPC name and project ID needed for BYOC cluster configuration -Use this guide to provision the customer-side infrastructure required for centralized egress on a Redpanda Bring Your Own Cloud (BYOC) cluster on GCP. After completing this procedure, you have a hub VPC with a NAT VM, exportable routes via VPC Network Peering, and the values needed to configure your BYOC network. You can then follow xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering] to enable centralized egress at cluster creation. +Provision the customer-side infrastructure required for centralized egress on a Redpanda Bring Your Own Cloud (BYOC) cluster on GCP. After this procedure, you have a hub VPC with a NAT VM, exportable routes through VPC Network Peering, and the hub VPC name and project ID needed to configure your BYOC network. You can then follow xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering] to enable centralized egress at cluster creation. After reading this page, you will be able to: @@ -32,7 +32,7 @@ Traffic path: [NOTE] ==== -Local static routes in GCP always beat imported VPC peering routes, regardless of priority numbers. The Redpanda spoke VPC must not have a local `0.0.0.0/0` route — if one exists, it will silently win over the imported route and no traffic will flow through the hub NAT. +Local static routes in GCP always beat imported VPC peering routes, regardless of priority numbers. The Redpanda spoke VPC must not have a local `0.0.0.0/0` route. If one exists, it silently wins over the imported route and no traffic flows through the hub NAT. ==== [#automated-alternative] @@ -44,7 +44,7 @@ The rest of this guide covers the equivalent steps using the GCP Console or gclo == Prerequisites -* `gcloud` CLI configured with credentials for the hub project. +* The `gcloud` CLI, configured with credentials for the hub project. * Permissions: Compute Network Admin and Compute Instance Admin in the hub project. * If the hub and Redpanda cluster are in different GCP projects, the principal also needs `roles/compute.networkPeer` in the Redpanda project. * The hub subnet CIDR must not overlap with the Redpanda cluster VPC CIDR. VPC peering is rejected when CIDRs overlap. @@ -63,8 +63,8 @@ The procedure uses the values in the following table. Replace any value that doe | Parameter | Default | Notes | Hub project | `my-hub-project` | Replace with your GCP project ID -| Hub VPC name | `hub-vpc` | — -| Hub subnet name | `hub-subnet` | — +| Hub VPC name | `hub-vpc` | +| Hub subnet name | `hub-subnet` | | Hub subnet CIDR | `100.64.0.0/20` | CGNAT range, unlikely to conflict with typical workload CIDRs | Region | `us-central1` | Replace with your target region | Zone | `us-central1-a` | Replace with any zone in your region @@ -101,7 +101,7 @@ Console:: . Go to *VPC Network > VPC Networks > Create VPC Network*. . Set the name to `hub-vpc`. . Set *Subnet creation mode* to *Custom*. -. Click *Create*. Add the subnet in the next step. +. Click *Create*. You add the subnet as a separate step. CLI:: + @@ -181,7 +181,7 @@ Console:: . Go to *VPC Network > IP Addresses > Reserve Internal Static Address*. . Set the name to `hub-nat-internal-ip`, the network to `hub-vpc`, the subnetwork to `hub-subnet`, the region to `us-central1`, and the static IP address to *Assign automatically*. . Click *Reserve*. -. Note the allocated IP address — you will need it in the following steps. +. Record the allocated IP address. You need it to create the spoke-to-NAT route and the NAT VM instance template. CLI:: + @@ -203,11 +203,11 @@ echo "NAT internal IP: $NAT_INTERNAL_IP" == Create the tagged route: NAT VM to internet -This route lets the NAT VM reach the internet directly via the default internet gateway. The `nat-direct` network tag restricts it to the NAT VM only, preventing other VMs in the hub VPC from using it. +This route lets the NAT VM reach the internet directly through the default internet gateway. The `nat-direct` network tag restricts it to the NAT VM only, preventing other VMs in the hub VPC from using it. [NOTE] ==== -Priority `100` ensures the NAT VM uses this route rather than the untagged `0.0.0.0/0 → NAT VM` route created in the next step, which would cause a routing loop. +Priority `100` ensures the NAT VM uses this route rather than the untagged spoke-to-NAT route (`0.0.0.0/0 → NAT VM`), which would cause a routing loop. ==== [tabs] @@ -237,7 +237,7 @@ echo "Tagged route created: hub-nat-to-internet (priority 100, tag: nat-direct)" == Create the untagged route: spoke traffic to NAT VM -GCP exports routes with `next_hop_ip` via VPC peering. Routes with `next_hop_gateway = default-internet-gateway` are not exportable. This route is what the Redpanda spoke VPC imports to direct all outbound traffic through the hub. +GCP exports routes with `next_hop_ip` through VPC peering. Routes with `next_hop_gateway = default-internet-gateway` are not exportable. This route is what the Redpanda spoke VPC imports to direct all outbound traffic through the hub. [NOTE] ==== @@ -249,7 +249,7 @@ Priority `900` ensures the imported copy in the Redpanda spoke VPC beats the spo Console:: + . Go to *VPC Network > Routes > Create Route*. -. Set the name to `hub-spoke-to-nat`, the network to `hub-vpc`, the destination IP range to `0.0.0.0/0`, the priority to `900`, and the next hop to *Specify an IP address* with the internal IP reserved in the previous step. +. Set the name to `hub-spoke-to-nat`, the network to `hub-vpc`, the destination IP range to `0.0.0.0/0`, the priority to `900`, and the next hop to *Specify an IP address* with the static internal IP you reserved for the NAT VM. . Leave *Instance tags* empty. . Click *Create*. @@ -302,7 +302,7 @@ echo "Firewall rule created: hub-allow-nat-forward" == Create the NAT VM instance template -The NAT VM runs IP forwarding and iptables masquerade. It carries the `nat-direct` network tag so it picks up the direct-to-internet route created earlier. +The NAT VM runs IP forwarding and iptables masquerade. It carries the `nat-direct` network tag so it picks up the tagged direct-to-internet route (`hub-nat-to-internet`). [NOTE] ==== @@ -321,8 +321,8 @@ Console:: .. Add the network tag `nat-direct`. .. Enable *IP forwarding*. .. Set the network interface to `hub-vpc` / `hub-subnet`. -.. Set the external IPv4 address to `hub-nat-ip` (reserved earlier). -.. Set the internal IPv4 address to `hub-nat-internal-ip` (reserved earlier). +.. Set the external IPv4 address to `hub-nat-ip` (the static public IP you reserved). +.. Set the internal IPv4 address to `hub-nat-internal-ip` (the static internal IP you reserved). . Under *Advanced options > Management > Automation > Startup script*, paste the following script: + [,bash] @@ -379,7 +379,7 @@ echo "Instance template created: hub-nat-template" ---- ====== -== Create the Managed Instance Group +== Create the managed instance group A size-1 MIG ensures the NAT VM is automatically restarted if it crashes or is terminated. @@ -418,9 +418,9 @@ Create the peering from the hub side. Redpanda creates the reciprocal peering fr [NOTE] ==== -Set `--export-custom-routes` so the `0.0.0.0/0 → NAT internal IP` route is visible to the Redpanda VPC. Do not set `--import-custom-routes` — the hub does not need to import routes from the spoke. +Set `--export-custom-routes` so the `0.0.0.0/0 → NAT internal IP` route is visible to the Redpanda VPC. Do not set `--import-custom-routes`, because the hub does not need to import routes from the spoke. -The peering shows as *INACTIVE* until the Redpanda cluster provisions the reciprocal peering. This is expected — proceed to create the cluster after this step. +The peering shows as *INACTIVE* until the Redpanda cluster provisions the reciprocal peering. This is expected. Proceed to create the cluster. ==== [tabs] @@ -495,7 +495,7 @@ The <> deploys a single NAT VM. Exten | NAT VM is not forwarding traffic | IP forwarding is not enabled on the instance template (`--can-ip-forward`), or the iptables MASQUERADE rule was not applied. Recreate the instance template with IP forwarding enabled and check the startup script output in the GCP serial console. -| `hub-spoke-to-nat` route is not exported to the spoke | The route uses `next_hop_gateway = default-internet-gateway` instead of `next_hop_ip`. GCP exports only routes with `next_hop_ip` or `next_hop_instance` via peering. Verify the route in *VPC Network > Routes* shows a next-hop IP address, not the internet gateway. +| `hub-spoke-to-nat` route is not exported to the spoke | The route uses `next_hop_gateway = default-internet-gateway` instead of `next_hop_ip`. GCP exports only routes with `next_hop_ip` or `next_hop_instance` through peering. Verify the route in *VPC Network > Routes* shows a next-hop IP address, not the internet gateway. |=== == Next steps diff --git a/modules/networking/pages/byoc/gcp/nat-free-egress.adoc b/modules/networking/pages/byoc/gcp/nat-free-egress.adoc index 61709d85a..a4a0c0901 100644 --- a/modules/networking/pages/byoc/gcp/nat-free-egress.adoc +++ b/modules/networking/pages/byoc/gcp/nat-free-egress.adoc @@ -12,7 +12,7 @@ This feature is in beta and is available only on GCP BYOC clusters with private networking. Availability is controlled per organization. Contact your account team to request access to centralized egress. ==== -Centralized egress lets your BYOC cluster send all internet-bound traffic through your own GCP hub VPC instead of a Redpanda-managed Cloud NAT in the Redpanda VPC. When centralized egress is enabled, the Redpanda spoke VPC peers to your hub VPC with `import_custom_routes = true`, all outbound traffic exits through the NAT VM in your hub, and no Cloud Router or Cloud NAT is created in the spoke VPC. +Centralized egress lets your BYOC cluster send all internet-bound traffic through your own GCP hub VPC instead of a Redpanda-managed Cloud NAT, so outbound traffic exits through a single, predictable public IP that you control. After reading this page, you will be able to: @@ -65,7 +65,7 @@ The following diagram shows the connectivity model: === Return traffic flow . The internet response arrives at the public IP on the NAT VM in the hub VPC. -. The NAT VM forwards it back to the originating node via the VPC peering connection. +. The NAT VM forwards it back to the originating node through the VPC peering connection. . The packet arrives at the originating GKE node. [#prerequisites] @@ -188,7 +188,7 @@ The NAT VM funnels all internet egress for all peered clusters through a single | Cluster creation does not complete | The cluster cannot reach the external endpoints it needs during bootstrap. Verify that the hub-side VPC peering has `export_custom_routes = true`; the `0.0.0.0/0 → NAT VM internal IP` route exists in the hub VPC and uses `next_hop_ip` (not `next_hop_gateway`); the NAT VM is running and healthy; and the firewall rule allows spoke CIDR traffic to reach the NAT VM. Also confirm the endpoints listed in <> are reachable. -| The spoke VPC has no `0.0.0.0/0` route after peering is established | The hub-side peering does not have `export_custom_routes = true`, or the route uses `next_hop_gateway = default-internet-gateway` instead of `next_hop_ip`. GCP only exports routes with `next_hop_ip` or `next_hop_instance` via peering. Verify the route at *VPC Network > Routes* and update the hub-side peering if needed. +| The spoke VPC has no `0.0.0.0/0` route after peering is established | The hub-side peering does not have `export_custom_routes = true`, or the route uses `next_hop_gateway = default-internet-gateway` instead of `next_hop_ip`. GCP only exports routes with `next_hop_ip` or `next_hop_instance` through peering. Verify the route at *VPC Network > Routes* and update the hub-side peering if needed. | Peering is stuck in `INACTIVE` state | Both sides of the peering must be established for it to become `ACTIVE`. The hub-side peering remains `INACTIVE` until `rpk byoc gcp apply` creates the reciprocal spoke-side peering. If the cluster is already running, verify that `import_custom_routes = true` is set on the Redpanda-side peering. @@ -198,7 +198,7 @@ The NAT VM funnels all internet egress for all peered clusters through a single | Traffic exits from an unexpected IP | The NAT VM may have been replaced and the startup script did not run correctly. SSH into the NAT VM and run `iptables -t nat -L POSTROUTING` to verify the MASQUERADE rule, and `sysctl net.ipv4.ip_forward` to verify IP forwarding is enabled. -| All traffic appears from one IP | Correct — this is the centralized egress design. All peered clusters share the single public IP assigned to the NAT VM. +| All traffic appears from one IP | Correct. This is the centralized egress design, and all peered clusters share the single public IP assigned to the NAT VM. |=== == Next steps From 846c234256cb6c783a3eaa1ec648bb459f740166 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 23 Jun 2026 15:19:00 -0600 Subject: [PATCH 3/5] Fix gcloud NAT instance-template command to pin the static egress IP --address is not a valid flag for `gcloud compute instance-templates create`. Consolidate the network flags into --network-interface with address= so the NAT VM keeps the single reserved public IP, mirroring the cloud-examples gcp-hub-egress Terraform (access_config.nat_ip). Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc index 52fd3be43..2ed63faf2 100644 --- a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc +++ b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc @@ -369,10 +369,7 @@ gcloud compute instance-templates create hub-nat-template \ --boot-disk-type=pd-balanced \ --can-ip-forward \ --tags=nat-direct \ - --network=$VPC_NAME \ - --subnet=$SUBNET_NAME \ - --private-network-ip=$NAT_INTERNAL_IP \ - --address=$NAT_PUBLIC_IP \ + --network-interface=network=$VPC_NAME,subnet=$SUBNET_NAME,private-network-ip=$NAT_INTERNAL_IP,address=$NAT_PUBLIC_IP \ --metadata-from-file=startup-script=/tmp/nat-startup.sh echo "Instance template created: hub-nat-template" From 354c269d32d733ad2762e0780eed23651358f43a Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 23 Jun 2026 15:44:30 -0600 Subject: [PATCH 4/5] List centralized egress for BYOC on AWS and GCP in Features in beta Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/get-started/pages/cloud-overview.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/get-started/pages/cloud-overview.adoc b/modules/get-started/pages/cloud-overview.adoc index 7be3fd121..634e60710 100644 --- a/modules/get-started/pages/cloud-overview.adoc +++ b/modules/get-started/pages/cloud-overview.adoc @@ -400,7 +400,8 @@ The following features are currently in beta in Redpanda Cloud: * BYOVNet for Azure * Secrets management for BYOVPC on GCP -* Several Redpanda Connect components +* Centralized egress for BYOC on AWS and GCP +* Several Redpanda Connect components include::shared:partial$suggested-video.adoc[] From 7ee4f123e834ad04d8a1eb5325f6eed96b3d6b4b Mon Sep 17 00:00:00 2001 From: Panagiotis Panagiotopoulos Date: Thu, 25 Jun 2026 13:33:40 +0300 Subject: [PATCH 5/5] DOC-2267: Apply style fixes and add GCP Cloud API egress_spec documentation - Shorten gcp-hub-egress.adoc intro to 35 words (was ~74), outcome-led - Add egress_spec.gcp Cloud API section to nat-free-egress.adoc behind show-preview-api gate, matching the AWS pattern - Add GCP egress_spec block to controlplane-api.adoc partial - Remove incorrect immutability claims from AWS and GCP egress_spec entries (storage layer confirms egress_spec is updatable) Co-Authored-By: Claude Sonnet 4.6 --- modules/manage/partials/controlplane-api.adoc | 29 ++++++++++++++- .../pages/byoc/gcp/gcp-hub-egress.adoc | 2 +- .../pages/byoc/gcp/nat-free-egress.adoc | 37 +++++++++++++++++++ 3 files changed, 66 insertions(+), 2 deletions(-) diff --git a/modules/manage/partials/controlplane-api.adoc b/modules/manage/partials/controlplane-api.adoc index b0cab27b5..770e734ac 100644 --- a/modules/manage/partials/controlplane-api.adoc +++ b/modules/manage/partials/controlplane-api.adoc @@ -131,9 +131,12 @@ curl -d \ // to route all cluster egress through a customer-owned Transit Gateway. // It is gated behind `:show-preview-api:` while the field is in preview. // To enable, set the attribute in the playbook or in this page header. +// The GCP BYOC network example adds `egress_spec.gcp.hub_vpc_project` and +// `egress_spec.gcp.hub_vpc_name` for centralized egress through a hub VPC. +// Also gated behind `:show-preview-api:`. ifdef::show-preview-api[] -To route all cluster egress through your own AWS Transit Gateway and hub VPC instead of a per-VPC NAT Gateway, set `egress_spec.aws.transit_gateway_id` on an AWS BYOC network. Centralized egress is in beta. The Transit Gateway ID is immutable after the network is created. Before calling this endpoint, provision the hub VPC and Transit Gateway and share the Transit Gateway with the Redpanda cluster account. See xref:networking:byoc/aws/aws-hub-egress.adoc[Create an AWS Hub for Centralized Egress] and xref:networking:byoc/aws/nat-free-egress.adoc[Configure Centralized Egress with AWS Transit Gateway]. +To route all cluster egress through your own AWS Transit Gateway and hub VPC instead of a per-VPC NAT Gateway, set `egress_spec.aws.transit_gateway_id` on an AWS BYOC network. Centralized egress is in beta. Before calling this endpoint, provision the hub VPC and Transit Gateway and share the Transit Gateway with the Redpanda cluster account. See xref:networking:byoc/aws/aws-hub-egress.adoc[Create an AWS Hub for Centralized Egress] and xref:networking:byoc/aws/nat-free-egress.adoc[Configure Centralized Egress with AWS Transit Gateway]. [,bash] ---- @@ -155,6 +158,30 @@ curl -d \ }' -H "Content-Type: application/json" \ -H "Authorization: Bearer " -X POST https://api.redpanda.com/v1/networks ---- + +To route all cluster egress through your own GCP hub VPC and NAT VM instead of a per-cluster Cloud NAT, set `egress_spec.gcp.hub_vpc_project` and `egress_spec.gcp.hub_vpc_name` on a GCP BYOC network. Centralized egress is in beta. Before calling this endpoint, provision the hub VPC and NAT VM. See xref:networking:byoc/gcp/gcp-hub-egress.adoc[Create a GCP Hub for Centralized Egress] and xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering]. + +[,bash] +---- +curl -d \ +'{ + "network": { + "cidr_block": "10.0.0.0/20", + "cloud_provider": "CLOUD_PROVIDER_GCP", + "cluster_type": "TYPE_BYOC", + "name": "", + "resource_group_id": "", + "region": "us-west1", + "egress_spec": { + "gcp": { + "hub_vpc_project": "", + "hub_vpc_name": "" + } + } + } +}' -H "Content-Type: application/json" \ +-H "Authorization: Bearer " -X POST https://api.redpanda.com/v1/networks +---- endif::[] endif::[] diff --git a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc index 2ed63faf2..330dca98b 100644 --- a/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc +++ b/modules/networking/pages/byoc/gcp/gcp-hub-egress.adoc @@ -7,7 +7,7 @@ :learning-objective-2: Configure routes and VPC Network Peering to export the default route to Redpanda spoke VPCs :learning-objective-3: Collect the hub VPC name and project ID needed for BYOC cluster configuration -Provision the customer-side infrastructure required for centralized egress on a Redpanda Bring Your Own Cloud (BYOC) cluster on GCP. After this procedure, you have a hub VPC with a NAT VM, exportable routes through VPC Network Peering, and the hub VPC name and project ID needed to configure your BYOC network. You can then follow xref:networking:byoc/gcp/nat-free-egress.adoc[Configure Centralized Egress with GCP VPC Peering] to enable centralized egress at cluster creation. +Provision a hub VPC and NAT VM so one or more BYOC clusters route internet egress through a single public IP. After this procedure you have the hub VPC name and project ID needed to configure your BYOC network. After reading this page, you will be able to: diff --git a/modules/networking/pages/byoc/gcp/nat-free-egress.adoc b/modules/networking/pages/byoc/gcp/nat-free-egress.adoc index a4a0c0901..54048a78c 100644 --- a/modules/networking/pages/byoc/gcp/nat-free-egress.adoc +++ b/modules/networking/pages/byoc/gcp/nat-free-egress.adoc @@ -152,6 +152,43 @@ curl -s https://api.ipify.org # Expected output: the NAT public IP you reserved in the hub setup ---- +// The Cloud API path for centralized egress is intentionally hidden while the +// `egress_spec` field is in PREVIEW. To re-enable the section when the field +// graduates, set the :show-preview-api: attribute (either in this page's +// header as `:show-preview-api:` or as a build-time attribute in the playbook). +ifdef::show-preview-api[] +=== Use the Cloud API + +[IMPORTANT] +==== +The `egress_spec` field is in preview. Its shape and validation rules may change. Pin a specific API version when scripting against this field, and revisit your integration when the field graduates to general availability. +==== + +Set `egress_spec.gcp.hub_vpc_project` and `egress_spec.gcp.hub_vpc_name` on the Network resource when you create a network. Both fields are required when `egress_spec.gcp` is set. + +[,bash] +---- +curl -X POST https://api.redpanda.com/v1/networks \ + -H "Authorization: Bearer $REDPANDA_CLOUD_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "prod-us-west1", + "cloud_provider": "CLOUD_PROVIDER_GCP", + "region": "us-west1", + "cidr_block": "10.0.0.0/20", + "cluster_type": "TYPE_BYOC", + "egress_spec": { + "gcp": { + "hub_vpc_project": "", + "hub_vpc_name": "" + } + } + }' +---- + +For the surrounding workflow (authenticating to the Cloud API, creating the resource group, creating the cluster against this network, and running `rpk byoc gcp apply`) see xref:manage:api/cloud-byoc-controlplane-api.adoc[Use the BYOC Control Plane API]. After the network is created, you can create the cluster against it through the UI or by calling the Cluster create endpoint with the new network ID. +endif::[] + [#internet-endpoints] == Internet endpoints required from your hub