Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Tutorial: Create an Amazon Transit Gateway using the Amazon command line

In this tutorial, you'll learn how to use the Amazon CLI to create a transit gateway and connect two VPCs to it. You'll create the transit gateway, attach both VPCs, and then configure the necessary routes to enable communication between the transit gateway and your VPCs.

Prerequisites

Before you begin, make sure you have:

Step 1: Create the transit gateway

When you create a transit gateway,Amazon creates a default transit gateway route table and uses it as the default association route table and the default propagation route table. The following shows an example create-transit-gateway request in the us-west-2 Region. Additional options were passed in the request. For more information about the create-transit-gateway command, including a list of the options you can pass in the request, see create-transit-gateway.

aws ec2 create-transit-gateway \
  --description "My Transit Gateway" \
  --region us-west-2     

The response then shows that the transit gateway was created. In the response, the Options that are returned are all default values.

{
    "TransitGateway": {
        "TransitGatewayId": "tgw-1234567890abcdef0",
        "TransitGatewayArn": "arn:aws:ec2:us-west-2:123456789012:transit-gateway/tgw-1234567890abcdef0",
        "State": "pending",
        "OwnerId": "123456789012",
        "Description": "My Transit Gateway",
        "CreationTime": "2025-06-23T17:39:33+00:00",
        "Options": {
            "AmazonSideAsn": 64512,
            "AutoAcceptSharedAttachments": "disable",
            "DefaultRouteTableAssociation": "enable",
            "AssociationDefaultRouteTableId": "tgw-rtb-abcdef1234567890a",
            "DefaultRouteTablePropagation": "enable",
            "PropagationDefaultRouteTableId": "tgw-rtb-abcdef1234567890a",
            "VpnEcmpSupport": "enable",
            "DnsSupport": "enable",
            "SecurityGroupReferencingSupport": "disable",
            "MulticastSupport": "disable"
        }
    }
}        

Step 2: Verify the transit gateway availability state

When you create a transit gateway, it's placed in a pending state. The state will change from pending to available automatically, but until it does you can't attach any VPCs until the state changes. To verify the state, run the describe-transit-gatweways command using the newly created transit gateway ID along with the filters option. The filters option uses Name=state and Values=available pairs. The command then searches to verify if the state of your transit gateway is in an available state. If it is, the response shows "State": "available". If it's in any other state then it is not yet available for use. Wait several minutes before running the command.

For more information about the describe-transit-gateways command, see describe-transit-gateways.

aws ec2 describe-transit-gateways \
  --transit-gateway-ids tgw-1234567890abcdef0 \
  --filters Name=state,Values=available

Wait until the transit gateway state changes from pending to available before proceeding. In the following response, the State has changed to available.

{
    "TransitGateways": [
        {
            "TransitGatewayId": "tgw-1234567890abcdef0",
            "TransitGatewayArn": "arn:aws:ec2:us-west-2:123456789012:transit-gateway/tgw-1234567890abcdef0",
            "State": "available",
            "OwnerId": "123456789012",
            "Description": "My Transit Gateway",
            "CreationTime": "2022-04-20T19:58:25+00:00",
            "Options": {
                "AmazonSideAsn": 64512,
                "AutoAcceptSharedAttachments": "disable",
                "DefaultRouteTableAssociation": "enable",
                "AssociationDefaultRouteTableId": "tgw-rtb-abcdef1234567890a",
                "DefaultRouteTablePropagation": "enable",
                "PropagationDefaultRouteTableId": "tgw-rtb-abcdef1234567890a",
                "VpnEcmpSupport": "enable",
                "DnsSupport": "enable",
                "SecurityGroupReferencingSupport": "disable",
                "MulticastSupport": "disable"
            },
            "Tags": [
                {
                    "Key": "Name",
                    "Value": "example-transit-gateway"
                }
            ]
        }
    ]
}

Step 3: Attach your VPCs to your transit gateway

Once your transit gateway is available, create an attachment for each VPC using the create-transit-gateway-vpc-attachment. You'll need to include the transit-gateway-id, the vpc-id, and the subnet-ids.

For more information about the create-transit-vpc attachment command, see create-transit-gateway-vpc-attachment.

In the following example, the command is run twice, once for each VPC.

For the first VPC run the following using the first vpc_id and subnet-ids:

aws ec2 create-transit-gateway-vpc-attachment \
  --transit-gateway-id tgw-1234567890abcdef0 \
  --vpc-id vpc-1234567890abcdef0 \
  --subnet-ids subnet-1234567890abcdef0

The response shows the successful attachment. The attachment is created in a pending state. There's no need to change this state as it changes to an available state automatically. This might take several minutes.

{
    "TransitGatewayVpcAttachment": {
        "TransitGatewayAttachmentId": "tgw-attach-1234567890abcdef0",
        "TransitGatewayId": "tgw-1234567890abcdef0",
        "VpcId": "vpc-1234567890abcdef0",
        "VpcOwnerId": "123456789012",
        "State": "pending",
        "SubnetIds": [
            "subnet-1234567890abcdef0",
            "subnet-abcdef1234567890"
        ],
        "CreationTime": "2025-06-23T18:35:11+00:00",
        "Options": {
            "DnsSupport": "enable",
            "SecurityGroupReferencingSupport": "enable",
            "Ipv6Support": "disable",
            "ApplianceModeSupport": "disable"
        }
    }
}

