Transit Gateway
AWS Transit Gateway is a regional router that many VPCs attach to, so they can reach each other without a mesh of peering links. The AWS Baseline runs one per region in core-network, shares it with every account, and places every attachment in a route table for its isolation domain.
What it does
A VPC connects to a Transit Gateway through an attachment. Each attachment is associated with one route table, which decides where that attachment's traffic goes, and can propagate its own CIDR into route tables so others learn the way back. With default association and propagation on, every attachment reaches every other; with them off, nothing is reachable until routes are placed deliberately. A Transit Gateway can be shared across accounts with Resource Access Manager and peered with a Transit Gateway in another region.
How BuiltForProd uses it
The transit-gateway unit (registry module terraform-aws-modules/transit-gateway 3.3.1, listed by core/network/us-west-2) creates acme-usw2-tgw with ASN 64512, shares it organization-wide through RAM, auto-accepts shared attachments, and attaches the hub VPC. It is created with default association and propagation off and creates no routes. Routing belongs to a second unit.
transit-gateway-routes owns every route table. From isolation_domains in network.hcl (prod = [prod], nonprod = [sandbox, dev, staging] by default) it creates one table per domain plus shared for the hub and runner VPCs. A domain table learns only its own spokes plus the hub and runner; shared learns every attachment. Every table carries 0.0.0.0/0 to the hub, and the hub VPC's route tables send the plat OU address range and the runner CIDR back to the Transit Gateway. Every spoke reaches the hub's NAT, Client VPN and DNS resolver and the runner VPC. Domains cost nothing.
Production and non-production cannot reach each other, and two rules together are what make that true. The domain tables never learn each other's routes, so neither has a path to the other. And each domain table carries a blackhole route for the address range of every stage outside it, taken from the same IPAM output as the hub return routes. A blackhole is more specific than 0.0.0.0/0, so a packet aimed across the boundary is dropped at the Transit Gateway rather than following the default route to the hub and being sent back down the other domain's path. The drop happens in both directions, whatever a security group allows, and a stage the address map does not cover is skipped. The shared table is deliberately left alone: the hub, the CI runners and Client VPN users still reach every stage, and egress through the hub is unchanged.
Each workload account runs transit-gateway-attachment, which attaches its VPC and points the private route tables' default route at the Transit Gateway; skip_public_routes = true leaves the public subnets on the internet gateway for load balancers. Attachments are discovered from the owner's side by owning account, so a spoke needs no change when domains change; a stage that has not attached yet is picked up on the next apply. On an already-running deployment, changing domains re-associates attachments with a short connectivity blip per spoke.
Two options are built in and off by default in network.hcl. enable_network_firewall inserts Network Firewall endpoints into the hub path and turns on appliance mode for the hub attachment. enable_tgw_peering makes the transit-gateway-peering unit peer a non-home region's Transit Gateway with the home region's and install static routes per domain both ways, at about $36 per month per peering plus transfer; it is a no-op in the home region.
Terms you will see
| Term | Meaning |
|---|---|
| Attachment | The link between a VPC and the Transit Gateway. |
| Association | Which route table an attachment's traffic is looked up in. |
| Propagation | An attachment advertising its CIDR into a route table; set per table here. |
| Isolation domain | A named group of stages sharing one route table; prod and nonprod. |
| Blackhole route | A route whose packets are discarded; here, another domain's address range. |
| Centralized egress | Every spoke's internet-bound traffic leaving through the hub's NAT Gateways. |
| Appliance mode | Keeping both directions of a flow in one AZ, needed for firewall inspection. |
| Peering | A connection between Transit Gateways in different regions; static routes only. |
Where to read more
- AWS Baseline overview for the hub-and-spoke diagram.
- VPC for the subnets and route tables on each side.
- Client VPN for remote users entering through the hub.