Deploy an Amazon API Gateway API on an internal website using private endpoints and an Application Load Balancer
Created by Saurabh Kothari (AWS)
Environment: Production | Technologies: Web & mobile apps; Networking; Serverless; Infrastructure | AWS services: Amazon API Gateway; Amazon Route 53; AWS Certificate Manager (ACM) |
Summary
This pattern shows you how to deploy an Amazon API Gateway API on an internal website that’s accessible from an on-premises network. You learn to create a custom domain name for a private API by using an architecture that’s designed with private endpoints, an Application Load Balancer, AWS PrivateLink, and Amazon Route 53. This architecture prevents the unintended consequences of using a custom domain name and proxy server to help with domain-based routing on an API. For example, if you deploy a virtual private cloud (VPC) endpoint in a non-routable subnet, your network can’t reach API Gateway. A common solution is to use a custom domain name and then deploy the API in a routable subnet, but this can break other internal sites when the proxy configuration passes traffic (execute-api.{region}.vpce.amazonaws.com) to AWS Direct Connect. Finally, this pattern can help you meet organizational requirements for using a private API that’s unreachable from the internet and a custom domain name.
Prerequisites and limitations
Prerequisites
An active AWS account
A Server Name Indication (SNI) certificate for your website and API
A connection from an on-premises environment to an AWS account that’s set up by using AWS Direct Connect or AWS Site-to-Site VPN
A private hosted zone with a corresponding domain (for example, domain.com) that’s resolved from an on-premises network and forwards DNS queries to Route 53
A routable private subnet that’s reachable from an on-premises network
Limitations
For more information about quotas (formerly referred to as limits) for load balancers, rules, and other resources, see Quotas for your Application Load Balancers in the Elastic Load Balancing documentation.
Architecture
Technology stack
Amazon API Gateway
Amazon Route 53
Application Load Balancer
AWS Certificate Manager
AWS PrivateLink
Target architecture
The following diagram shows how an Application Load Balancer is deployed in a VPC that directs web traffic to a website target group or API Gateway target group based on Application Load Balancer listener rules. The API Gateway target group is a list of IP addresses for the VPC endpoint in API Gateway. API Gateway is configured to make the API private with its resource policy. The policy denies all calls that are not from a specific VPC endpoint. Custom domain names in API gateway are updated to use api.domain.com for the API and its stage. Application Load Balancer rules are added to route traffic based on the host name.
The diagram shows the following workflow:
A user from an on-premises network tries to access an internal website. The request is sent to ui.domain.com and api.domain.com. Then, the request is resolved to the internal Application Load Balancer of the routable private subnet. The SSL is terminated at the Application Load Balancer for ui.domain.com and api.domain.com.
Listener rules, configured on the Application Load Balancer, check for the host header.
a. If the host header is api.domain.com, the request is forwarded to the API Gateway target group. The Application Load Balancer initiates a new connection to API Gateway over port 443.
b. If the host header is ui.domain.com, the request is forwarded to the website target group.
When the request reaches API Gateway, the custom domain mapping configured in API Gateway determines the hostname and which API to run.
Automation and scale
The steps in this pattern can be automated by using AWS CloudFormation or the AWS Cloud Development Kit (AWS CDK). To configure the target group of the API Gateway calls, you must use a custom resource to retrieve the IP address of the VPC endpoint. API calls to describe-vpc-endpoints
Tools
Amazon API Gateway helps you create, publish, maintain, monitor, and secure REST, HTTP, and WebSocket APIs at any scale.
Amazon Route 53 is a highly available and scalable DNS web service.
AWS Certificate Manager (ACM) helps you create, store, and renew public and private SSL/TLS X.509 certificates and keys that protect your AWS websites and applications.
AWS Cloud Development Kit (AWS CDK) is a software development framework that helps you define and provision AWS Cloud infrastructure in code.
AWS PrivateLink helps you create unidirectional, private connections from your VPCs to services outside of the VPC.
Epics
| Task | Description | Skills required |
|---|---|---|
Create an SNI certificate and import the certificate into ACM. |
| Network administrator |
| Task | Description | Skills required |
|---|---|---|
Create an interface VPC endpoint in API Gateway. | To create an interface VPC endpoint, follow the instructions from Access an AWS service using an interface VPC endpoint in the Amazon Virtual Private Cloud (Amazon VPC) documentation. | Cloud administrator |
| Task | Description | Skills required |
|---|---|---|
Create a target group for your application. | Create a target group for the UI resources of your application. | Cloud administrator |
Create a target group for the API Gateway endpoint. |
| Cloud administrator |
Create an Application Load Balancer. |
| Cloud administrator |
Create listeners rules. | Create listener rules to do the following:
| Cloud administrator |
| Task | Description | Skills required |
|---|---|---|
Create a private hosted zone. | Create a private hosted zone for domain.com. | Cloud administrator |
Create domain records. | Create CNAME records for the following:
| Cloud administrator |
| Task | Description | Skills required |
|---|---|---|
Create and configure a private API endpoint. |
| App developer, Cloud administrator |
Create a custom domain name. |
| Cloud administrator |
Related resources
