Connect an AWS Environment to a Transit Gateway
Connect a private Agentic Data Plane environment on AWS to an AWS Transit Gateway that you own. Self-managed agents, test harnesses, and applications in the other virtual private clouds (VPCs) attached to the Transit Gateway can then reach the environment’s AI Gateway and API over private IPv4 addresses. You connect the environment once, instead of peering it with each VPC.
This page applies only to environments on AWS. For an environment on Google Cloud, see Connect a Google Cloud Environment to a Network Connectivity Center Hub. To connect a single VPC on either cloud, see Peer a VPC with an Environment.
After reading this page, you will be able to:
-
Attach a private environment’s VPC on AWS to a Transit Gateway that you own
-
Configure routes so traffic flows in both directions between the environment and your other VPCs
-
Verify that workloads in another VPC reach the environment
Prerequisites
-
An environment on AWS with
Privateaccess that showsReady. To create one, see Create an Agentic Data Plane Environment. -
A Transit Gateway in the environment’s region, with the VPCs that your workloads run in attached to it.
-
Credentials for the AWS account that you deployed the environment into. If the Transit Gateway or your VPCs are in other accounts, you also need credentials for those accounts. In the environment’s account, you need the EC2 permissions for the commands on this page:
-
ec2:DescribeVpcs,ec2:DescribeSubnets, andec2:DescribeRouteTables -
ec2:CreateTransitGatewayVpcAttachment,ec2:DescribeTransitGatewayVpcAttachments, andec2:DeleteTransitGatewayVpcAttachment -
ec2:CreateRouteandec2:DeleteRoute -
ec2:SearchTransitGatewayRoutes
-
-
The AWS CLI, or Terraform 1.5 or later with the AWS provider.
-
Workloads and address ranges that meet these requirements:
Requirement Details Address ranges
The environment’s CIDR block doesn’t overlap the CIDR block of any other VPC attached to the Transit Gateway. A Transit Gateway doesn’t route between VPCs whose address ranges overlap.
Client source addresses
Your workloads use addresses in
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16, or100.64.0.0/10. The endpoints accept connections only from these ranges. You don’t need to change a security group in the environment.Region
Workloads in the environment’s region reach it through the Transit Gateway. Workloads in another region reach it through a peering between that region’s Transit Gateway and yours. See Reach the environment from another region.
How the Transit Gateway connects your VPCs
An environment with Private access serves its AI Gateway and API endpoints from an internal load balancer in the environment’s VPC. By default, the load balancer has an address in each of the environment’s three Availability Zones. The endpoint hostnames are in public DNS and resolve to those private addresses, so workloads in other VPCs need no DNS configuration. Requests use HTTPS on TCP port 443.
Traffic needs a route at three points:
-
Your VPCs' route tables route the environment’s CIDR block to the Transit Gateway.
-
The Transit Gateway’s route table routes the environment’s CIDR block to the environment’s attachment. A Transit Gateway that uses its default route table for association and propagation adds this route when the attachment becomes available.
-
The environment’s private route tables route your address ranges to the Transit Gateway. These routes carry the environment’s responses. They also carry the calls that its agents and MCP servers make to your VPCs.
Which of these you set up depends on how the environment was created:
| Item | Environment with the default egress | Environment created with an egress Transit Gateway |
|---|---|---|
Attachment to the Transit Gateway |
You create it. See Attach the environment’s VPC. |
Redpanda created it when it deployed the environment. |
Routes in the environment’s private route tables |
You add a route for each of your address ranges. |
None to add. Each private route table already sends all traffic outside the VPC to the Transit Gateway. |
For both kinds of environment, you add the routes in your VPCs. See Route your VPCs to the environment.
To check which kind you have, open the environment’s detail page in the Redpanda Cloud UI. An environment created with the Egress Transit Gateway ID (optional) field shows a Transit Gateway ID. For that field, see Create an Agentic Data Plane Environment.
For an environment with the default egress, you create and manage the attachment and its routes in your own AWS accounts. Redpanda Cloud doesn’t create, track, or remove them. Updating the environment’s infrastructure with rpk cloud byoc aws apply leaves the attachment and the routes that you added in place.
To give people access from their computers or from an office network, connect them to the environment’s VPC through a VPN instead. See Connect to a Private Environment from Your Computer.
Find the environment’s network details
Find the environment’s network ID, region, CIDR block, and AI Gateway URL in the Redpanda Cloud UI. For the steps, see Find the environment’s network details. You need only the values, not the peering commands that the Redpanda Cloud UI shows.
The commands on this page use these placeholders:
| Placeholder | Value |
|---|---|
|
The environment’s Redpanda network ID. The environment’s VPC carries the |
|
The environment’s region. |
|
The environment’s |
|
The ID of your Transit Gateway, which has a |
|
One private subnet of the environment’s VPC in each Availability Zone. See Attach the environment’s VPC. |
|
The ID of the environment’s attachment, which has a |
|
An address range behind the Transit Gateway that calls the environment, such as the CIDR block of one of your VPCs or a range that covers several of them. |
|
The ID of a route table in one of your VPCs. |
|
The ID of the Transit Gateway route table that your VPCs' attachments use. |
|
The environment’s |
Attach the environment’s VPC
Follow this section only for an environment with the default egress. If the environment’s detail page shows a Transit Gateway ID, Redpanda already attached the VPC, so skip to Route your VPCs to the environment.
Create the attachment with the AWS CLI, or declare it in Terraform.
If the Transit Gateway belongs to another AWS account, first share it with the environment’s account by using AWS Resource Access Manager. Unless the Transit Gateway accepts shared attachments automatically, its owner must then accept the attachment. See Amazon VPC attachments in the AWS documentation.
| This configuration refers to a third-party product. Specific UI elements may not be up to date. For current syntax, see the vendor documentation linked on this page. |
-
AWS CLI
-
Terraform
Run these commands with credentials for the AWS account that you deployed the environment into.
-
List the private subnets that hold the environment’s internal load balancer:
ENV_VPC_ID=$(aws ec2 describe-vpcs --region <region> \ --filters "Name=tag:Name,Values=network-<network-id>" \ --query 'Vpcs[0].VpcId' --output text) aws ec2 describe-subnets --region <region> \ --filters "Name=vpc-id,Values=$ENV_VPC_ID" \ "Name=tag:kubernetes.io/role/internal-elb,Values=1" \ --query 'Subnets[].[AvailabilityZone,SubnetId]' --output text | sortThe output lists the subnets by Availability Zone. An Availability Zone can have more than one. You can use any one of them.
-
Create the attachment with one subnet from each Availability Zone:
aws ec2 create-transit-gateway-vpc-attachment --region <region> \ --transit-gateway-id <transit-gateway-id> \ --vpc-id "$ENV_VPC_ID" \ --subnet-ids <subnet-id-1> <subnet-id-2> <subnet-id-3> \ --query 'TransitGatewayVpcAttachment.TransitGatewayAttachmentId' --output textReplace
<subnet-id-1>,<subnet-id-2>, and<subnet-id-3>with one subnet ID from each Availability Zone in the previous step’s output. The load balancer has an address in every Availability Zone, and the Transit Gateway reaches only the Availability Zones that the attachment includes.The command prints the attachment ID, which has a
tgw-attach-prefix. You use it as<attachment-id>in the next steps. -
Wait for the attachment to show
available. This can take a few minutes.aws ec2 describe-transit-gateway-vpc-attachments --region <region> \ --transit-gateway-attachment-ids <attachment-id> \ --query 'TransitGatewayVpcAttachments[0].State' --output text -
Add a route for each of your address ranges to each private route table in the environment’s VPC:
for route_table_id in $(aws ec2 describe-route-tables --region <region> \ --filters "Name=vpc-id,Values=$ENV_VPC_ID" "Name=tag:purpose,Values=private" \ --query 'RouteTables[].RouteTableId' --output text); do aws ec2 create-route --region <region> \ --route-table-id "$route_table_id" \ --destination-cidr-block <client-cidr> \ --transit-gateway-id <transit-gateway-id> doneThe environment has one private route table for each of its private subnets. Run the loop once for each
<client-cidr>.
This example assumes that the Transit Gateway is in the same AWS account as the environment.
variable "network_id" {
description = "The environment's Redpanda network ID."
type = string
}
variable "transit_gateway_id" {
description = "The ID of your Transit Gateway."
type = string
}
variable "client_cidrs" {
description = "The address ranges behind the Transit Gateway that call the environment."
type = list(string)
}
data "aws_vpc" "environment" {
tags = { Name = "network-${var.network_id}" }
}
# The private subnets that the environment's internal load balancer uses.
data "aws_subnets" "environment_private" {
filter {
name = "vpc-id"
values = [data.aws_vpc.environment.id]
}
tags = { "kubernetes.io/role/internal-elb" = "1" }
}
data "aws_subnet" "environment_private" {
for_each = toset(data.aws_subnets.environment_private.ids)
id = each.value
}
data "aws_route_tables" "environment_private" {
vpc_id = data.aws_vpc.environment.id
tags = { purpose = "private" }
}
locals {
# An attachment takes one subnet in each Availability Zone.
attachment_subnet_ids = [
for zone, ids in { for s in data.aws_subnet.environment_private : s.availability_zone => s.id... } : sort(ids)[0]
]
}
resource "aws_ec2_transit_gateway_vpc_attachment" "environment" {
transit_gateway_id = var.transit_gateway_id
vpc_id = data.aws_vpc.environment.id
subnet_ids = local.attachment_subnet_ids
tags = { Name = "environment-${var.network_id}" }
}
# Environment side: each private route table routes your ranges to the Transit Gateway.
resource "aws_route" "environment_to_clients" {
for_each = {
for pair in setproduct(data.aws_route_tables.environment_private.ids, var.client_cidrs) :
"${pair[0]}-${pair[1]}" => pair
}
route_table_id = each.value[0]
destination_cidr_block = each.value[1]
transit_gateway_id = var.transit_gateway_id
depends_on = [aws_ec2_transit_gateway_vpc_attachment.environment]
}
For resource arguments, see aws_ec2_transit_gateway_vpc_attachment and aws_route.
Set the variables, then run terraform init and terraform apply.
If your Transit Gateway doesn’t associate and propagate new attachments with its default route table, also associate the attachment with a Transit Gateway route table. Then add a route for the environment’s CIDR block, with the environment’s attachment as the target, to the Transit Gateway route tables that your VPCs' attachments use.
Route your VPCs to the environment
In each VPC that calls the environment, add a route to the environment’s CIDR block in the route tables of the subnets that your workloads run in. Use credentials for the account that owns the VPC.
aws ec2 create-route --region <region> \
--route-table-id <client-route-table-id> \
--destination-cidr-block <environment-cidr> \
--transit-gateway-id <transit-gateway-id>
If a route table already sends a range that contains the environment’s CIDR block to the Transit Gateway, skip that route table. For each other route table, replace <client-route-table-id> with its ID and run the command. For a VPC in another region, use that VPC’s region and the ID of that region’s Transit Gateway. In Terraform, use an aws_route resource with transit_gateway_id.
Reach the environment from another region
A Transit Gateway serves one region. To reach the environment from a VPC in another region, peer that region’s Transit Gateway with the one that the environment is attached to. Associate the peering attachment with a Transit Gateway route table on each side. A peering doesn’t propagate routes, so add static routes in these places:
-
In the other region’s Transit Gateway route table, route the environment’s CIDR block to the peering attachment.
-
In the environment’s region, in the Transit Gateway route table that the environment’s attachment uses, route the other region’s address range to the peering attachment. If the peering attachment uses a different route table, make sure that table has a route to the environment’s CIDR block.
-
In the other region’s VPC route tables, route the environment’s CIDR block to that region’s Transit Gateway.
-
For an environment with the default egress, in each private route table in the environment’s VPC, route the other region’s address range to the Transit Gateway. Skip this if a route there already covers the range.
For the steps, see Transit gateway peering attachments in the AWS documentation.
Verify the connection
-
Confirm that the Transit Gateway’s route table has an active route to the environment’s CIDR block:
aws ec2 search-transit-gateway-routes --region <region> \ --transit-gateway-route-table-id <transit-gateway-route-table-id> \ --filters "Name=route-search.exact-match,Values=<environment-cidr>" \ --query 'Routes[].[DestinationCidrBlock,Type,State]' --output textReplace
<transit-gateway-route-table-id>with the ID of the Transit Gateway route table that your VPCs' attachments use. The output shows the environment’s CIDR block with the stateactive. -
From a machine in one of the VPCs attached to the Transit Gateway, send a request to the environment’s AI Gateway:
curl -sS --connect-timeout 5 -o /dev/null -w '%{http_code}\n' <ai-gateway-url>Any HTTP status code means the network path works. A timeout means traffic doesn’t reach the environment.
For how workloads authenticate and what they need to call the environment, see Run agents and harnesses in your VPC. The same guidance applies to workloads in a VPC attached to the Transit Gateway.
Allow traffic from the environment to your services
To let agents and MCP servers reach a service in one of your VPCs, such as a database, allow inbound traffic from the environment’s CIDR block in the service’s security group. For an environment with the default egress, the route that you added in the environment’s private route tables must cover the service’s address.
Remove the attachment
For an environment with the default egress, delete the attachment when you no longer need it, and before you delete the environment. Redpanda Cloud doesn’t remove an attachment that you created. If the attachment still exists when you delete the environment, the deletion stalls at the step that removes the environment’s network, until you delete the attachment.
If you created the attachment and routes with Terraform, run terraform destroy for that configuration instead of the following steps.
-
If you keep the environment, delete the route for each of your address ranges from each private route table in the environment’s VPC. If you delete the environment, skip this step, because deleting the environment removes its route tables.
ENV_VPC_ID=$(aws ec2 describe-vpcs --region <region> \ --filters "Name=tag:Name,Values=network-<network-id>" \ --query 'Vpcs[0].VpcId' --output text) for route_table_id in $(aws ec2 describe-route-tables --region <region> \ --filters "Name=vpc-id,Values=$ENV_VPC_ID" "Name=tag:purpose,Values=private" \ --query 'RouteTables[].RouteTableId' --output text); do aws ec2 delete-route --region <region> \ --route-table-id "$route_table_id" \ --destination-cidr-block <client-cidr> doneRun the loop once for each
<client-cidr>. -
Delete the attachment:
aws ec2 delete-transit-gateway-vpc-attachment --region <region> \ --transit-gateway-attachment-id <attachment-id>Replace
<attachment-id>with the ID that you noted when you created the attachment. To find it again, runaws ec2 describe-transit-gateway-vpc-attachments. The attachment takes a minute or two to showdeleted.
For an environment created with Egress Transit Gateway ID (optional), don’t delete the attachment yourself. Redpanda created it, and removes it when you delete the environment.
For both kinds of environment, delete the routes to the environment’s CIDR block from your VPCs' route tables.
Troubleshooting
| Symptom | Action |
|---|---|
Requests from a workload in another VPC time out. |
Check each of these:
|
Requests work from the environment’s region, but requests from another region time out. |
Check the static routes on both Transit Gateway route tables. A peering doesn’t propagate routes. See Reach the environment from another region. |
The environment’s CIDR block doesn’t appear in the Transit Gateway’s route table. |
Check each of these:
|
Deleting an environment with the default egress doesn’t finish. |
The environment’s network can’t be removed while your attachment exists. Delete the attachment. The deletion then finishes on its own. See Remove the attachment. |
The environment’s hostname resolves, but to an address your network can’t reach. |
This is expected outside the networks connected to the Transit Gateway, because the hostname always resolves to the private addresses. Some corporate DNS resolvers drop public answers that contain private addresses. If yours does, ask your network team to allow the environment’s hostnames. |
Agents or MCP servers can’t reach a service in one of your VPCs. |
Allow inbound traffic from the environment’s CIDR block in the service’s security group. For an environment with the default egress, check that a route in the environment’s private route tables covers the service’s address. |