aws-samples/sample-transit-gateway-attached-nfw-migration-guidance

# Migrating to Transit Gateway-Attached AWS Network Firewall This repository provides step-by-step migration guidance for moving from an AWS Network Firewall deployed in a customer-managed inspection VPC to a [Transit Gateway-attached Network Firewall](https://aws.amazon.com/about-aws/whats-new/2025/06/aws-network-firewall-native-attachment-transit-gateway/). It covers the two most common centralized inspection architectures and offers three migration methods for each: manual console steps, CloudFormation, and Terraform. ## Supported Architectures This repository covers migration guidance for two common centralized Network Firewall deployment patterns: | Architecture | Description | Directory | |---|---|---| | **Architecture 1** | Network Firewall deployed in a dedicated inspection VPC, with a separate egress VPC for centralized NAT Gateways | [architecture-1-separate-inspection-egress/](architecture-1-separate-inspection-egress/) | | **Architecture 2** | Network Firewall deployed in a combined inspection and egress VPC (firewall endpoints and NAT Gateways in the same VPC) | [architecture-2-combined-inspection-egress/](architecture-2-combined-inspection-egress/) | ### Architecture 1: Separate Inspection and Egress VPCs  ### Architecture 2: Combined Inspection and Egress VPC  ### Post-Migration End State (both architectures) Both architectures converge to the same end state: spoke VPCs routing through a Transit Gateway-attached Network Firewall to a dedicated egress VPC.  ### Differences between the two migrations Both architectures deploy the same new resources (a new egress VPC, a Transit Gateway-attached firewall, and three new Transit Gateway route tables) and use the same phased cutover approach. The differences are in the starting point and what you clean up at the end: - **Transit Gateway routing before migration:** Architecture 1 uses three Transit Gateway route tables (spoke, firewall, and egress) because traffic traverses two VPCs. Architecture 2 uses two Transit Gateway route tables (spoke and inspection) because the firewall and NAT Gateway are in the same VPC. - **Spoke route table default route target:** In Architecture 1, the spoke route table's default route points to the old inspection VPC attachment. In Architecture 2, it points to the old combined VPC attachment. - **Appliance mode:** Architecture 2's combined VPC Transit Gateway attachment uses appliance mode to maintain symmetric routing within the VPC. Architecture 1 does not need this because the firewall is in its own dedicated VPC. - **Cleanup:** For Architecture 1, you remove the old inspection VPC and old egress VPC (two VPCs). For Architecture 2, you remove the old combined VPC (one VPC). Both architectures converge to the same end state: spoke VPCs routing through a Transit Gateway-attached Network Firewall to a dedicated egress VPC. ## Migration Methods Each architecture includes three migration methods. Choose the one that best fits how you manage your infrastructure: | Method | Description | Architecture 1 | Architecture 2 | |---|---|---|---| | **Manual Console Steps** | Step-by-step instructions using the AWS Management Console | [Guide](architecture-1-separate-inspection-egress/manual-console-steps/) | [Guide](architecture-2-combined-inspection-egress/manual-console-steps/) | | **CloudFormation** | Automated migration using two coordinated CloudFormation stacks with phased parameter updates | [Guide](architecture-1-separate-inspection-egress/cloudformation-migration/) | [Guide](architecture-2-combined-inspection-egress/cloudformation-migration/) | | **Terraform** | Automated migration using Terraform with three phased root configurations | [Guide](architecture-1-separate-inspection-egress/terraform-migration/) | [Guide](architecture-2-combined-inspection-egress/terraform-migration/) | ### Using the migration guides with your existing infrastructure Each migration guide assumes a specific starting architecture. This repository includes CloudFormation templates that deploy the exact starting architecture for each pattern, so you can practice the full migration in a development or test account before migrating your production environment. If you deployed your original infrastructure using CloudFormation, the CloudFormation migration guides can import resource IDs directly from your existing stack using cross-stack references. If you deployed your infrastructure using ClickOps, Terraform, or another method, you can still use any of the migration methods. You will need to provide some resource IDs (such as your Transit Gateway ID and spoke VPC attachment IDs) as manual parameter inputs instead of cross-stack imports. Each guide explains which values are needed and where to find them. ## Starting Architecture Templates These templates deploy the starting architectures so you can run through the entire migration process end-to-end in a test account: | Architecture | Template | Description | |---|---|---| | Architecture 1 | [starting-architecture.yaml](architecture-1-separate-inspection-egress/cfn/starting-architecture.yaml) | Deploys two spoke VPCs, a dedicated inspection VPC with Network Firewall, a separate egress VPC with NAT Gateway, and a Transit Gateway connecting them | | Architecture 2 | [starting-architecture.yaml](architecture-2-combined-inspection-egress/cfn/starting-architecture.yaml) | Deploys two spoke VPCs, a combined inspection and egress VPC with Network Firewall and NAT Gateway, and a Transit Gateway connecting them | Both templates include EC2 instances in the spoke VPCs with AWS Systems Manager Session Manager access for connectivity testing during migration. ## Connecting to Spoke Instances for Validation Each migration step includes a validation using `curl checkip.amazonaws.com` from the spoke instances to verify which egress path is active. The instances have no public IP — connect through AWS Systems Manager Session Manager: aws ssm start-session --target --region us-east-1 # Once connected: curl checkip.amazonaws.com Alternatively, connect through the EC2 Console by selecting the instance and choosing **Connect** → **Session Manager**. If Session Manager shows the instance as unavailable, wait 1-2 minutes after launch for the SSM agent to register. ## VPC Quota Warning The default VPC quota per region is 5. Every migration in this repository temporarily creates a 5th VPC (the new egress VPC) while the old and new egress paths run in parallel. If the region's default VPC still exists, the migration will fail with `VpcLimitExceeded`. Before starting, either delete the default VPC in your target region or request a quota increase. # Check whether the default VPC exists in your target region aws ec2 describe-vpcs --region us-east-1 \ --filters "Name=is-default,Values=true" \ --query 'Vpcs[*].VpcId' --output text # Option A: request a quota increase (recommended for production accounts) aws service-quotas request-service-quota-increase \ --service-code vpc --quota-code L-F678F1CE \ --desired-value 10 --region us-east-1 # Option B: delete the default VPC (lab/POC accounts only -- make sure # nothing is running in it first) ## Security ## License This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file. ## Authors - [Lawton Pittenger](https://github.com/lawtonpittenger) - WW Security Solutions Architect - [Pal-Magnus Slatto](https://github.com/dev-slatto) - Senior Solutions Architect - [Frank Phillis](https://github.com/phillisf) - Senior Security Solutions Architect