Skip to content

DOC-1348: Document cross-region AWS PrivateLink feature #480

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
micheleRP wants to merge 7 commits into
base: main
Choose a base branch
from
+98 −8
Open

DOC-1348: Document cross-region AWS PrivateLink feature #480

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0a84d0b
DOC-1348: Document cross-region AWS PrivateLink feature
micheleRP Jan 8, 2026
9d655c3
DOC-1348: Add Cloud UI documentation for cross-region PrivateLink
micheleRP Jan 8, 2026
5f20adf
DOC-1348: Add note that supported regions only appears for multi-AZ c…
micheleRP Jan 8, 2026
f34c40f
style edits
micheleRP Jan 8, 2026
50aa5c2
style edit
micheleRP Jan 8, 2026
e71a0a4
incorporate comments from code review
micheleRP Jan 14, 2026
f548f76
incorporate doc review feedback
micheleRP Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions modules/get-started/pages/whats-new-cloud.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ xref:get-started:cluster-types/serverless.adoc[Serverless] on AWS is now general

You can now enable xref:manage:schema-reg/schema-id-validation.adoc[schema ID validation] by xref:manage:cluster-maintenance/config-cluster.adoc[configuring the `enable_schema_id_validation` cluster property]. This controls whether or not Redpanda validates schema IDs in records and which topic properties are enforced. Use caution when enabling this property, because it could cause decompression across topics and increase CPU load.

=== Cross-region AWS PrivateLink

AWS PrivateLink now supports cross-region connectivity, allowing clients in different AWS regions to connect to your Redpanda cluster through PrivateLink. Configure supported regions in the xref:networking:configure-privatelink-in-cloud-ui.adoc#cross-region-privatelink[Cloud UI] or using the xref:networking:aws-privatelink.adoc#cross-region-privatelink[Cloud API] to specify which regions can establish PrivateLink connections. This feature requires multi-AZ cluster deployments.

== January 2026

=== Redpanda Connect updates
Expand Down
1 change: 1 addition & 0 deletions modules/manage/pages/terraform-provider.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,6 +355,7 @@ resource "redpanda_cluster" "test" {
enabled = true
connect_console = true
allowed_principals = ["arn:aws:iam::123456789024:root"]
supported_regions = ["us-east-1", "us-west-2"] # Optional: Enable cross-region PrivateLink
}
tags = {
"environment" = "dev"
Expand Down
69 changes: 64 additions & 5 deletions modules/networking/pages/aws-privatelink.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ Consider using the PrivateLink endpoint service if you have multiple VPCs and co

After <<get-a-cloud-api-access-token,getting an access token>>, you can <<create-new-cluster-with-privatelink-endpoint-service-enabled,enable PrivateLink when creating a new cluster>>, or you can <<enable-privatelink-endpoint-service-for-existing-clusters,enable PrivateLink for existing clusters>>.

== Requirements
== Prerequisites

* Install `rpk`.
* Your Redpanda cluster and <<create-client-vpc,VPC>> must be in the same region.
* Your Redpanda cluster and <<create-client-vpc,VPC>> must be in the same region, unless you configure <<cross-region-privatelink,cross-region PrivateLink>>.
* In this guide, you use the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Redpanda Cloud API] to enable the Redpanda endpoint service for your clusters. Follow the steps below to <<get-an-access-token,get an access token>>.
* Use the https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html[AWS CLI^] to create a new client VPC or modify an existing one to use the PrivateLink endpoint.

