This Guidance builds a serverless proxy that lets clients outside AWS reach your Amazon VPC Lattice services.

• Guidance for External Connectivity to Amazon VPC Lattice
  • Table of Content
  • Overview
    • Proxy engines
    • Cost
  • Prerequisites
    • Operating System
    • Supported AWS Regions
    • VPC Lattice infrastructure
    • DNS resolution configuration
  • Deployment Steps
  • Deployment Validation
  • Cleanup
  • Next Steps
    • Security
    • Scaling
    • Logging
    • Performance
  • License
  • Contributing
  • Authors

A VPC Lattice service gets a globally resolvable DNS name, but outside its VPC that name resolves to link-local IPs (169.254.171.x/24 within the IPv4 link-local range of RFC3927, and fd00:ec2:80::/64 within the IPv6 link-local range of RFC4291). Link-local addresses aren't routable. When a consumer inside an associated VPC resolves the service, the Nitro card intercepts the packets and routes them to the VPC Lattice service network ingress. So a client outside such a VPC can't connect directly.

Service network endpoints let you place ENIs in a VPC and reach service networks from outside it. They behave differently from Interface endpoints:

1. Each endpoint consumes multiple /28 IPv4 and /80 IPv6 ranges per Availability Zone (subnet).
2. Several VPC Lattice services can share a single IP from those ranges.

So you can't assume a service's IP is stable or unique. To handle this, each service associated to the network gets its own globally unique, externally resolvable domain name (resolving to a routable endpoint IP). For hybrid and cross-Region access, service network endpoints are the recommended approach: you only configure the matching DNS resolution (hybrid or in the consumer VPC) to target the endpoint.

For clients outside AWS with no private connectivity, the IPs used to reach services can change as services are added. This Guidance front-ends VPC Lattice with a proxy layer that resolves services dynamically on each request, so a changing backend IP never breaks your clients, and you avoid discovering endpoint IPs and updating static configuration yourself.

The proxy runs as a fleet of containers on ECS/Fargate. You choose the engine at deploy time with the ProxyEngine parameter (default nginx); both perform the same TLS passthrough, so the surrounding infrastructure is identical. Pick based on how much you expect to extend the proxy.

For how each engine works, how it's built, and how to edit it after deployment, see proxies/.

You are responsible for the cost of the AWS services used while running this Guidance. As of May 2026, running it with default settings in US East (N. Virginia) costs approximately $185.20 per month, broken down below. This is an estimate of the steady-state (idle) cost; verify for your Region and usage with the AWS Pricing Calculator.

You can reduce cost by using fewer Availability Zones (default is 3). We recommend at least 2 for high availability.

The CI/CD services typically stay within the AWS Free Tier at this Guidance's scale; review each pricing page for usage beyond it:

• Amazon ECR and AWS CodeBuild: pay-as-you-go for image storage and build minutes.
• AWS CodePipeline: one V1 active pipeline is free; the pipeline's S3 artifacts cost a few cents per month.
• AWS CodeCommit: 5 active users per month are free. Note that the CodePipeline and CodeBuild service roles count as active users, so large teams editing the proxy could exceed the free allowance ($1.00 per additional active user per month).

We recommend creating a Budget via AWS Cost Explorer to manage costs. Prices are subject to change; see each service's pricing page for details.

These instructions are optimized for Linux ARM64. Because the proxy runs on AWS Fargate (serverless), you don't manage any instance infrastructure.

