/sitetositevpn

Creating a Site-to-Site VPN Connection

Overview

Domain expertise for building an AWS Site-to-Site VPN connection: an encrypted IP Security (IPsec) tunnel between an on-premises network and a VPC. Covers the target gateway decision (virtual private gateway, transit gateway, or AWS Cloud WAN), the fixed order of the dependent resources, the customer gateway as metadata only, the distinct-ASN rule for a virtual private gateway, and choosing tunnel options at create time.

Does not cover the routing-type decision (the choosing-static-or-dynamic-routing reference), tunnel bandwidth sizing (the choosing-tunnel-bandwidth reference), the VPN Concentrator (its own reference), or applying the device configuration (the applying-the-customer-gateway-device-configuration reference). Settle routing type before running this procedure.

Execute commands using the AWS MCP server when connected (sandboxed execution, audit logging, observability). Fall back to the AWS CLI otherwise. Site-to-Site VPN is regional; pass --region {region} matching the VPC or transit gateway the connection terminates on.

Table of Contents

• Overview
• Workflow
• Decision: target gateway
• Creation order
• The customer gateway is metadata only
• Distinct ASNs for a virtual private gateway
• Tunnel options at create time
• Troubleshooting
• Procedure
• Security Considerations
• Additional Resources

Workflow

To build the connection end to end, follow the procedure exactly. See the Procedure section below.

The procedure covers:

• Choosing the target gateway based on how many VPCs and how much throughput the customer needs
• Creating the customer gateway resource that describes the on-premises device
• Creating or selecting the target gateway and attaching it to the VPC
• Enabling route propagation or adding routes, and updating the security group
• Creating the VPN connection with the chosen routing and tunnel options
• Surfacing the console link to verify status and download the device configuration

Decision: target gateway

Constraints:

• You MUST establish the target gateway first, tied to how many VPCs the customer must reach and how much throughput they need. It is the most consequential choice and gates bandwidth and Concentrator options
• You MUST tell the customer that a virtual private gateway cannot later be upgraded in place to Large tunnels or a Concentrator; reaching those means rebuilding on a transit gateway
• You SHOULD recommend a transit gateway when the customer needs more than one VPC or any feature a virtual private gateway does not support

Creation order

The connection only works after several resources are in place in the right order. Creating the VPN connection first and stopping there leaves traffic with nowhere to flow, and no single error points at the missing piece.

Constraints:

• You MUST create the resources in this order: customer gateway, target gateway attached to the VPC, route propagation or routes, security group rule, then the VPN connection
• You MUST confirm each resource before moving to the next
• You MUST confirm route propagation (or static routes) and the security group rule before declaring the connection ready

The customer gateway is metadata only

The customer gateway resource in AWS is only metadata: it gives AWS the device's public IP address and routing details. Customers read "gateway" and assume creating it configures their device. It does not; the device configuration is a separate step the customer owns.

Constraints:

• You MUST make clear that the customer gateway resource does not configure the on-premises device
• You SHOULD point the customer at the applying-the-customer-gateway-device-configuration reference for the device-side work

Distinct ASNs for a virtual private gateway

When the target gateway is a virtual private gateway, the Autonomous System Number (ASN) on the AWS side must differ from the customer gateway ASN, and the gateway must be attached to the VPC before anything routes.

Constraints:

• You MUST set distinct ASNs on the AWS side and the customer gateway side for a virtual private gateway target
• You MUST confirm the gateway is attached to the VPC before expecting routes to flow

Tunnel options at create time

Customers accept the default tunnel options at creation, then later need stronger algorithms and discover that modifying tunnel or connection options replaces the tunnel endpoints and interrupts connectivity.

Constraints:

• You MUST set strong tunnel options (AES-256, SHA-256 or higher, Diffie-Hellman group 14 or higher) at create time, when changing them is free, rather than after the customer is in production
• You MUST warn that modifying tunnel options later replaces the tunnel endpoints and briefly interrupts the connection

Troubleshooting

Connection created but traffic does not flow

Route propagation or the security group rule is missing. Confirm both (Creation order).

Connection never establishes on a virtual private gateway

The AWS-side and customer gateway ASNs match, or the gateway is not attached. Set distinct ASNs and attach (Distinct ASNs).

Customer waits for AWS to configure their device

The customer gateway resource is metadata only. The device configuration is the customer's separate step (The customer gateway is metadata only).

Customer needs more than 1.25 Gbps but built on a virtual private gateway

Large tunnels need a transit gateway. Rebuild the target gateway on a transit gateway (Decision).

Procedure

Overview

This procedure creates the customer gateway, the target gateway, the routing and security group configuration, and the VPN connection in the required order, then surfaces the console link to verify status and download the device configuration.

Parameters