Expand Down Expand Up @@ -93,6 +93,7 @@ In the example below, make sure to set your own values for the following fields:
- `name`
- `connect_console`: Whether to enable connections to Redpanda Console (boolean)
- `allowed_principals`: Amazon Resource Names (ARNs) for the AWS principals allowed to access the endpoint service. For example, for all principals in an account, use `"arn:aws:iam::account_id:root"`. See https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permission[Configure an endpoint service^] for details.
- `supported_regions`: (Optional) List of AWS regions from which PrivateLink endpoints can connect to Redpanda. Required only for <<cross-region-privatelink,cross-region PrivateLink>>. For example, `["us-east-1", "us-west-2"]`.
--
+
[,bash]
Expand All @@ -112,7 +113,8 @@ CLUSTER_POST_BODY=`cat << EOF
"aws_private_link": {
"enabled": true,
"connect_console": true,
"allowed_principals": ["<principal_1>","<principal_2>"]
"allowed_principals": ["<principal_1>","<principal_2>"],
"supported_regions": ["<region_1>","<region_2>"]
}
}
}
Expand Down Expand Up @@ -158,6 +160,7 @@ In the example below, make sure to set your own value for the following field:
--
- `connect_console`: Whether to enable connections to Redpanda Console (boolean)
- `allowed_principals`: Amazon Resource Names (ARNs) for the AWS principals allowed to access the endpoint service. For example, for all principals in an account, use `"arn:aws:iam::account_id:root"`. See https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permission[Configure an endpoint service^] for details.
- `supported_regions`: (Optional) List of AWS regions from which PrivateLink endpoints can connect to Redpanda. Required only for <<cross-region-privatelink,cross-region PrivateLink>>. For example, `["us-east-1", "us-west-2"]`.
--
+
[,bash]
Expand All @@ -167,7 +170,8 @@ CLUSTER_PATCH_BODY=`cat << EOF
"aws_private_link": {
"enabled": true,
"connect_console": true,
"allowed_principals": ["<principal_1>","<principal_2>"]
"allowed_principals": ["<principal_1>","<principal_2>"],
"supported_regions": ["<region_1>","<region_2>"]
}
}
EOF`
Expand Down Expand Up @@ -234,7 +238,7 @@ xref:networking:byoc/aws/vpc-peering-aws.adoc[VPC peering] and PrivateLink will
VPC peering and PrivateLink can both be used at the same time if Kafka clients are connecting from distinct VPCs. For example, in a private Redpanda cluster, you can connect your internal Kafka clients over VPC peering, and enable PrivateLink for external services.
====

The VPC region must be the same region where the Redpanda cluster is deployed. To create the VPC, run:
The client VPC must be in the same region as your Redpanda cluster, unless you have configured <<cross-region-privatelink,cross-region PrivateLink>>. To create the VPC, run:

[,bash]
----
Expand Down Expand Up @@ -346,6 +350,61 @@ After you have enabled PrivateLink for your cluster, your connection URLs are av

include::networking:partial$private-links-access-rp-services-through-vpc.adoc[]

== Cross-region PrivateLink

By default, AWS PrivateLink only allows connections from VPCs in the same region as the endpoint service. Cross-region PrivateLink enables clients in different AWS regions to connect to your Redpanda cluster through PrivateLink.

For more information about AWS cross-region PrivateLink support, see the https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html#endpoint-service-cross-region[AWS documentation^].

=== Requirements

* The Redpanda cluster must be deployed across multiple availability zones (multi-AZ). This is an AWS limitation for cross-region PrivateLink.
* Cross-region PrivateLink is configured through the `supported_regions` field in the `aws_private_link` configuration. This field only appears in the API response for multi-AZ clusters.
* For BYOC clusters, the Redpanda agent IAM role must have `vpce:AllowMultiRegion` and `elasticloadbalancing:DescribeListenerAttributes` permissions.

Comment on lines 359 to 364
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Missing AWS permissions and feature flag documentation per PR objectives.

The PR objectives specify documenting "new required AWS permissions: vpce:AllowMultiRegion and elasticloadbalancing:DescribeListenerAttributes" and "the feature flag guarding the capability." Neither is present in the Requirements section or elsewhere in the new cross-region documentation.

Add the missing AWS permissions and feature flag guidance. These should be included in the Requirements subsection (lines 359-363) so users understand all prerequisites before attempting to configure cross-region PrivateLink.

🤖 Prompt for AI Agents 
In @modules/networking/pages/aws-privatelink.adoc around lines 359 - 363, Update
the Requirements subsection to list the two new AWS IAM permissions and the
feature flag: add bullets stating that IAM must allow vpce:AllowMultiRegion and
elasticloadbalancing:DescribeListenerAttributes, and note that the cross-region
PrivateLink capability is guarded by the feature flag named in the PR objectives
(mention the exact flag name from the PR and how to enable it in cluster
configuration), and keep the existing note about configuring cross-region via
the aws_private_link supported_regions field so users see all prerequisites in
one place.

Copy link
Contributor

@paulzhang97 paulzhang97 Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new perms should be added to here. But the page is outdated, especially it does not include the perms related to Private Link. Can we add the perms in this PR?

Copy link
Contributor

@coderabbitai coderabbitai bot Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find the cloud IAM policies documentation file
fd -t f "cloud-iam-policies" --extension adoc

# Also search for files that might contain IAM policy documentation
fd -t f "iam" --extension adoc | head -20

Length of output: 429

🏁 Script executed:

#!/bin/bash
# Read the current AWS IAM policies documentation
cat modules/security/pages/authorization/cloud-iam-policies.adoc

# Also check the partial file
echo "====== PARTIAL FILE ======"
cat modules/security/partials/iam-policies.adoc

Length of output: 34391

🏁 Script executed:

#!/bin/bash
# Fetch the Terraform file content from GitHub to see the PrivateLink permissions
curl -s "https://raw.githubusercontent.com/redpanda-data/cloudv2/42e19f241f98bda8c6a02623bcb849c9325be2d6/apps/redpanda-agent/infra/aws/redpanda/agent/instance_profile.tf" | sed -n '425,457p'

Length of output: 0

🏁 Script executed:

#!/bin/bash
# Try fetching the entire file and then extracting the relevant section
curl -s "https://raw.githubusercontent.com/redpanda-data/cloudv2/42e19f241f98bda8c6a02623bcb849c9325be2d6/apps/redpanda-agent/infra/aws/redpanda/agent/instance_profile.tf" > /tmp/instance_profile.tf

# Check if the file was downloaded
if [ -s /tmp/instance_profile.tf ]; then
    echo "File downloaded successfully. Total lines:"
    wc -l /tmp/instance_profile.tf
    
    echo ""
    echo "Lines 425-457:"
    sed -n '425,457p' /tmp/instance_profile.tf
    
    echo ""
    echo "=== Searching for PrivateLink-related permissions ==="
    grep -i -A 5 -B 5 "privatelink\|vpce\|endpoint.*service" /tmp/instance_profile.tf | head -80
else
    echo "Failed to download the file. Trying alternative approach..."
    # Try with different user agent
    curl -A "Mozilla/5.0" -s "https://raw.githubusercontent.com/redpanda-data/cloudv2/42e19f241f98bda8c6a02623bcb849c9325be2d6/apps/redpanda-agent/infra/aws/redpanda/agent/instance_profile.tf" | grep -i -A 10 -B 5 "privatelink\|vpce\|elasticloadbalancing" | head -100
fi

Length of output: 140

🌐 Web query:

AWS vpce:AllowMultiRegion permission PrivateLink cross-region

💡 Result:

Short answer

  • vpce:AllowMultiRegion is a permission-only action you must allow (in identity policies and not denied by SCPs) to create or access PrivateLink (VPC endpoint service or interface endpoint) across AWS Regions. [1][2][3]

Key points

  • Who needs it: service providers (to make a VPCE service available in multiple Regions) and service consumers (to create an interface endpoint to a service in another Region). [1][2]
  • Policy controls: use ec2:VpceSupportedRegion (providers) and ec2:VpceServiceRegion (consumers) condition keys to restrict which Regions can be added/used. [1][2]
  • SCPs: ensure your organization SCPs do not deny vpce:AllowMultiRegion. [2][3]
  • Opt-in Regions: accounts must be opted-in to opt-in Regions before selecting them. [1]

Minimal example IAM statement (allow only two service Regions)
{
"Effect":"Allow",
"Action":"vpce:AllowMultiRegion",
"Resource":"arn:aws:ec2:::vpc-endpoint/*",
"Condition":{
"StringLike":{"ec2:VpceServiceRegion":["ap-northeast-1","eu-west-1"]}
}
}
(Adapt Principal/Resource to your use case.) [3]

Sources

  • AWS PrivateLink: Share your services (cross-Region permissions & condition keys). [1]
  • AWS PrivateLink cross-region docs (permissions/considerations). [2]
  • AWS blog / announcement describing vpce:AllowMultiRegion and examples. [3]

🌐 Web query:

AWS elasticloadbalancing:DescribeListenerAttributes PrivateLink cross-region

💡 Result:

Short answer: DescribeListenerAttributes is an ELBv2 (regional) API that returns attributes for a listener on a load balancer in the region you call. For a PrivateLink (VPCE service) that is hosted in another AWS Region, call DescribeListenerAttributes (or aws elbv2 describe-listener-attributes) against the load balancer's region (or set --region to the service region / use that region's endpoint). PrivateLink cross‑region itself does not change which ELB API region you must call. [1][2]

Practical notes:

  • PrivateLink provider endpoints are typically backed by a Network Load Balancer; the ELBv2 listener attributes supported for NLB/GWLB (e.g. tcp.idle_timeout.seconds) are documented in the ELB API/CLI docs. Querying those attributes must target the region where the NLB exists. [2][3]
  • If the load balancer is in another account, ensure the caller has IAM permissions and the correct ARN (and cross-account trust) to call DescribeListenerAttributes in that region.
  • With the AWS CLI you can specify --region or use the ARN's region to direct the request. [3]

Sources:
[1] AWS PrivateLink cross‑region announcement and docs.
[2] ELBv2 DescribeListenerAttributes / API reference.
[3] AWS CLI elbv2 describe-listener-attributes reference.

@paulzhang97 Yes, adding the IAM permissions documentation to this PR makes sense since users will need these permissions to use cross-region PrivateLink.

I can help plan the code changes to update modules/security/pages/authorization/cloud-iam-policies.adoc. From the PR objectives and my research, I've confirmed the two new permissions for cross-region PrivateLink:

  1. vpce:AllowMultiRegion - Required for both service providers and consumers to enable cross-region PrivateLink connections
  2. elasticloadbalancing:DescribeListenerAttributes - Required to retrieve listener attributes for the Network Load Balancer backing the PrivateLink service

However, I cannot access the private cloudv2 repository you linked to see the existing PrivateLink permissions at lines 425-457. Could you either:

  1. Provide the list of existing PrivateLink-related permissions from that Terraform file that should be documented, or
  2. Confirm which permissions are currently missing from the docs that should be added

Once I have this information, I can plan the code changes to add a dedicated PrivateLink permissions section (or update the VPC Management section) in the IAM policies documentation with both the new cross-region permissions and any missing existing permissions.

Would you like me to proceed with planning these changes?

🧠 Learnings used 
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 390
File: modules/manage/pages/schema-reg/schema-reg-authorization.adoc:4-4
Timestamp: 2025-08-15T02:29:34.901Z
Learning: In Redpanda Cloud documentation PRs, when CodeRabbit flags missing Asciidoctor tag markers for include directives, the fix may be implemented in the corresponding ROOT module file that contains the actual content being included, rather than in the file where the include directive appears.

Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.

=== Configure cross-region PrivateLink

To enable cross-region PrivateLink, add the `supported_regions` field to your `aws_private_link` configuration when <<create-new-cluster-with-privatelink-endpoint-service-enabled,creating a new cluster>> or <<enable-privatelink-endpoint-service-for-existing-clusters,enabling PrivateLink on an existing cluster>>.

The `supported_regions` field accepts a list of AWS region identifiers where you want to allow PrivateLink connections from. For example:

[,json]
----
"aws_private_link": {
"enabled": true,
"connect_console": true,
"allowed_principals": ["arn:aws:iam::123456789012:root"],
"supported_regions": ["us-east-1", "us-west-2", "eu-west-1"]
}
----

With this configuration, clients in VPCs located in `us-east-1`, `us-west-2`, and `eu-west-1` can create PrivateLink endpoints that connect to your Redpanda cluster, regardless of which region the cluster is deployed in.

=== Create a cross-region VPC endpoint

When creating a VPC endpoint in a different region than your Redpanda cluster, use the same process as <<create-vpc-endpoint,creating a standard VPC endpoint>>, but specify both the client VPC's region and the service region where your Redpanda cluster is deployed.

NOTE: The `--service-region` option requires AWS CLI version 2.22.0 or later. Run `aws --version` to check your version and https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html[update if necessary^].

[,bash]
----
# CLIENT_REGION is the region where your client VPC is located
# SERVICE_REGION is the region where your Redpanda cluster is deployed
CLIENT_REGION=<client_region>
SERVICE_REGION=<service_region>

aws ec2 create-vpc-endpoint \
--region $CLIENT_REGION --profile $PROFILE \
Copy link
Contributor

@paulzhang97 paulzhang97 Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to add --service-region $SERVICE_REGION. SERVICE_REGION is the region where RP cluster is deployed.

We should also mention for updating aws cli with the latest since an older aws might not have the option --service-region.

--service-region $SERVICE_REGION \
--vpc-id $CLIENT_VPC_ID \
--vpc-endpoint-type "Interface" \
--ip-address-type "ipv4" \
--service-name $PL_SERVICE_NAME \
--subnet-ids $SUBNET_ID \
--security-group-ids $SECURITY_GROUP_ID \
--private-dns-enabled
----

== Test the connection

You can test the PrivateLink connection from any VM or container in the consumer VPC. If configuring a client isn't possible right away, you can do these checks using `rpk` or cURL:
Expand Down
32 changes: 29 additions & 3 deletions modules/networking/pages/configure-privatelink-in-cloud-ui.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Consider using the endpoint service if you have multiple VPCs and could benefit

== Requirements

* Your Redpanda cluster and VPC must be in the same region.
* Your Redpanda cluster and VPC must be in the same region, unless you configure <<cross-region-privatelink,cross-region PrivateLink>>.
* Use the https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html[AWS CLI] to create a new client VPC or modify an existing one to use the PrivateLink endpoint.

TIP: In Kafka clients, set `connections.max.idle.ms` to a value less than 350 seconds.
Expand All @@ -31,8 +31,9 @@ include::networking:partial$dns_resolution.adoc[]

. In the Redpanda Cloud Console, select your https://cloud.redpanda.com/clusters[cluster^], and go to the *Cluster settings* page.
. For AWS PrivateLink, click *Enable*.
. On the Enable PrivateLink page, for Allowed principal ARNs, click *Add*, and enter the Amazon Resource Names (ARNs) for each AWS principal allowed to access the endpoint service. For example, for all principals in a specific account, use `arn:aws:iam::<account-id>:root`. See the AWS documentation on https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permission[configuring an endpoint service^] for details.
. Click *Add* after entering each ARN, and when finished, click *Enable*.
. On the Enable PrivateLink page, for Allowed principal ARNs, click *Add*, and enter the Amazon Resource Names (ARNs) for each AWS principal allowed to access the endpoint service. For example, for all principals in a specific account, use `arn:aws:iam::<account-id>:root`. See the AWS documentation on https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permission[configuring an endpoint service^] for details.
. Click *Add* after entering each ARN, and when finished, click *Enable*.
. (Optional) To enable cross-region PrivateLink, add supported regions. See <<cross-region-privatelink>>.
. It may take several minutes for your cluster to update. When the update is complete, the AWS PrivateLink status on the Cluster settings page changes from *In progress* to *Enabled*.

NOTE: For help with issues when enabling PrivateLink, contact https://support.redpanda.com/hc/en-us/requests/new[Redpanda support^].
Expand All @@ -49,6 +50,31 @@ You can test the connection to the endpoint service from any VM or container in

include::networking:partial$private-links-test-connection.adoc[]

== Cross-region PrivateLink

By default, AWS PrivateLink only allows connections from VPCs in the same region as the endpoint service. Cross-region PrivateLink enables clients in different AWS regions to connect to your Redpanda cluster through PrivateLink.

For more information about AWS cross-region PrivateLink support, see the https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html#endpoint-service-cross-region[AWS documentation^].

=== Prerequisites

* The Redpanda cluster must be deployed across multiple availability zones (multi-AZ). This is an AWS limitation for cross-region PrivateLink.

=== Configure supported regions

NOTE: The *Supported regions* option only appears in the UI for multi-AZ clusters.

. In the Redpanda Cloud UI, select your https://cloud.redpanda.com/clusters[cluster^], and go to the cluster settings page.
. In the AWS PrivateLink section, click *Edit* (or *Enable* if PrivateLink is not yet enabled).
. In the *Supported regions* section, click *Add* to add a region from which PrivateLink endpoints can connect to your cluster.
. Select an AWS region from the dropdown. The cluster's home region is automatically included and not shown in the list.
. Repeat to add additional regions as needed.
. Click *Save* (or *Enable*) to apply the changes.

After saving, the *Supported regions* row on the cluster settings page displays your configured regions.

Clients in VPCs located in the supported regions can now create PrivateLink endpoints that connect to your Redpanda cluster.

== Disable endpoint service

On the Cluster settings page for the cluster, click *Disable* for PrivateLink. Existing connections are closed after the AWS PrivateLink service is disabled. To connect using PrivateLink again, you must re-enable the service.
Expand Down