Deploy this Guidance in any Region where Amazon VPC Lattice is available (it's the gating service). The other services have broader Region support.

This Guidance provides access to VPC Lattice services but does not create any VPC Lattice assets. You connect the ingress VPC to one or more service networks using either:

• a service network VPC association (1 per VPC), or
• one or more service network VPC endpoints (check the subnet prerequisites carefully, mainly for IPv4).

To test end-to-end consumption, use the templates and scripts in the testing folder, which has its own README covering how to deploy the test environment and validate reachability.

After the ingress VPC and proxy are created and the VPC is associated (or an endpoint created) to a service network, configure DNS so external clients reach the proxy and the proxy reaches VPC Lattice. You need two records:

• A public Route 53 record mapping the VPC Lattice custom domain name to the proxy's NLB DNS name.
• A private Route 53 record (in a hosted zone associated to the ingress VPC) mapping the custom domain name to the VPC Lattice-generated domain name. Services sharing a domain name under the same private hosted zone name don't need new zones.

For both records, we recommend an ALIAS record.

NOTE This Guidance does not create hosted zones or configure DNS. See dns-resolution.yml in the testing folder for an example.

1. Deploy the stack template. Key parameters:
   • AllowedIPv4Block (required) and AllowedIPv6Block (optional): CIDR blocks allowed to reach the public NLB.
   • VpcCidr: VPC IPv4 CIDR, defaults to 192.168.1.0/16.
   • ProxyEngine: proxy engine to deploy, nginx (default) or envoy (see Proxy engines).

aws cloudformation deploy --template-file ./guidance-stack.yml --stack-name guidance-vpclattice-external --parameter-overrides AllowedIPv4Block={YOUR_IPV4_BLOCK} AllowedIPv6Block={YOUR_IPV6_BLOCK} ProxyEngine=nginx --capabilities CAPABILITY_IAM

2. Configure DNS resolution so clients can consume the VPC Lattice services (see above).

The stack deploys three layers: the network path, the proxy that serves traffic, and a CI/CD pipeline to iterate on the proxy. The Lifecycle column shows what runs continuously, what only runs on demand, and what is kept when the stack is deleted:

NOTE On first-time ECS use, a service-linked role is created for you. If the stack fails because the role wasn't created in time, delete the failed stack and redeploy.

Confirm the deployment succeeded:

• In the AWS CloudFormation console, the stack shows CREATE_COMPLETE.
• In the Amazon ECS console, the cluster {STACK_NAME}-ProxyCluster-%random% has 3 running tasks.

To validate connectivity end-to-end (reach a VPC Lattice service through the proxy, signed or unsigned), use the testing folder. Its README covers both validating an existing service network and deploying a self-contained test service, plus the test-endpoint.sh helper script.

1. Delete the stack. This removes everything except the three retained resources below.

aws cloudformation delete-stack --stack-name guidance-vpclattice-external --region {YOUR_REGION}

2. Manually remove the retained resources if you no longer need them. These are kept on purpose so a stack deletion never destroys your images or customizations:

⚠️ Deleting the CodeCommit repository is irreversible and removes any proxy changes you committed. Clone or back it up first if you might redeploy later.

The proxy runs in private subnets and reaches AWS services through PrivateLink interface endpoints, so no NAT gateways are needed. A security group on the NLB restricts inbound traffic to your allowed CIDR blocks.

Because this is external connectivity over the public internet, the Guidance is TLS-only by default: the proxy exposes only port 443 and does TLS passthrough (reading the SNI without decrypting), keeping traffic encrypted end-to-end to the VPC Lattice service. Enforce HTTPS on your VPC Lattice services accordingly (an HTTPS listener with a certificate and custom domain). Port 80 is intentionally not exposed; if you need it, proxies/customizations/ shows how to add it back with the relevant caveats.

By design, the proxy handles only layer 4 connectivity and layer 3 security; all layer 7 concerns, including authentication and authorization, stay with VPC Lattice. Keep your service network and service authN/Z policies in place, since the proxy does not enforce them.

The ECS service autoscales on average CPU. Under load testing the proxy was CPU-bound at the chosen task sizes (see these independent measurements). Adjust the metric to fit your workload by editing guidance-stack.yml.

This Guidance uses Application Auto Scaling target tracking with the ECSServiceAverageCPUUtilization predefined metric. You can swap in your own metric via a CustomizedMetricSpecification. The default target is 70% CPU; adjust it in the template:

  ProxyScalableTarget:
    Type: AWS::ApplicationAutoScaling::ScalableTarget
    Properties: 
      MaxCapacity: 9
      MinCapacity: 3

  ProxyScalingPolicy:
    Type: AWS::ApplicationAutoScaling::ScalingPolicy
    Properties: 
      .....
      TargetTrackingScalingPolicyConfiguration:
        TargetValue: 70.0
        ScaleInCooldown: 60
        ScaleOutCooldown: 60

The ECS service uses Container Insights to capture performance data, written to CloudWatch Logs and viewable from the ECS or CloudWatch console.

We load-tested the Guidance against an AWS Lambda VPC Lattice service (with concurrency raised to 3000 from the 1000 base). The load profile was 5000 remote users generating ~3000 requests/second, sustained for 20 minutes after a 5-minute ramp-up. The setup:

The harness is the Distributed Load Testing on AWS solution; its template is also in this repo. The results below show each layer in the path: the test harness, the NLB, the proxy (ECS), VPC Lattice, and the Lambda target.

Harness

ECS proxy

Lambda target

VPC Lattice

This library is licensed under the MIT-0 License. See the LICENSE file.

See CONTRIBUTING for more information.

• Pablo Sánchez Carmona, Senior Network Specialist Solutions Architect, AWS
• Adam Palmer, Principal Solutions Architect, Amazon Leo