| name | migration-networking |
| description | Cross-region migration for networking services including AWS Transit Gateway, AWS Site-to-Site VPN, AWS Client VPN, and AWS Direct Connect. Covers Transit Gateway recreation with VPC and Direct Connect gateway attachments, VPN tunnel configuration with pre-shared keys, Client VPN endpoint migration with certificate handling, and Direct Connect Gateway association. |
Networking Services Migration
Security: Always ensure migrated resources meet or exceed the security configuration of the source resources. Refer to SECURITY.md for security requirements.
Data Classification
- Highly sensitive: Pre-shared keys, private keys, certificates — require encryption at rest and in transit, access logging, and restricted IAM permissions
- Sensitive: VPN configurations, network diagrams, IP addresses — require access controls and secure storage
- Encryption at rest: Enable AWS KMS encryption for Amazon CloudWatch Log Groups storing VPN/network logs. Store configuration files in Amazon S3 buckets with Block Public Access enabled, SSE-KMS encryption at rest, a bucket policy enforcing TLS-only access, versioning enabled, and access logging configured.
AWS Transit Gateway Migration Guide
Customer may need to create a new AWS Transit Gateway to establish connectivity between VPCs they have migrated to or between workloads in these VPCs and their on-premises data centers.
Prerequisites
- An understanding of the use case (VPC to VPC or VPC to on-premises)
- Is centralized inspection in use?
- Network diagram if possible
A. VPC to VPC connectivity
VPC A <--- Transit Gateway ---> VPC B
B. On-premises to VPC connectivity
on-prem <-- Direct Connect -- Direct Connect gateway -- Transit Gateway --> VPC
Note: Leverage VPC and Transit Gateway flow logs to troubleshoot connectivity issues:
AWS Site-to-Site VPN Migration Guide
Migration Overview
AWS Site-to-Site VPN connections are region-specific and must be recreated in the target region.
Step 1: Document Existing VPN Configuration
Gather the following information: * Customer Gateway configuration (IP address, BGP ASN) * Virtual Private Gateway or Transit Gateway attachment * VPN connection settings (static/dynamic routing) * Tunnel configuration (pre-shared keys, inside CIDR blocks) * Route propagation settings * Security group and network ACL rules
Export VPN Configuration:
aws ec2 describe-vpn-connections \
--region me-central-1 \
--query 'VpnConnections[*].[VpnConnectionId,CustomerGatewayId,VpnGatewayId,Type,State]' \
--output table
Step 2: Create Customer Gateway in Target Region
Input validation: Validate IP address format and BGP ASN range before calling the API.
if [[ ! $CGW_IP =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then echo "Invalid IP address format"; exit 1; fi
if [[ $BGP_ASN -lt 1 || $BGP_ASN -gt 4294967295 ]]; then echo "BGP ASN out of valid range"; exit 1; fi
aws ec2 create-customer-gateway \
--region eu-central-1 \
--type ipsec.1 \
--public-ip "$CGW_IP" \
--bgp-asn "$BGP_ASN" \
--tag-specifications 'ResourceType=customer-gateway,Tags=[{Key=Name,Value=recovery-cgw}]'
Step 3: Create Virtual Private Gateway or Transit Gateway
Option A: Virtual Private Gateway
aws ec2 create-vpn-gateway \
--region eu-central-1 \
--type ipsec.1 \
--amazon-side-asn YOUR-AMAZON-ASN \
--tag-specifications 'ResourceType=vpn-gateway,Tags=[{Key=Name,Value=recovery-vgw}]'
# Attach to VPC
aws ec2 attach-vpn-gateway \
--region eu-central-1 \
--vpn-gateway-id vgw-XXXXXXXXXXXX \
--vpc-id vpc-XXXXXXXXXXXX
Option B: Transit Gateway
aws ec2 create-transit-gateway \
--region eu-central-1 \
--description "Recovery Transit Gateway" \
--options AmazonSideAsn=YOUR-AMAZON-ASN
# Attach VPC to Transit Gateway
aws ec2 create-transit-gateway-vpc-attachment \
--region eu-central-1 \
--transit-gateway-id tgw-XXXXXXXXXXXX \
--vpc-id vpc-XXXXXXXXXXXX \
--subnet-ids subnet-XXXXXXXXXXXX subnet-YYYYYYYYYYYY
Step 4: Create VPN Connection
Security: Pre-shared keys are sensitive credentials. Do not pass them directly on the command line in production — they are visible in shell history and process listings. Store PSKs in AWS Secrets Manager and retrieve them programmatically. Use cryptographically strong, randomly generated keys (minimum 32 characters) and rotate them according to your security policies.
# Option 1 (recommended): Omit PreSharedKey to let AWS generate cryptographically strong keys
aws ec2 create-vpn-connection \
--region eu-central-1 \
--type ipsec.1 \
--customer-gateway-id cgw-XXXXXXXXXXXX \
--vpn-gateway-id vgw-XXXXXXXXXXXX \
--options TunnelOptions=[{TunnelInsideCidr=169.254.10.0/30},{TunnelInsideCidr=169.254.10.4/30}]
# Option 2: Retrieve PSK from Secrets Manager if you need a specific key
PSK=$(aws secretsmanager get-secret-value --secret-id vpn-psk-tunnel1 --query SecretString --output text)
aws ec2 create-vpn-connection \
--region eu-central-1 \
--type ipsec.1 \
--customer-gateway-id cgw-XXXXXXXXXXXX \
--vpn-gateway-id vgw-XXXXXXXXXXXX \
--options "TunnelOptions=[{TunnelInsideCidr=169.254.10.0/30,PreSharedKey=$PSK},{TunnelInsideCidr=169.254.10.4/30}]"
Note: If reusing tunnel configurations from the original VPN, retrieve pre-shared keys from AWS Secrets Manager rather than copying them from command history.
Step 5: Download Configuration File
aws ec2 describe-vpn-connections \
--region eu-central-1 \
--vpn-connection-ids vpn-XXXXXXXXXXXX \
--query 'VpnConnections[0].CustomerGatewayConfiguration' \
--output text > vpn-config.xml
Provide this configuration to your network team to update the customer gateway device.
Step 6: Enable Route Propagation
aws ec2 enable-vgw-route-propagation \
--region eu-central-1 \
--route-table-id rtb-XXXXXXXXXXXX \
--gateway-id vgw-XXXXXXXXXXXX
Step 7: Update Security Groups and Network ACLs
- Allow VPN traffic (UDP 500, UDP 4500, ESP protocol 50)
- Update security group rules to allow traffic from on-premises networks
- Verify network ACL rules permit VPN traffic
Step 8: Verification
Check VPN Status:
aws ec2 describe-vpn-connections \
--region eu-central-1 \
--vpn-connection-ids vpn-XXXXXXXXXXXX \
--query 'VpnConnections[0].VgwTelemetry[*].[OutsideIpAddress,Status,StatusMessage]' \
--output table
AWS Client VPN Migration Guide
Migration Overview
AWS Client VPN endpoints are region-specific and must be recreated in the target region.
Prerequisites
- AWS CLI configured with temporary credentials (via IAM roles, AWS SSO, or STS tokens)
- Access to both source and target regions
- Existing Client VPN endpoint in source region
Step 1: Export Client VPN Configuration
Retrieve the current endpoint configuration:
aws ec2 describe-client-vpn-endpoints \
--region source-region \
--client-vpn-endpoint-ids cvpn-endpoint-xxxxx \
--output json > client-vpn-config.json
Document key configuration details: * Client CIDR block * DNS servers * Split tunnel settings * Transport protocol * VPN port * Authentication options (certificate/Active Directory) * Connection logging preferences
Step 2: Export Certificates from ACM
Get server certificate ARN:
aws acm list-certificates --region source-region
Note: You cannot export private keys from ACM. If you don't have the original certificates, you'll need to generate new ones.
Step 3: Import Certificates to Target Region
Security: Private key files are highly sensitive. Store them with restricted permissions (chmod 600), delete local copies after import, and never commit them to version control.
If you have the original certificate files:
# Import server certificate
aws acm import-certificate \
--region target-region \
--certificate fileb://server-cert.pem \
--private-key fileb://server-key.pem \
--certificate-chain fileb://ca-chain.pem
# Import client certificate (if using mutual authentication)
aws acm import-certificate \
--region target-region \
--certificate fileb://client-cert.pem \
--private-key fileb://client-key.pem \
--certificate-chain fileb://ca-chain.pem
Step 4: Create Client VPN Endpoint in Target Region
aws ec2 create-client-vpn-endpoint \
--region target-region \
--client-cidr-block "10.0.0.0/16" \
--server-certificate-arn arn:aws:acm:target-region:ACCOUNT:certificate/xxxxx \
--authentication-options Type=certificate-authentication,MutualAuthentication={ClientRootCertificateChainArn=arn:aws:acm:target-region:ACCOUNT:certificate/xxxxx} \
--connection-log-options Enabled=true,CloudwatchLogGroup=client-vpn-logs,CloudwatchLogStream=connection-logs \
--dns-servers "10.0.0.2" \
--transport-protocol udp \
--vpn-port 443 \
--split-tunnel
Step 5: Associate Target VPC Subnets
Get subnet associations from source:
aws ec2 describe-client-vpn-target-networks \
--region source-region \
--client-vpn-endpoint-id cvpn-endpoint-xxxxx
Associate subnets in target region:
aws ec2 associate-client-vpn-target-network \
--region target-region \
--client-vpn-endpoint-id cvpn-endpoint-yyyyy \
--subnet-id subnet-xxxxx
Step 6: Configure Authorization Rules
List existing rules from source:
aws ec2 describe-client-vpn-authorization-rules \
--region source-region \
--client-vpn-endpoint-id cvpn-endpoint-xxxxx
Create authorization rules in target:
# Least-privilege: authorize specific groups only
aws ec2 authorize-client-vpn-ingress \
--region target-region \
--client-vpn-endpoint-id cvpn-endpoint-yyyyy \
--target-network-cidr "10.0.0.0/16" \
--access-group-id <AD-group-id>
Security: Always use --access-group-id to restrict access to specific Active Directory groups or SAML assertions. Using --authorize-all-groups grants access to all authenticated users and should only be used for testing.
Step 7: Apply Security Groups
Describe security groups from source:
aws ec2 describe-client-vpn-endpoints \
--region source-region \
--client-vpn-endpoint-ids cvpn-endpoint-xxxxx \
--query 'ClientVpnEndpoints[0].SecurityGroupIds'
Apply security groups in target:
aws ec2 apply-security-groups-to-client-vpn-target-network \
--region target-region \
--client-vpn-endpoint-id cvpn-endpoint-yyyyy \
--vpc-id vpc-xxxxx \
--security-group-ids sg-xxxxx
Step 8: Download New Client Configuration
aws ec2 export-client-vpn-client-configuration \
--region target-region \
--client-vpn-endpoint-id cvpn-endpoint-yyyyy \
--output text > client-config.ovpn
Manually add certificate and key to the .ovpn file (if using mutual authentication):
<cert>
[Client certificate content]
</cert>
<key>
[Client private key content]
</key>
Step 9: Test and Validate
- Distribute updated .ovpn configuration to test users
- Verify connectivity to resources in target VPC
- Test DNS resolution
- Validate split tunnel behavior
- Check connection logs in Amazon CloudWatch
Step 10: Cutover
- Communicate maintenance window to users
- Distribute new client configuration files
- Instruct users to import new profile
- Monitor connection logs for issues
- Decommission old endpoint once migration is confirmed
Important Notes
- Client CIDR blocks cannot overlap with VPC CIDR
- Maximum 5 target network associations per endpoint
- DNS servers must be reachable from associated subnets
- Connection logs require Amazon CloudWatch Logs permissions
- Certificate renewal must be planned (ACM certificates expire)
Documentation: * AWS Client VPN Administrator Guide * Client VPN Endpoints
AWS Direct Connect Migration Guide
Migration Overview
To establish connectivity between on-premises/data center and resources in a different region via a new Direct Connect link. Customers using DX Gateway may only need to associate the DXGW with a TGW or VGW in the working region.
Prerequisites
- Virtual Private Gateway (for single VPC connectivity) or Transit Gateway (for multiple VPCs) must exist in new region
- Amazon EC2/Amazon RDS/Amazon EKS resources must exist in new region
- Direct Connect Gateway (if applicable)
Documentation: * Create VGW * Create TGW
Migration Steps
Step 1: Create Direct Connect Connection in New Region
Working with Connections
Step 2: Create Virtual Interface
Create the appropriate virtual interface depending on your use case. Create VIF
Step 3: Associate VIF to Direct Connect Gateway
If applicable, associate the virtual interface to the Direct Connect gateway. Direct Connect Gateways
Step 4: Associate Gateway to Transit/Virtual Private Gateway
Apply correct allowed prefixes.
Step 5: Configure Customer Gateway
Verify correct Layer 2 (VLAN) and Layer 3 (BGP) configuration on customer gateway. VIF Router Configuration
Step 6: Configure Routing
Verify correct routing in VPC and Transit Gateway (if applicable).
Verify Direct Connect Connection
aws directconnect describe-connections --region <target-region>
Example Output:
{
"connections": [
{
"awsDevice": "EqDC2-123h49s71dabc",
"ownerAccount": "123456789012",
"connectionId": "dxcon-fguhmqlc",
"connectionState": "available",
"bandwidth": "1Gbps",
"location": "EqDC2",
"connectionName": "My_Connection",
"region": "us-east-1"
}
]
}
Security Guidelines
IAM Prerequisites
Before executing migration commands, verify your IAM role has the minimum required permissions. Follow least-privilege principles — scope permissions to specific resources using ARN conditions and aws:ResourceTag condition keys for access control.
Transit Gateway: ec2:CreateTransitGateway, ec2:CreateTransitGatewayVpcAttachment, ec2:CreateRoute, ec2:DescribeTransitGateways
Site-to-Site VPN: ec2:CreateVpnConnection, ec2:CreateCustomerGateway, ec2:CreateVpnGateway, ec2:AttachVpnGateway
Client VPN: ec2:CreateClientVpnEndpoint, ec2:AuthorizeClientVpnIngress, ec2:AssociateClientVpnTargetNetwork, acm:ImportCertificate
Direct Connect: directconnect:CreateDirectConnectGatewayAssociation, ec2:CreateTransitGatewayVpcAttachment
Service-Specific Security Controls
Transit Gateway:
- Use separate route tables to isolate VPC-to-VPC traffic from VPC-to-on-premises traffic
- Enable Transit Gateway flow logs for traffic analysis
- Tag all Transit Gateway resources for IAM condition-based access control
Site-to-Site VPN:
- Verify tunnel encryption uses AES-256:
aws ec2 describe-vpn-connections --vpn-connection-id vpn-xxx --query 'VpnConnections[0].Options.TunnelOptions[*].Phase1EncryptionAlgorithms'
- Confirm only authorized on-premises IPs can establish tunnels via Customer Gateway IP validation
- Use IKEv2 over IKEv1 for improved security
Client VPN:
- Restrict authorization rules to specific target network CIDRs instead of
0.0.0.0/0
- Apply security groups to the Client VPN endpoint:
aws ec2 apply-security-groups-to-client-vpn-target-network --client-vpn-endpoint-id cvpn-xxx --vpc-id vpc-xxx --security-group-ids sg-xxx
- Validate certificate expiration dates before migration
- Enable connection logging to Amazon CloudWatch
Direct Connect:
- Enable MACsec encryption on supported connections for Layer 2 encryption
- Use BGP authentication (MD5) on all BGP sessions
- Monitor BGP peer status and route advertisements
Error Handling Guidance
When executing AWS CLI commands in this guide, validate outputs before proceeding to the next step. For critical operations:
VPN_ID=$(aws ec2 create-vpn-connection \
--region eu-central-1 \
--type ipsec.1 \
--customer-gateway-id cgw-xxx \
--vpn-gateway-id vgw-xxx \
--query 'VpnConnection.VpnConnectionId' --output text 2>&1)
if [[ $? -ne 0 || -z "$VPN_ID" ]]; then
echo "ERROR: VPN creation failed: $VPN_ID"
exit 1
fi
Validate user-supplied inputs (IP addresses, ASNs, CIDR blocks) before passing to AWS CLI commands.
Monitoring and Logging
Enable comprehensive logging for all migrated networking resources:
- AWS CloudTrail: Verify that CloudTrail is enabled to log all VPN, Direct Connect, and certificate API operations
- Amazon VPC Flow Logs: Enable on all VPCs for network traffic analysis (use for both troubleshooting and security monitoring)
- Transit Gateway Flow Logs: Enable for cross-VPC traffic visibility
- Client VPN Connection Logs: Enable Amazon CloudWatch logging on all Client VPN endpoints
Note: References to "VPC" in this guide refer to the virtual private cloud resource. When referring to the service, use "Amazon VPC".