• region (required): The AWS Region of the VPC or transit gateway.
• target_gateway_type (required): vpn-gateway, transit-gateway, core-network, or vpn-concentrator. If the customer says vpn-concentrator, redirect to the connecting-many-sites-with-a-vpn-concentrator reference.
• vpc_id (required for a virtual private gateway or transit gateway target): The VPC the gateway attaches to.
• transit_gateway_id (required if using an existing transit gateway): The transit gateway the connection terminates on. If creating a new transit gateway, this is captured from the create-transit-gateway response in Step 3.
• customer_gateway_ip (required): The public IP address of the on-premises device.
• routing_type (required): static or dynamic, settled in the choosing-static-or-dynamic-routing reference.
• customer_gateway_asn (required): The BGP ASN of the customer gateway. create-customer-gateway always requires --bgp-asn. For dynamic routing, use the real ASN of the on-premises device. For static routing, supply a placeholder (for example, 65000).
• aws_side_asn (required when creating a new virtual private gateway or transit gateway): The BGP ASN for the AWS side, which must differ from customer_gateway_asn. If the customer does not specify one, use the AWS default 64512.
• subnet_ids (required for a transit gateway target): One subnet ID per Availability Zone for the transit gateway VPC attachment. Note: if the transit gateway VPC attachment already exists (managed by the transitgateway skill or another team), skip creating it in Step 3 and use the existing attachment.

Constraints for parameter acquisition:

• You MUST ask for all required parameters upfront in a single prompt
• You MUST confirm the routing type is already decided before building

Steps

1. Verify dependencies

Constraints:

• You MUST confirm credentials with aws sts get-caller-identity
• You SHOULD recommend ephemeral IAM role-based credentials (instance profile, SSO session, or assumed role) rather than long-lived IAM user access keys for running these commands
• You MUST confirm the VPC (or transit gateway) and the on-premises device public IP exist before building

2. Create the customer gateway

Constraints:

• You MUST create the customer gateway describing the on-premises device:

  aws ec2 create-customer-gateway --type ipsec.1 --public-ip {customer_gateway_ip} \
    --bgp-asn {customer_gateway_asn} --region {region}

• If the customer's BGP ASN is larger than 2,147,483,647 (a 32-bit ASN), you MUST use --bgp-asn-extended instead of --bgp-asn:

  aws ec2 create-customer-gateway --type ipsec.1 --public-ip {customer_gateway_ip} \
    --bgp-asn-extended {customer_gateway_asn} --region {region}

  --bgp-asn accepts values 1 to 2,147,483,647; --bgp-asn-extended accepts 2,147,483,648 to 4,294,967,295.

• You MUST capture the CustomerGatewayId from the response

3. Create or select the target gateway and attach it

Constraints:

• You MUST create the chosen target gateway. For a virtual private gateway, create it and attach it to the VPC:

  aws ec2 create-vpn-gateway --type ipsec.1 --amazon-side-asn {aws_side_asn} --region {region}
  aws ec2 attach-vpn-gateway --vpn-gateway-id {vpn_gateway_id} --vpc-id {vpc_id} --region {region}

• For a transit gateway, create it (or select an existing one) and attach it to the VPC. The VPN connection is associated with the transit gateway in Step 5; the VPC attachment carries VPN traffic into the VPC:

  aws ec2 create-transit-gateway --options AmazonSideAsn={aws_side_asn} --region {region}
  aws ec2 create-transit-gateway-vpc-attachment --transit-gateway-id {transit_gateway_id} \
    --vpc-id {vpc_id} --subnet-ids {subnet_ids} --region {region}

• You MUST set an AWS-side ASN distinct from the customer gateway ASN for a virtual private gateway

4. Enable routing and update the security group

Constraints:

• You MUST enable route propagation on the subnet route table (or add static routes) so the subnet can reach the on-premises network
• You MUST update the security group to permit the on-premises traffic

5. Create the VPN connection

Constraints:

• You MUST create the connection against the target gateway and customer gateway, with the chosen routing type and tunnel options. For a virtual private gateway target, pass --vpn-gateway-id; for a transit gateway target, pass --transit-gateway-id instead:

  # Virtual private gateway target
  aws ec2 create-vpn-connection --type ipsec.1 --customer-gateway-id {customer_gateway_id} \
    --vpn-gateway-id {vpn_gateway_id} \
    --pre-shared-key-storage SecretsManager \
    --options "StaticRoutesOnly={true_if_static},TunnelOptions=[{Phase1EncryptionAlgorithms=[{Value=AES256}],Phase2EncryptionAlgorithms=[{Value=AES256}],Phase1IntegrityAlgorithms=[{Value=SHA2-256}],Phase2IntegrityAlgorithms=[{Value=SHA2-256}],Phase1DHGroupNumbers=[{Value=14}],Phase2DHGroupNumbers=[{Value=14}]},{Phase1EncryptionAlgorithms=[{Value=AES256}],Phase2EncryptionAlgorithms=[{Value=AES256}],Phase1IntegrityAlgorithms=[{Value=SHA2-256}],Phase2IntegrityAlgorithms=[{Value=SHA2-256}],Phase1DHGroupNumbers=[{Value=14}],Phase2DHGroupNumbers=[{Value=14}]}]" \
    --region {region}
  
  # Transit gateway target
  aws ec2 create-vpn-connection --type ipsec.1 --customer-gateway-id {customer_gateway_id} \
    --transit-gateway-id {transit_gateway_id} \
    --pre-shared-key-storage SecretsManager \
    --options "StaticRoutesOnly={true_if_static},TunnelOptions=[{Phase1EncryptionAlgorithms=[{Value=AES256}],Phase2EncryptionAlgorithms=[{Value=AES256}],Phase1IntegrityAlgorithms=[{Value=SHA2-256}],Phase2IntegrityAlgorithms=[{Value=SHA2-256}],Phase1DHGroupNumbers=[{Value=14}],Phase2DHGroupNumbers=[{Value=14}]},{Phase1EncryptionAlgorithms=[{Value=AES256}],Phase2EncryptionAlgorithms=[{Value=AES256}],Phase1IntegrityAlgorithms=[{Value=SHA2-256}],Phase2IntegrityAlgorithms=[{Value=SHA2-256}],Phase1DHGroupNumbers=[{Value=14}],Phase2DHGroupNumbers=[{Value=14}]}]" \
    --region {region}

