Networking & Content Delivery

Migrate from Transit VPC to AWS Transit Gateway

Amazon Virtual Private Cloud (Amazon VPC) provides you with the ability to create as many virtual networks as you need. It also provides different options for connecting these networks to each other and to non-AWS infrastructure, such as on-premises data centers, remote headquarters, or other offices. Most of you start this journey with a few VPCs. However, as you expand workloads on AWS, you scale the networks across multiple accounts and VPCs to meet your needs.

In 2014, we launched VPC peering, which offers point-to-point network connectivity between two VPCs. You can use VPC peering to create a full mesh network that uses individual connections between all networks. However, this can be very complex to manage as the number of your VPCs grows. In addition, for every VPC that needs on-premises connectivity you have to configure an AWS Direct Connect connection or an AWS Site-to-Site VPN connection. This process could take several weeks of implementation based on internal business operations, approvals, and maintenance window schedules.

In 2016 we introduced the transit VPC solution, which is a way to build a hub-and-spoke topology on Amazon VPCs, so that they can centralize edge connectivity. Transit VPC allows an easy way to implement shared services or packet inspection/replication in a VPC. It works across accounts and is easy to set up through an AWS CloudFormation stack. However, it leverages instance-based routing that increases costs while lowering availability and limiting the bandwidth.

In 2018, we released AWS Transit Gateway which offers the same advantages of transit VPC, but it is a managed service that scales elastically in a highly available product. Transit gateways are easy to set up and to use, and are designed to be highly scalable and resilient. By default, you can attach up to 5000 VPCs to each gateway and each attachment can handle up to 50 Gbits per second of traffic burst. You can also attach your AWS VPN connections to an AWS Transit Gateway today. With this in mind, we realized the need for developing an automation tool that would help you gracefully migrate from your existing transit VPC solution to the AWS Transit Gateway service. In this blog post we’ll describe the TGW Migrator tool and show you how to use it.

TGW Migrator Tool

The TGW Migrator tool provides a seamless migration path from the transit VPC solution to AWS Transit Gateway. It can also be used to quickly attach and enable routing between Amazon VPCs through AWS Transit Gateway, even if they are not a part of Transit VPC.

Aside from quickly and seamlessly migrating your Amazon VPCs to AWS Transit Gateway, this tool provides a quick option to roll back the migration if something goes wrong. A process that would manually take minutes to hours, depending on the scale of VPCs, is easily accomplished within a few seconds.

Before we get into the specifics of the tool, let’s go through some important caveats:

  • AWS Transit Gateway is a regional construct and this tool can only migrate VPCs in the same Region as a transit gateway.
  • This tool only helps in migration of all spoke VPCs in a Transit VPC to a Transit Gateway. It does not automate the migration of the edge network connectivity to on-premises through AWS Direct Connect or AWS Site-to-Site VPN. This portion must be done manually.

How to use this tool

To use the TGW Migrator tool, start by deploying an AWS CloudFormation stack. This provisions a new dedicated Amazon VPC, subnet, and Amazon EC2 instance that is used to run the TGW Migrator tool. You access the Python-based tool by using SSH to connect to the provisioned EC2 instance. To run this tool, use the following instructions.


  1. Click here to download and launch the CloudFormation stack (signing in to the console requires an AWS account, if you don’t have one, you can create one for free).
  2. In the CloudFormation console wait for the stack to complete deployment and then choose the Outputs tab for the stack. This section has the public IP address that you need to use SSH to connect to the TGW Migrator tool installed on the EC2 instance.
  3. Access the EC2 instance and then browse into the tool’s directory:
    cd tgw-migrator/
  4. Start the tool by running this command:

    You will see the following output after executing this command:

Instructions to migrate spoke VPCs from transit VPC to AWS Transit Gateway

If you have been using a transit VPC in AWS, then your architecture likely looks like the following diagram:

When you deploy the TGW Migrator tool, you can migrate the spoke VPCs of transit VPC to AWS Transit Gateway (assuming you have created AWS Transit Gateway by following these instructions) in a few steps:

  1. Initiate the tool as instructed in the earlier “Deployment” section. Now, choose C) Attach VPCs to the registered TGW. At some point during the attachment process, you will be asked to provide the Customer Gateway (CGW) public IP address of one of the hub routers in your transit VPC.
    Note: If you are running more than one CGW for redundancy, you can simply choose one of their IP addresses at random (for example, in this diagram you could use ).
    The tool will use this IP address to trace down all the connected VPNs and their respective spoke VPCs that need to be migrated to the transit gateway.
  2. After the tool has finished attaching the VPCs, run it again and choose D) Enable routing between attached VPCs. This step will move the traffic from the transit VPC as it inserts static routes into each of the VPCs’ main route tables pointing the AWS Transit Gateway as the target. (Static routes take preference over BGP propagated routes from the transit VPC.)
  3. If you need to, you can roll back the migration by initiating the tool again and choosing E) Disable routing between attached VPCs.

Under the Hood

Instructions to attach standalone VPCs to a transit gateway

The TGW Migrator tool can also be used to quickly attach any VPC to a transit gateway, not just spoke VPCs that are part of a transit VPC solution. To attach a standalone VPC, simply add a tag to the VPC, with the Key being attach-tgw and the Value being true. Note: These are case sensitive, so make sure to make them lowercase.

Tagging is illustrated in this screenshot:

After tagging the appropriate VPCs that you want to attach, follow these steps:

  1. Initiate the tool as instructed in the earlier “Deployment” section. Then choose C) Attach VPCs to registered TGW.
  2. After the tool has finished attaching the VPCs, run it again and choose D) Enable routing between attached VPCs. This step will start routing your traffic between VPCs over the TGW.
  3. If you need to roll back the migration, you can initiate the tool again and choose E) Disable routing between attached VPCs.

Enabling cross-account access for the TGW Migrator

You can optionally grant the TGW Migrator tool API access to secondary AWS accounts. The tool will automatically share a transit gateway with any secondary accounts through Resource Access Manager, attach the accounts’ VPCs to the AWS Transit Gateway, and enable routing between all VPCs in all accounts. Granting cross-account access can be done using the following steps:

  1. First, download and launch the transit gateway CloudFormation stack in a primary account.
  2. Use SSH to connect to the TGW Migrator tool in your EC2 instance and run the tool after the CloudFormation stack has fully deployed (step 1).
  3. Choose B) Share registered TGW with other AWS accounts. This will lead you through the steps to add any secondary AWS account IDs that you want the TGW Migrator to share the TGW with, attach VPCs from, and enable routing for.
  4. After you provide the secondary account numbers, the TGW Migrator tool will continuously poll for successful access to the secondary accounts. At this time you can download and launch the secondary account CloudFormation stack in any secondary accounts. This template will deploy appropriate IAM permissions for the tool in the primary account to make cross-account API calls.
  5. You should eventually see the TGW migrator go from a polling state to stating “Success!!! All secondary accounts are ready for deployment!” and return you to the main menu. At this point you can proceed with attaching VPCs, enabling routing through the tool. The tool which check each account automatically.


In this blog post, we walked you through the TGW Migrator tool functionalities. We described the detailed instructions for how to migrate spoke VPCs in a Transit VPC to AWS Transit Gateway along with the attachment of standalone VPCs to a transit gateway. This tool is easy to use and provides seamless migration from Transit VPC to AWS Transit Gateway with multi-account support.

We hope this blog post helps you in your migration journey to AWS Transit Gateway. If you have any questions or feedback, please leave a comment for us.

Happy networking at scale with multiple VPCs using AWS Transit Gateway!