Amazon Transit Gateway serves as a central hub that connects Amazon Virtual Private Clouds and on-premises networks through a cloud router model. Each new connection is made only once and the Transit Gateway handles routing between attachments. Terraform provides declarative control over Transit Gateway attachments, peering attachments, route tables, routes, and cross-account and cross-region workflows. Managing these resources as code enables repeatable hub-and-spoke topologies, auditability, and consistent attachment policies across environments.
What Transit Gateway Attachments Are
A Transit Gateway attachment connects a VPC to an existing Transit Gateway. The attachment is created on subnets that provide the attachment point where the Transit Gateway receives an IP address. Once attached, traffic from the VPC can be routed through the Transit Gateway to other VPCs, on-premises networks, or other Transit Gateways.
A Transit Gateway peering attachment connects two Transit Gateways to each other. Peering is a one-to-one relationship between two Transit Gateways. Much like a VPC attachment can be thought of as a network cable, a peering attachment plugs two Transit Gateways together and allows traffic to route between them. Unlike VPC attachments, peering attachments have two components, a requester and an accepter. Each attachment must be accepted prior to the attachment being completed.
Attachments to a Transit Gateway can be made from any account in an organization to enable cross-account connectivity. A Transit Gateway already exists somewhere in the AWS Organization and its identifier is used when creating transit gateway attachments.
Module Landscape for Terraform Transit Gateway Attachments
Several Terraform modules address Transit Gateway attachment patterns with different scopes and workflows.
| Module | Scope | Primary Capability |
|---|---|---|
| adamwshero terraform-aws-transit-gateway-attachment | Existing Transit Gateway | Create one or many attachments and routes |
| Gruntwork transit-gateway-attachment | Single Transit Gateway | Attach VPCs with configurable routing tables |
| Gruntwork transit-gateway-peering-attachment | Peering requester side | Create peering requester resources |
| plus3it terraform-aws-tardigrade-transit-gateway | Full TGW lifecycle | Manage TGW, route tables, routes, VPC attachments, associations and propagations |
The adamwshero module supports one or many of the following:
- Transit Gateway Attachments
- Transit Gateway Peering Attachment
- Transit Gateway Peering Attachment Accepter
- TGW Routes
- NAT Gateway routes
- Local Gateway routes
- Network Interface routes
- VPC Endpoint routes
- VPC Peering routes
- VPC Peering
- VPC peers are already in place
The module requires that a Transit Gateway already exists and uses its ID when creating attachments. For peering scenarios, at least two transit gateways are needed, a peer and an accepter.
The Gruntwork transit-gateway-attachment module creates attachments for a set of VPCs. Required inputs include an EC2 Transit Gateway identifier and a map of VPCs with their name and the subnet IDs that the Transit Gateway will attach to. The subnet IDs configured are the attachment point for the Transit Gateway. The module outputs the EC2 Transit Gateway Attachment identifier.
The Gruntwork transit-gateway-peering-attachment module creates transit gateway peering resources for the requester side of the connection to another transit gateway. The transit gateway can be in this account or in another account. If you need to peer multiple transit gateways, you will need to create multiple transit gateway peering attachments.
The plus3it tardigrade module manages a Transit Gateway, as well as its Route Tables, Routes, VPC attachments, Route Table associations and propagations, and VPC routes associated with the VPC attachments. It includes several submodules for different workflows and use cases:
- cross-account-vpc-attachment
- cross-region-peering-attachment
- peering-accepter
- peering-attachment
- route
- route-table
- vpc-accepter
Core Prerequisites and HCP Workflow
Before creating a transit gateway attachment, the HCP provider documentation lists required information. The prerequisites include:
- AWS account ID
- AWS transit gateway ID
- ARN of the resource share in AWS
- No active PrivateLink service is associated with the HVN
The HCP interface provides links and other onscreen assistance to help find this information. The HCP interface provides guided steps to help you transit gateway attachments. For instructions on how to create transit gateway attachments with Terraform, refer to the HCP provider documentation.
Adamwshero Module Configuration Patterns
The module can be used to create a Transit Gateway attachment for an existing transit gateway in an organization. A sample usage shows attachment definitions with VPC ID, transit gateway ID, and subnet IDs.
module "transit_gateway_attachment" {
source = "adamwshero/transit-gateway-attachment/aws"
version = "~> 1.5.0"
transit_gateway_attachments = {
attachment-1 = {
vpc_id = dependency.vpc.outputs.vpc_id
transit_gateway_id = local.account.locals.tgw_id_1
subnet_ids = dependency.vpc.outputs.private_subnets
}
}
transit_gateway_routes = {
"private_rtb" = {
route_table_ids = dependency.vpc.outputs.private_route_table_ids
destination_cidr_blocks = ["${local.common.cidr-1}", "${local.common.cidr-2}"]
transit_gateway_id = local.external_deps.dependency.settings.outputs.settings.transit_gateway_id
}
}
vpc_peering_routes = {
"private_pcx" = {
route_table_ids = dependency.vpc.outputs.private_route_table_ids
destination_cidr_blocks = ["${local.common.vpc-peer-cidr-1}"]
vpc_peering_connection_id = "${local.common.pcx-1}"
}
}
tags = {
Environment = local.env
Owner = "DevOps"
CreatedByTerraform = true
}
}
The module also supports creating transit gateway peering attachments between multiple transit gateways.
Gruntwork Attachment Module Inputs and Outputs
The Gruntwork transit-gateway-attachment module documents inputs with specific types.
| Name | Description | Type | Required |
|---|---|---|---|
| transitgatewayid | EC2 Transit Gateway identifier | string | yes |
| vpcs | A map of vpcs with their name and the subnet ids that the transit gateway will attach to. The subnet IDs configured here are the attachment point for the transit gateway. I.E. The transit gateway will have an IP on these subnets. | map(object({ vpcid = string vpcname = string subnet_ids = list(string) })) | yes |
Outputs:
| Name | Description |
|---|---|
| id | EC2 Transit Gateway Attachment identifier. |
Sample usage shows deployment via Git source with required variables for transitgatewayid and VPC map.
Tardigrade Module Submodule Workflows
The tardigrade module manages a Transit Gateway with comprehensive lifecycle control. The cross-account-vpc-attachment submodule creates a cross-account Transit Gateway VPC Attachment by managing the invite/accept interaction between two accounts. It requires two providers, one for each account. The providers must be different accounts, and must be using the same region. The Transit Gateway must be shared using the AWS Resource Access Manager.
The cross-region-peering-attachment submodule creates a cross-region Peering Attachment, managing the invite/accept workflow between the two regions. It requires two providers, one for each region. The providers may be the same or different account, but must be different regions.
Supporting submodules include peering-accepter to accept a peering attachment request, peering-attachment to send a peering attachment invite, route to create a Transit Gateway Route, route-table to create a Transit Gateway Route Table, and vpc-accepter to accept a VPC attachment request.
Observability and Best Practices
Operational visibility for Transit Gateway attachments can be achieved with CloudWatch metrics and attachment state information. Use OneUptime along with CloudWatch metrics to track bytes in/out and packet counts, and use AWS attachment state information to track attachment status.
Best practices for Transit Gateway with Terraform include:
- Use separate Transit Gateway route tables for different environments like production and development
- Enable DNS support on both the Transit Gateway and attachments
- Use dedicated subnets for Transit Gateway attachments rather than sharing them with workloads
- Plan your CIDR ranges to avoid overlaps across all connected VPCs
Transit Gateway with Terraform provides a scalable, manageable solution for connecting multiple VPCs. The hub-and-spoke model simplifies network architecture, and managing it as code ensures consistency and auditability. Whether you are connecting VPCs within a single account or across multiple accounts and regions, Transit Gateway attachments managed through Terraform give you full control over your network topology.
Conclusion
Terraform transit gateway attachment patterns range from single-account VPC attachments to advanced cross-account and cross-region peering workflows. The adamwshero module offers broad support for attachments, routes, and peering with an existing Transit Gateway. Gruntwork modules provide focused, opinionated constructs for VPC attachments and peering requester side resources. The plus3it tardigrade module delivers a complete TGW lifecycle with submodules for cross-account VPC attachments and cross-region peering attachments, including invite and accept handling.
Prerequisites remain consistent across workflows: an existing Transit Gateway identifier, correct subnet selection for attachment points, and for HCP integration, AWS account ID, transit gateway ID, resource share ARN, and no active PrivateLink service on the HVN. Peering requires explicit requester and accepter handling and is one-to-one per attachment.
When implemented with dedicated subnets, separate route tables per environment, DNS support enabled, and non-overlapping CIDRs, Terraform managed Transit Gateway attachments deliver a scalable hub-and-spoke network with auditability and repeatability. CloudWatch metrics and attachment state tracking provide ongoing operational confidence.