• You MUST use --pre-shared-key-storage SecretsManager to store PSKs in AWS Secrets Manager so they are not returned as plain text in APIs like describe-vpn-connections; this incurs a small additional Secrets Manager cost per secret

• You MUST set strong tunnel options (AES-256, SHA-256 or higher, Diffie-Hellman group 14 or higher) rather than the AES-128 / SHA-1 / DH group 2 minimums

• You MUST supply two TunnelOptions objects, one per tunnel, since every connection has two tunnels; a single-element array leaves Tunnel 2 on the weak AES-128 / SHA-1 / DH group 2 defaults

• You SHOULD enable Site-to-Site VPN logs at create time so tunnel establishment and BGP events are captured from the start; see the monitoring-and-troubleshooting-tunnels reference for setup

6. Confirm and surface the console link

Constraints:

• You MUST confirm the connection and its tunnels reach the expected state:

  aws ec2 describe-vpn-connections --vpn-connection-ids {vpn_connection_id} --region {region}

• You MUST present the VPN connection console link, filling {region} and {vpnConnectionId} from the API response, and tell the customer to open it, confirm the connection, and download the device configuration:

  https://console.aws.amazon.com/vpc/home?region={region}#VpnConnectionDetails:VpnConnectionId={vpnConnectionId}

Example

Example input

{
  "region": "us-east-1",
  "target_gateway_type": "transit-gateway",
  "vpc_id": "vpc-0abc1234def567890",
  "subnet_ids": ["subnet-0abc1234def567890", "subnet-0fed9876cba543210"],
  "aws_side_asn": 64512,
  "customer_gateway_ip": "203.0.113.10",
  "routing_type": "dynamic",
  "customer_gateway_asn": 65010
}

Example output

Created customer gateway (203.0.113.10, ASN 65010) and the VPN connection on the transit gateway,
dynamic routing. Route propagation enabled and the security group updated.
Open the VPN connection in the console, confirm both tunnels, and download the device configuration:
https://console.aws.amazon.com/vpc/home?region=us-east-1#VpnConnectionDetails:VpnConnectionId=vpn-0abc1234def567890

Troubleshooting

Traffic does not flow after creation

Route propagation or the security group rule is missing. Confirm both (Step 4).

Connection never establishes on a virtual private gateway

ASNs match or the gateway is not attached. Set distinct ASNs and attach (Step 3).

Customer expects AWS to configure their device

The customer gateway is metadata. Hand off to the applying-the-customer-gateway-device-configuration reference.

Security Considerations

Creating the connection sets the authentication and encryption posture the tunnels run with, so the security choices belong at create time, when changing them is free.

Constraints:

• You MUST treat tunnel pre-shared keys (PSKs) as secrets: never pass them on the command line or store them in plaintext, store them in AWS Secrets Manager, and rotate them periodically; where the device supports it, recommend certificate-based authentication with AWS Private Certificate Authority instead of a static PSK
• You MUST set strong tunnel options (AES-256, SHA-256 or higher, Diffie-Hellman group 14 or higher) rather than the AES-128 / SHA-1 / DH group 2 minimums
• You MUST scope the security group rule to the specific on-premises CIDR blocks and protocols the workload needs, not 0.0.0.0/0
• You SHOULD set up monitoring by following the monitoring-and-troubleshooting-tunnels reference, which covers CloudWatch tunnel-state alarms, VPN logs, and CloudTrail audit logging
• You MUST enable encryption at rest on all log destinations (KMS on the CloudWatch Logs log groups holding the VPN/tunnel logs, and SSE-S3 or SSE-KMS on the S3 bucket holding the CloudTrail logs) since these logs can carry sensitive tunnel and connection details

Additional Resources

• Get started with AWS Site-to-Site VPN (AWS Site-to-Site VPN User Guide)
• Create an AWS Site-to-Site VPN connection (AWS Site-to-Site VPN User Guide)
• AWS Site-to-Site VPN single and multiple VPN connection examples (AWS Site-to-Site VPN User Guide)
• AWS Site-to-Site VPN customer gateway devices (AWS Site-to-Site VPN User Guide)
• Tunnel options for your AWS Site-to-Site VPN connection (AWS Site-to-Site VPN User Guide)