Transitgateway Diagnostics

AWS Transit Gateway Diagnostics

When to use

Any AWS Transit Gateway investigation where the console alone is insufficient — TGW creation, route table configuration, VPC/VPN/DX attachments, route propagation, blackhole routes, inter-region peering, multicast, or performance troubleshooting.

Investigation workflow

Step 1 — Collect and triage

aws ec2 describe-transit-gateways --transit-gateway-ids <tgw-id>
aws ec2 describe-transit-gateway-attachments --filters Name=transit-gateway-id,Values=<tgw-id>
aws ec2 describe-transit-gateway-route-tables --filters Name=transit-gateway-id,Values=<tgw-id>
aws ec2 search-transit-gateway-routes --transit-gateway-route-table-id <rtb-id> --filters Name=state,Values=active,blackhole

Step 2 — Domain deep dive

aws ec2 describe-transit-gateway-vpc-attachments --filters Name=transit-gateway-id,Values=<tgw-id>
aws ec2 describe-transit-gateway-peering-attachments --filters Name=transit-gateway-id,Values=<tgw-id>
aws ec2 get-transit-gateway-route-table-associations --transit-gateway-route-table-id <rtb-id>
aws ec2 get-transit-gateway-route-table-propagations --transit-gateway-route-table-id <rtb-id>

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=ec2.amazonaws.com --max-results 20
aws ec2 describe-transit-gateway-multicast-domains --filters Name=transit-gateway-id,Values=<tgw-id>
aws cloudwatch get-metric-statistics --namespace AWS/TransitGateway --metric-name BytesIn --dimensions Name=TransitGateway,Value=<tgw-id> --start-time <start> --end-time <end> --period 300 --statistics Sum

Read references/transitgateway-guardrails.md before concluding on any Transit Gateway issue.

Tool quick reference

Gotchas: AWS Transit Gateway

• TGW route tables are completely separate from VPC route tables. A VPC route table entry pointing to a TGW only gets traffic TO the TGW. The TGW route table then determines where traffic goes NEXT. Both must be configured correctly for end-to-end connectivity.
• Attachments need a subnet in each AZ where you want connectivity. If a VPC attachment only has a subnet in AZ-a, instances in AZ-b of that VPC cannot reach the TGW. Always specify subnets in all AZs where instances reside.
• Route propagation vs static routes: propagated routes are automatically learned from attachments. Static routes are manually configured and take precedence over propagated routes for the same CIDR. Mixing both can cause confusion.
• Blackhole routes block traffic silently. They appear when an attachment is deleted but the route remains, or when manually created. Always check for blackhole routes when debugging connectivity failures.
• Inter-region peering has bandwidth limits and does NOT support route propagation. You must create static routes for peered TGWs. Peering also does not support multicast.
• Each attachment can only associate with ONE route table. Association determines which route table is used for routing decisions for traffic FROM that attachment. A route table can have many attachments associated.
• Appliance mode must be enabled on VPC attachments for stateful inspection appliances. Without it, return traffic may use a different AZ path, breaking stateful firewalls.
• MTU 8500 is supported within the same region for VPC attachments. VPN attachments support 1500 MTU. Inter-region peering supports 8500 MTU. Mismatched MTU causes packet drops.

Anti-hallucination rules

1. Always cite specific TGW IDs, attachment IDs, route table IDs, or API responses as evidence.
2. TGW route tables are NOT VPC route tables. Never confuse the two.
3. Inter-region peering does NOT support route propagation. Never suggest enabling propagation on peering attachments.
4. Each attachment associates with exactly ONE route table. Never suggest multiple associations.
5. Multicast support must be enabled at TGW creation. Never suggest enabling it on an existing TGW.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

24 runbooks