For the second VPC, run the same command as above using the second vpc_id and subnet-ids:

aws ec2 create-transit-gateway-vpc-attachment \
  --transit-gateway-id tgw-1234567890abcdef0 \
  --vpc-id vpc-abcdef1234567890 \
  --subnet-ids subnet-abcdef01234567890

The response for this command also shows a successful attachment, with the attachment currently in a pending state.

{
    {
    "TransitGatewayVpcAttachment": {
        "TransitGatewayAttachmentId": "tgw-attach-abcdef1234567890",
        "TransitGatewayId": "tgw-1234567890abcdef0",
        "VpcId": "vpc-abcdef1234567890",
        "VpcOwnerId": "123456789012",
        "State": "pending",
        "SubnetIds": [
            "subnet-fedcba0987654321",
            "subnet-0987654321fedcba"
        ],
        "CreationTime": "2025-06-23T18:42:56+00:00",
        "Options": {
            "DnsSupport": "enable",
            "SecurityGroupReferencingSupport": "enable",
            "Ipv6Support": "disable",
            "ApplianceModeSupport": "disable"
        }
    }
}

Step 4: Verify that the transit gateway attachments are available

Transit gateway attachments are created in a initial pending state. You won't be able to use these the attachments in your routes until the state changes to available. This happens automatically. Use the describe-transit-gateways command, along with the transit-gateway-id, to check the State. For more information about the describe-transit-gateways command, see describe-transit-gateways.

Run the following command to check the status. In this example, optional Name and Values filters fields are passed in the request:

aws ec2 describe-transit-gateway-vpc-attachments \
  --filters Name=transit-gateway-id,Values=tgw-1234567890abcdef0      

The following response shows that both attachments in an available state:

{
    "TransitGatewayVpcAttachments": [
        {
            "TransitGatewayAttachmentId": "tgw-attach-1234567890abcdef0",
            "TransitGatewayId": "tgw-1234567890abcdef0",
            "VpcId": "vpc-1234567890abcdef0",
            "VpcOwnerId": "123456789012",
            "State": "available",
            "SubnetIds": [
                "subnet-1234567890abcdef0",
                "subnet-abcdef1234567890"
            ],
            "CreationTime": "2025-06-23T18:35:11+00:00",
            "Options": {
                "DnsSupport": "enable",
                "SecurityGroupReferencingSupport": "enable",
                "Ipv6Support": "disable",
                "ApplianceModeSupport": "disable"
            },
            "Tags": []
        },
        {
            "TransitGatewayAttachmentId": "tgw-attach-abcdef1234567890",
            "TransitGatewayId": "tgw-1234567890abcdef0",
            "VpcId": "vpc-abcdef1234567890",
            "VpcOwnerId": "123456789012",
            "State": "available",
            "SubnetIds": [
                "subnet-fedcba0987654321",
                "subnet-0987654321fedcba"
            ],
            "CreationTime": "2025-06-23T18:42:56+00:00",
            "Options": {
                "DnsSupport": "enable",
                "SecurityGroupReferencingSupport": "enable",
                "Ipv6Support": "disable",
                "ApplianceModeSupport": "disable"
            },
            "Tags": []
        }
    ]
}         

Step 5: Add routes between your transit gateway and VPCs

Configure routes in each VPC's route table to direct traffic to the other VPC through the transit gateway using the create-route command along with the transit-gateway-id for each VPC route table. In the following example, the command is run twice, once for each route table. The request includes the route-table-id, the destination-cidr-block, and transit-gateway-id for each VPC route you're creating.

For more information about create-route command, see create-route.

For the first VPC's route table run the following command:

aws ec2 create-route \
  --route-table-id rtb-1234567890abcdef0 \
  --destination-cidr-block 10.2.0.0/16 \
  --transit-gateway-id tgw-1234567890abcdef0     

For the second VPC's route table run the following command. This route uses a route-table-id and destination-cidr-block different from the first VPC. However, since you're only using a single transit gateway, the same transit-gateway-id is used.

aws ec2 create-route \
  --route-table-id rtb-abcdef1234567890 \
  --destination-cidr-block 10.1.0.0/16 \
  --transit-gateway-id tgw-1234567890abcdef0

The response returns true for each route, indicating the routes were created.

{
    "Return": true
}

Step 6: Test the transit gateway

You can confirm that the transit gateway was successfully created by connecting to an EC2 instance in one VPC and pinging an instance in the other VPC, and then running the ping command.

If the ping is successful, your transit gateway is correctly configured and routing traffic between your VPCs.

Step 7: Delete the transit gateway attachments and transit gateway

When you no longer need the transit gateway, you can delete it. First, you must delete all attachments. Run the delete-transit-gateway-vpc-attachment command, using the transit-gateway-attachment-id for each attachment. After running the command, use delete-transit-gateway to delete the transit gateway. For the following, delete the two VPC attachments and the single transit gateway that were created in the previous steps.

Conclusion

You've successfully created a transit gateway, attached two VPCs to it, configured routing between them, and verified connectivity. This simple example demonstrates the basic functionality of Amazon VPC Transit Gateways. For more complex scenarios, such as connecting to on-premises networks or implementing more advanced routing configurations, see the Amazon VPC Transit Gateways User Guide.