Overall Architecture | DNS and HTTPS Paths | AWS Direct Connect | Route 53 Resolver | Private API Gateway | Security and Troubleshooting
It's important to note here: this is not a "serial proxy chain" that all traffic passes through in sequence.
It is actually divided into two independent processes:
- DNS resolution path : Responsible for resolving the private domain name into the private IP of the VPC Endpoint.
- HTTPS access path : After the client obtains the private IP, it directly accesses the Interface VPC Endpoint through Direct Connect, and then transfers it to the Private API Gateway through AWS PrivateLink.
2. Overall Architecture
The examples below use the Tokyo Region, ap-northeast-1.
external company network
172.20.0.0/16
│
├─Business client
│ curl / Java / Postman / Business system
│
├─ External Company DNS
│ Conditional forwarding:
│ api.partner.example.com
│ ↓
│ 10.20.10.10
│ 10.20.20.10
│
└─ External corporate router
BGP
│
│ AWS Direct Connect
▼
Direct Connect Location
│
▼
Direct Connect Gateway
│
├─ Private VIF → VGW
│ or
└─ Transit VIF → Transit Gateway
│
▼
AWS VPC
10.20.0.0/16
│
┌──────────────┴──────────────┐
│ │
▼ ▼
Route 53 Resolver Interface VPC Endpoint
Inbound Endpoint com.amazonaws.ap-northeast-1.execute-api
UDP/TCP 53 TCP 443
10.20.10.10 10.20.11.x
10.20.20.10 10.20.21.x
│ │
▼ │
Route 53 Private Hosted Zone │
partner.example.com │
│ │
api.partner.example.com │
Alias → VPC Endpoint ─────────────┘
│
▼
API Gateway Private Domain
│
Domain Access Association
│
▼
API Mapping / Base Path
│
▼
Private REST API Gateway
│
▼
Lambda / AWS Service / VPC Link
Route 53 Resolver Inbound Endpoint receives DNS requests from the local network, while Private Hosted Zone saves private domain name records; Interface VPC Endpoint is the actual entry point for HTTPS data flows into API Gateway.
3. How does a complete request flow?
Suppose an external company system requests:
https://api.partner.example.com/v1/orders
1. DNS resolution process
The client first asks the external company for its internal DNS:
What is the IP of api.partner.example.com?
Conditional forwarding configured on external corporate DNS:
partner.example.com
→ 10.20.10.10
→ 10.20.20.10
These two IPs are the Route 53 Resolver Inbound Endpoint IPs in the AWS VPC.
DNS request goes:
External company DNS
→ Direct Connect
→ Transit Gateway/VGW
→ Resolver Inbound Endpoint
→ Route 53 VPC Resolver
→ Private Hosted Zone
Exists in Private Hosted Zone:
api.partner.example.com
A Alias
→ vpce-xxxxxxxx.execute-api.ap-northeast-1.vpce.amazonaws.com
What is finally returned is not the public IP of the API Gateway, but the private IP of the Interface VPC Endpoint ENI, for example:
10.20.11.45
10.20.21.82
The IP of the inbound endpoint is itself a VPC private IP, so the on-premises network must be routed to the VPC via Direct Connect or VPN. AWS requires each Resolver Endpoint to be configured with at least two IPs, and it is recommended to place them in different availability zones.
2. HTTPS access process
After DNS ends, the client establishes TCP 443 to the resolved VPC Endpoint private IP:
client
→ Direct Connect
→ TGW/VGW
→ VPC Endpoint ENI:443
→ AWS PrivateLink
→ API Gateway Private Custom Domain
→ API Mapping
→ Private REST API
Here Route 53 Resolver does not participate in HTTPS forwarding of . It is only responsible for previous DNS resolution.
Private API Gateway can only be accessed through API Gateway's Interface VPC Endpoint, and the API resource policy must also allow the specified VPC or VPC Endpoint.
4. Why do each service exist?
1. AWS Direct Connect
function
Direct Connect provides a private line connection between the external corporate network and AWS.
It is mainly responsible for:
- Route an external company's private network segment to an AWS VPC.
- Release the AWS VPC network segment to external companies.
- Hosts DNS requests.
- Hosts HTTPS API requests.
- Avoid business traffic passing through the public Internet.
- Provide relatively stable bandwidth and latency.
What Direct Connect is not responsible for
Direct Connect itself is not responsible for:
- DNS resolution.
- API authentication.
- API authorization.
- TLS certificate.
- API Gateway routing.
- Automatically encrypt all links.
Direct Connect is a "private circuit", but it cannot be simply equated to an "end-to-end encrypted circuit." When link encryption is required, consider MACsec where supported, or overlay Site-to-Site VPN/IPsec on Direct Connect. MACsec's must_encrypt mode stops transmission if encryption cannot be established; should_encrypt may fall back to unencrypted communication on failure.
2. Route 53 Resolver Inbound Endpoint
function
Enable external companies' own DNS servers to query DNS within the AWS VPC.
Without it, the external company's local DNS cannot be queried directly:
- Route 53 Private Hosted Zone。
- VPC internal private DNS name.
- Private records related to the VPC Endpoint.
After the Inbound Endpoint is created, an ENI will be created in the specified subnet and a fixed private IP will be assigned. The external company DNS forwards requests for corresponding domain names to these IPs.
Why can’t I directly ask the VPC’s VPC+2 DNS?
Common DNS addresses in VPC are similar:
VPC CIDR：10.20.0.0/16
VPC Resolver：10.20.0.2
But the external network should not directly use 10.20.0.2 as a normal DNS server. The standard entry point for hybrid networks is the Resolver Inbound Endpoint.
3. Route 53 Private Hosted Zone
function
Save private domain names and corresponding records, for example:
Private Hosted Zone:
partner.example.com
Record:
api.partner.example.com
A Alias
→ execute-api Interface VPC Endpoint
Private Hosted Zone only takes effect for the associated VPC and queries entered through the corresponding Resolver Inbound Endpoint. There is no need to expose the real API address to the public DNS.
4. Interface VPC Endpoint
Service name:
com.amazonaws.ap-northeast-1.execute-api
function
Interface VPC Endpoint is the private entrance of Private API Gateway within VPC.
It creates an ENI in each Availability Zone subnet selected:
AZ-a：10.20.11.45
AZ-c：10.20.21.82
HTTPS requests from external companies eventually reach these ENIs and then enter the API Gateway through AWS PrivateLink.
Interface Endpoint supports:
- Security Group。
- VPC Endpoint Policy。
- Multiple Availability Zones.
- Private DNS name.
- IPv4, IPv6 or dual stack, depending on service and configuration.
AWS recommends that Interface Endpoint select multiple subnets to improve availability.
5. API Gateway Private Custom Domain
For example:
api.partner.example.com
It solves two problems:
Friendly calling address
No need to use:
https://a1b2c3d4-vpce123.execute-api.ap-northeast-1.amazonaws.com/prod
Instead use:
https://api.partner.example.com/v1
TLS certificate
API Gateway is based on TLS SNI:
api.partner.example.com
Select the corresponding ACM certificate.
Must be created between Private Custom Domain and VPC Endpoint:
Domain Name Access Association
Otherwise, even if the DNS points to the Endpoint, API Gateway will not allow the Endpoint to use this private domain name.
6. Private API Gateway
Private API Gateway is the final API entrance.
It can continue to integrate:
- Lambda。
- AWS services.
- HTTP backend.
- Connect to ALB/NLB and intra-VPC services through VPC Link.
Private API does not mean "anyone through the dedicated line can call it." At least the following authorization layers also exist:
VPC Endpoint Security Group
VPC Endpoint Policy
Private Domain Resource Policy
Private API Resource Policy
API method level authentication
Backend business certification
Private API's resource policy can restrict sources through aws:SourceVpce or aws:SourceVpc. AWS recommends explicitly specifying a VPC or VPC Endpoint instead of allowing all origins.
5. Recommended address and resource planning
A specific example is given below.
| Project | Example |
|---|---|
| AWS Region | ap-northeast-1 |
| AWS VPC | 10.20.0.0/16 |
| External company network segment | 172.20.0.0/16 |
| Resolver Endpoint Subnet A | 10.20.10.0/24 |
| Resolver Endpoint Subnet C | 10.20.20.0/24 |
| Resolver IP A | 10.20.10.10 |
| Resolver IP C | 10.20.20.10 |
| execute-api Endpoint subnet A | 10.20.11.0/24 |
| execute-api Endpoint subnet C | 10.20.21.0/24 |
| Private domain name | api.partner.example.com |
| Private Hosted Zone | partner.example.com |
| API Stage | prod |
| Base Path | v1 |
It is recommended to separate the Resolver Endpoint and Interface Endpoint in a dedicated subnet to facilitate:
- Configure NACL independently.
- Separate Flow Logs.
- Identify costs.
- Independent control of routing and security groups.
- Subsequent replacement or expansion.
6. Phase One: Direct Connect Configuration
Scenario A: Only one VPC
Can use:
Direct Connect
→ Private VIF
→ Direct Connect Gateway
→ Virtual Private Gateway
→ VPC
Private VIF is mainly used to access VPC through private IP. When creating, you need to set parameters such as VLAN, client BGP ASN, BGP Peer IP, and MTU.
Option B: Multiple VPCs or shared network center
Recommended:
Direct Connect
→ Transit VIF
→ Direct Connect Gateway
→ Transit Gateway
→ Shared Services VPC
This is a more common design in enterprise environments because it can be followed by:
- DNS VPC。
- API VPC。
- Business VPC.
- Security Check VPC.
Unified access to Transit Gateway.
Transit VIF is used to connect to the Transit Gateway associated with the Direct Connect Gateway; the Direct Connect Gateway's allowed prefixes affect the AWS-side prefixes published to the local network.
Direct Connect configuration steps
1. Establish a physical or Hosted Connection
Can be:
- Dedicated Connection。
- Hosted Connection provided by partners.
Enterprise formal production environments should avoid having only one link. AWS's high availability model recommends using redundant connections from different devices and different Direct Connect Locations, and you can use the Resiliency Toolkit to test BGP failover.
2. Create Direct Connect Gateway
For example:
Name: dxgw-partner-api
Amazon side ASN: 64520
3. Create Transit Gateway
For example:
TGW ASN: 64530
Attach the VPC where the API is located to the TGW.
4. Associate DX Gateway and TGW
Allowed prefixes need to be set, for example:
10.20.0.0/16
Don't post randomly:
0.0.0.0/0
10.0.0.0/8
Unless this is an explicitly vetted web design.
5. Create Transit VIF
Key parameters include:
VLAN: 120
Customer ASN: 65010
AWS ASN: from DXGW
Customer Peer IP: 169.254.x.x/30
AWS Peer IP: 169.254.x.x/30
BGP MD5 Key: automatically generated or specified
MTU: 1500 or 8500
6. Configure local router
Publish locally to AWS:
172.20.0.0/16
AWS releases to local:
10.20.0.0/16
7. Configure TGW routing table
The AWS side requires at least:
172.20.0.0/16
→ Direct Connect Gateway/TGW association direction
The API VPC subnet route table requires:
172.20.0.0/16
→ Transit Gateway
External corporate router requires:
10.20.0.0/16
→ Direct Connect
Direct Connect most common errors
The route is only configured in one direction
For example:
External companies can go to 10.20.11.45
But AWS doesn't know how to get back to 172.20.0.0/16
The result is usually a TCP connection timeout.
CIDR overlap
For example:
External company: 10.20.0.0/16
AWS VPC：10.20.0.0/16
This situation cannot be solved by ordinary routing. It usually requires:
- Re-plan the address.
- NAT。
- Intermediary agent.
- PrivateLink service-based architecture.
MTU inconsistent
Private VIF can use 1500 or 9001, Transit VIF can use 1500 or 8500. Before enabling Jumbo Frame, make sure that the customer router, operator, DX link, TGW and intermediate equipment all support it. Otherwise, small requests may be normal and large requests may be stuck.
7. Phase 2: Create Route 53 Resolver Inbound Endpoint
1. Create a security group
For example:
sg-r53-inbound
Inbound rules:
UDP 53
Source: External company DNS server IP/32
TCP 53
Source: External company DNS server IP/32
For example:
UDP 53 ← 172.20.1.10/32
UDP 53 ← 172.20.1.11/32
TCP 53 ← 172.20.1.10/32
TCP 53 ← 172.20.1.11/32
Don't just open UDP 53. TCP may be used in the following situations:
- DNS response is too large.
- DNSSEC。
- Retry after UDP truncation.
- Behavior of some internal DNS products.
AWS explicitly requires the Inbound Endpoint security group to allow TCP and UDP 53.
2. Create Inbound Endpoint
Console path:
Route 53
→ Resolver
→ Inbound endpoints
→ Create inbound endpoint
Recommended settings:
Name: r53-inbound-partner-api
VPC: vpc-api-shared
Endpoint category: Default
Protocol: Do53
Security Group: sg-r53-inbound
Configure two AZs:
AZ-a
Subnet: subnet-dns-a
IP: 10.20.10.10
AZ-c
Subnet: subnet-dns-c
IP: 10.20.20.10
AWS requires a minimum of two IPs and recommends being in different Availability Zones; these IPs remain unchanged for the life of the Endpoint.
3. External company DNS configuration conditional forwarding
Windows DNS example:
Conditional Forwarder:
partner.example.com
Master Servers:
10.20.10.10
10.20.20.10
BIND example:
zone "partner.example.com" {
type forward;
forward only;
forwarders {
10.20.10.10;
10.20.20.10;
};
};
It is recommended to forward only the precise domain name:
partner.example.com
Don't configure unnecessarily:
.
com
example.com
Otherwise a large number of irrelevant DNS queries may be forwarded to AWS.
4. Verify DNS link
Test the AWS Resolver IP directly:
dig @10.20.10.10 api.partner.example.com
Then pass the normal DNS test of the external company:
dig api.partner.example.com
In the early stage, when the Private Hosted Zone has not been created, NXDOMAIN may be returned, which at least proves that the request has reached the Resolver.
8. Phase 3: Create execute-api Interface VPC Endpoint
1. Create an Endpoint security group
For example:
sg-vpce-execute-api
Inbound rules:
TCP 443
Source: 172.20.0.0/16
When it is more strict, only the business system network segment is allowed:
TCP 443
Source: 172.20.10.0/24
Don’t make the mistake of thinking that just allowing VPC CIDR is enough. The caller is located in an external company network. The source seen by VPC Endpoint is usually the original private IP of the external company, so the corresponding network segment must be allowed.
AWS requires the execute-api Endpoint security group to allow HTTPS 443 traffic.
2. Create Endpoint
Console path:
VPC
→ Endpoints
→ Create endpoint
Select:
Service category: AWS services
Service:
com.amazonaws.ap-northeast-1.execute-api
Type:
Interface
Configuration:
VPC: vpc-api-shared
Subnets:
subnet-endpoint-a
subnet-endpoint-c
Security Group:
sg-vpce-execute-api
Private DNS:
Enabled
It is recommended to select at least two Availability Zones. Only one subnet can be selected for each selected AZ, and AWS will create an Endpoint ENI in each subnet.
AWS CLI example:
aws ec2 create-vpc-endpoint \
--region ap-northeast-1 \
--vpc-id vpc-0123456789abcdef0 \
--vpc-endpoint-type Interface \
--service-name com.amazonaws.ap-northeast-1.execute-api \
--subnet-ids subnet-aaa subnet-ccc \
--security-group-ids sg-0123456789abcdef0 \
--private-dns-enabled
3. Impact of Private DNS switch
After turning on execute-api Private DNS:
*.execute-api.ap-northeast-1.amazonaws.com
Within this VPC, VPC Endpoint will be resolved first.
It is more convenient to call the default domain name of the Private API, but it also has side effects:
- When accessing the public API Gateway default
execute-apiURL in a VPC, it may be resolved to Private Endpoint. - Therefore, the public API may not be accessible through the default domain name.
- It is best to use your own Regional Custom Domain for public network API.
AWS documentation clearly reminds that after enabling the execute-api Endpoint private DNS, access to the public API through the default endpoint in the VPC may be affected.
9. Phase 4: Create Private REST API
1. Create API
Console:
API Gateway
→ Create API
→ REST API
→ Build
Select:
Endpoint type: Private
IP address type: Dualstack
VPC Endpoint IDs: vpce-xxxxxxxx
Private API Gateway here refers to REST API Private Endpoint. You can directly associate the execute-api VPC Endpoint when creating it. Once associated, API Gateway generates the calling DNS name related to the API ID and Endpoint ID.
CLI example:
aws apigateway create-rest-api \
--region ap-northeast-1 \
--name partner-private-api \
--endpoint-configuration '{
"types":["PRIVATE"],
"ipAddressType":"dualstack",
"vpcEndpointIds":["vpce-0123456789abcdef0"]
}'
2. Create resources and methods
For example:
/
└── orders
├── GET
└── POST
Or:
/health
/orders
/orders/{orderId}
After configuring Lambda or other integration, deploy to:
Stage: prod
3. API Resource Policy
It is recommended to only allow specified Endpoint:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/*"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/*",
"Condition": {
"StringNotEquals": {
"aws:SourceVpce": "vpce-0123456789abcdef0"
}
}
}
]
}
The meaning of this way of writing is:
- In principle, calls are allowed.
- But as long as the source Endpoint is not the specified Endpoint, it will be explicitly rejected.
AWS provides examples of Private API resource policies based on aws:SourceVpce and aws:SourceVpc.
After modifying the resource policy, the API should be redeployed.
10. Stage 5: Certificate and Private Custom Domain
1. Prepare ACM certificate
The certificate must cover:
api.partner.example.com
And the certificate must be located in the region where the API Gateway is located, for example:
ap-northeast-1
You can use:
api.partner.example.com
or where appropriate:
*.partner.example.com
Private Custom Domain supports wildcard certificates, but does not support the wildcard Custom Domain name itself; private domain names always use TLS 1.2.
Important issues with ACM public certificates
Even if the domain name is only used for the intranet, ACM still needs to verify domain name ownership when applying for an ACM public certificate.
DNS verification records must be discoverable by ACM from public DNS. Simply placing the CNAME in the Route 53 Private Hosted Zone cannot complete ACM public certificate verification.
Therefore, a safer approach is:
- Use a public domain name subdomain that is actually owned by the company, such as
api.partner.example.com. - Put only ACM verified CNAME in public DNS.
- The A record of the actual API is only placed in the Private Hosted Zone.
- Public network DNS does not need to publish the real address of the API.
2. Create Private Custom Domain
Console:
API Gateway
→ Custom domain names
→ Add domain name
Configuration:
Domain name:
api.partner.example.com
Endpoint type:
Private
Routing mode:
API mappings only
ACM Certificate:
Certificate covering api.partner.example.com
After creation, API Gateway will initially configure a policy that denies all access to the domain name, and requires manual authorization to specify the VPC Endpoint.
CLI example:
aws apigateway create-domain-name \
--region ap-northeast-1 \
--domain-name api.partner.example.com \
--certificate-arn arn:aws:acm:ap-northeast-1:111122223333:certificate/xxxxxxxx \
--security-policy TLS_1_2 \
--endpoint-configuration '{"types":["PRIVATE"]}' \
--policy file://domain-policy.json
11. Private Domain Resource Policy
The Private Domain itself must also allow the VPC Endpoint to be specified.
domain-policy.json：
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/*"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/*",
"Condition": {
"StringNotEquals": {
"aws:SourceVpce": "vpce-0123456789abcdef0"
}
}
}
]
}
Here is a very easy to overlook point:
For a request to be successful, at least the following must be true:
Private Domain Policy allows
Private API Policy allows
VPC Endpoint Policy allows
Method level authentication allows
AWS explicitly requires Private API and Private Custom Domain to configure resource policies separately.
12. Stage 6: Create API Mapping
For example, hope:
https://api.partner.example.com/v1/orders
Maps to:
API: partner-private-api
Stage: prod
Base Path: v1
Console:
API Gateway
→ Custom domain names
→ api.partner.example.com
→ API mappings
→ Configure mappings
Settings:
API: partner-private-api
Stage: prod
Path: v1
CLI：
aws apigateway create-base-path-mapping \
--region ap-northeast-1 \
--domain-name api.partner.example.com \
--domain-name-id abcd1234 \
--rest-api-id a1b2c3d4 \
--stage prod \
--base-path v1
Private Custom Domain must be mapped to specific Private API and Stage through API Mapping or routing rules.
13. Stage 7: Create Domain Name Access Association
This is the most easily missed step in the Private Custom Domain architecture.
Need to build:
Private Custom Domain
↕
execute-api VPC Endpoint
Console:
API Gateway
→ Custom domain names
→ api.partner.example.com
→ Resource sharing
→ Domain name access associations
→ Create
Select:
Domain ARN:
arn:aws:apigateway:ap-northeast-1:111122223333:
/domainnames/api.partner.example.com+domain-id
VPC Endpoint:
vpce-0123456789abcdef0
CLI：
aws apigateway create-domain-name-access-association \
--region ap-northeast-1 \
--domain-name-arn \
arn:aws:apigateway:ap-northeast-1:111122223333:/domainnames/api.partner.example.com+abcd1234 \
--access-association-source vpce-0123456789abcdef0 \
--access-association-source-type VPCE
It may take about 15 minutes for the association to become available after it is created, and it may also take a while for the creation of the Private Custom Domain itself or the update of the certificate.
14. Stage 8: Configure VPC Endpoint Policy
Endpoint Policy control:
It is not recommended to maintain Full Access for long periods of time.
For example, only Domain and API are allowed to be specified:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:ap-northeast-1:111122223333:/domainnames/api.partner.example.com+abcd1234",
"arn:aws:execute-api:ap-northeast-1:111122223333:a1b2c3d4/*"
]
}
]
}
You can also use execute-api:viaDomainArn to restrict access to only the specified Private Custom Domain. AWS gives an example of restricting VPC Endpoint Policy by private domain name, API, and method.
Authorization Header Notes
Endpoint Policy first evaluates the request's Authorization header:
- No Authorization: Evaluated by anonymous Principal.
- Correct SigV4: Identified as IAM Principal.
- Error SigV4: Direct rejection.
- Bearer Token/JWT: Endpoint Policy is usually still evaluated based on anonymous Principal.
Therefore, if the business layer uses OAuth/JWT/Lambda Authorizer, do not mistakenly request an IAM User in Endpoint Policy, otherwise legitimate JWT requests may be blocked by Endpoint Policy.
15. Stage 9: Create Private Hosted Zone and Alias records
1. Create Private Hosted Zone
Recommended to create:
partner.example.com
and associate a VPC containing the following resources:
- Resolver Inbound Endpoint。
- execute-api VPC Endpoint。
At least the Private Hosted Zone must be associated with the VPC where the Inbound Endpoint is located, so that the Resolver can use the Hosted Zone to respond to external queries.
CLI：
aws route53 create-hosted-zone \
--name partner.example.com \
--caller-reference "$(date +%s)" \
--hosted-zone-config Comment="Partner private API",PrivateZone=true \
--vpc VPCRegion=ap-northeast-1,VPCId=vpc-0123456789abcdef0
2. Create Alias records
Console:
Route 53
→ Hosted zones
→ partner.example.com
→ Create record
Configuration:
Record name:
api
Record type:
A
Alias:
On
Route traffic to:
Alias to VPC endpoint
Region:
ap-northeast-1
Endpoint:
vpce-0123456789abcdef0
The Route 53 Alias target of the Private API Custom Domain should be the execute-api Interface VPC Endpoint, not the Lambda, API ID, or Resolver Endpoint.
CLI record example:
{
"Changes": [
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "api.partner.example.com",
"Type": "A",
"AliasTarget": {
"DNSName": "vpce-0123456789abcdef0.execute-api.ap-northeast-1.vpce.amazonaws.com",
"HostedZoneId": "VPC_ENDPOINT_HOSTED_ZONE_ID",
"EvaluateTargetHealth": false
}
}
}
]
}
Then:
aws route53 change-resource-record-sets \
--hosted-zone-id Z0123456789ABCDEFG \
--change-batch file://api-alias.json
If the Endpoint uses IPv6 or Dualstack, add AAAA records according to actual needs.
16. What does the external company ultimately need to configure?
Outside companies typically only need access to the following information.
Network information
AWS target network segment:
10.20.0.0/16
Agreement:
DNS UDP/TCP 53
HTTPS TCP 443
DNS information
Forwarding domain:
partner.example.com
DNS target:
10.20.10.10
10.20.20.10
API information
Base URL:
https://api.partner.example.com/v1
Health check:
GET /health
Business API:
GET /orders
POST /orders
Certification information
Depends on the design, for example:
- OAuth2/JWT。
- API Gateway Lambda Authorizer。
- AWS IAM SigV4。
- HMAC signature.
- Cognito Token。
- Business username/password, not recommended to be used alone.
- API Key is only suitable for metering and Usage Plan and should not be used as the only security authentication.
Private API currently does not support the mutual TLS function of API Gateway, so B2B two-way certificate authentication cannot be configured directly according to the mTLS method of public network Regional API. You can use IAM SigV4, JWT/Lambda Authorizer, application layer certificate verification, or redesign the front-end proxy layer.
17. Complete security control layer
It is recommended to divide the controls into six layers.
Layer 1: Direct Connect routing
Only publish necessary network segments:
External Company → AWS:
10.20.0.0/16
AWS → External Company:
172.20.10.0/24
Try not to publish entire enterprise network segments to each other.
Second layer: Resolver Endpoint security group
Only official DNS servers from external companies are allowed:
UDP/TCP 53
172.20.1.10/32
172.20.1.11/32
Do not allow all clients to query the Resolver directly.
The third layer: execute-api Endpoint security group
Only business system source network segments are allowed:
TCP 443
172.20.10.0/24
Layer 4: VPC Endpoint Policy
Only allowed:
Specify Private Domain
Specify API
Specify method or stage
Layer 5: Domain and API Resource Policy
Also passed:
aws:SourceVpce
Limit the specified endpoint.
When you need to further restrict external origin IPs, the Private API resource policy can be used:
aws:VpcSourceIp
Because VPC Endpoint may rewrite the network layer source IP, aws:VpcSourceIp is used to determine the original request source address.
Level 6: Method-level and business-level certification
For example:
OAuth2 Access Token
JWT Claims
Partner ID
Scope
Order permissions
Call frequency
business audit
Being reachable by the network does not mean that the business has access.
18. Key points to note in DNS design
1. Split-Horizon DNS
Assume that the external company is already managed internally:
example.com
AWS creates again:
Private Hosted Zone: example.com
Then split DNS and authority conflicts may occur.
It is more recommended to divide dedicated subdomains:
aws-api.example.com
partner-api.example.com
private.example.com
Then only conditionally forward this subdomain.
2. Private Hosted Zone association error
if:
Resolver Endpoint in VPC-A
Private Hosted Zone is only associated with VPC-B
The Inbound Endpoint may not resolve the Hosted Zone as expected.
The simplest way is:
Private Hosted Zone
Also associate the VPC where the Resolver Endpoint is located
And the VPC where the execute-api Endpoint is located
It's easier if both are in the same VPC.
3. Do not write the Resolver IP into the business A record
Error:
api.partner.example.com
A → 10.20.10.10
10.20.10.10 is a DNS server, not an API server.
Correct:
api.partner.example.com
A Alias → execute-api VPC Endpoint
4. TTL and caching
After the Private Hosted Zone record changes, external corporate DNS and clients may continue to use cache.
When testing you can:
dig api.partner.example.com
Observe TTL, and clean up:
- Windows DNS cache.
- Linux
systemd-resolvedcache. - Java JVM DNS cache.
- Enterprise DNS caching.
19. High availability design
Direct Connect
For production environments, at least consider:
DX Connection A
DX Connection B
different devices
Best Different DX Location
and prepare:
Site-to-Site VPN Backup
Use BGP attributes to control active and standby.
Resolver Inbound Endpoint
At least two AZs:
10.20.10.10
10.20.20.10
External DNS is configured with two forwarders at the same time.
Each Resolver Endpoint IP can handle a large number of queries; current AWS documentation states that a single IP can handle up to approximately 10,000 UDP DNS QPS when conditions are suitable, but actual capacity is affected by query size, protocol, response latency, and security group connection tracking.
Interface VPC Endpoint
At least two AZs:
Endpoint ENI A
Endpoint ENI C
Route 53 Alias will return the corresponding Endpoint address.
AWS also clearly recommends that Private Custom Domain use VPC Endpoints in at least two availability zones.
API Gateway
API Gateway itself is a regional hosting service and does not require the deployment of EC2-style active and standby instances. However, the backend still needs to be considered separately:
- Lambda concurrency.
- VPC Link。
- ALB/NLB has multiple AZs.
- The database has multiple AZs.
- Cross-region disaster recovery.
20. Monitoring and logging
It is recommended to enable at least the following items.
Direct Connect
Monitor:
ConnectionState
VirtualInterfaceBpsIngress
VirtualInterfaceBpsEgress
VirtualInterfacePpsIngress
VirtualInterfacePpsEgress
BGP status
And execute BGP Failover Test to confirm that the backup link can actually take over. The AWS Resiliency Toolkit supports verifying redundant routes by temporarily closing the BGP session.
Route 53 Resolver
Enable:
Resolver Query Logging
CloudWatch Resolver Endpoint Metrics
Querying the logs can help confirm:
- Whether a domain name query has been received.
- Which VPC the query comes from.
- Query type.
- Return results.
It should be noted that repeated queries hit by the Resolver cache usually do not appear in the Query Log as each independent query.
VPC
Enable:
VPC Flow Logs
Highlights:
- Resolver Endpoint ENI。
- execute-api Endpoint ENI。
- TGW related traffic.
- ACCEPT/REJECT。
- Source IP, destination IP, port.
API Gateway
Enable:
Access Logs
Execution Logs
Detailed Metrics
AWS X-Ray, on demand
It is recommended that access logs contain at least:
$requestId
$context.identity.sourceIp
$context.domainName
$context.httpMethod
$context.resourcePath
$context.status
$context.responseLength
$context.integrationErrorMessage
21. Standard test sequence
Don't just run curl initially, test by layer.
Step 1: Check BGP and Routing
The external router confirms that it has learned:
10.20.0.0/16
The AWS side confirms that it has learned:
172.20.0.0/16
Step 2: Test the Resolver Endpoint directly
dig @10.20.10.10 api.partner.example.com A
dig @10.20.20.10 api.partner.example.com A
Step 3: Pass formal DNS testing by an external company
dig api.partner.example.com A
The Endpoint private IP should be returned.
Step 4: Test TCP 443
nc -vz api.partner.example.com 443
Or:
telnet api.partner.example.com 443
Step Five: Check the TLS Certificate
openssl s_client \
-connect api.partner.example.com:443 \
-servername api.partner.example.com
Check:
Subject Alternative Name
Issuer
Validity
TLS version
Certificate chain
Step 6: Call the health check
curl -v https://api.partner.example.com/v1/health
Step 7: Call with authentication
JWT example:
curl -v \
-H "Authorization: Bearer ${TOKEN}" \
https://api.partner.example.com/v1/orders
SigV4 scenarios can use the SDK, AWS CLI or corresponding signature library that supports signatures.
22. Common faults and judgment methods
1. DNS request timeout
Performance:
dig timeout
Priority checks:
External DNS to Resolver IP routing
TGW routing
VPC subnet routing
Resolver SG UDP/TCP 53
external firewall
NACL
2. DNS returns NXDOMAIN
It means that the network and DNS server may be connected, but there is a problem with the record layer.
Check:
Private Hosted Zone name
A Alias record
Hosted Zone is associated with VPC
Is the FQDN queried correct?
Is there a more specific conflict Hosted Zone
3. The domain name can be resolved, but TCP 443 times out.
Check:
execute-api Endpoint SG
External routing to Endpoint ENI
NACL
TGW backhaul routing
external firewall
4. TLS certificate name mismatch
For example the certificate is:
*.example.com
But the domain name is:
api.partner.example.com
*.example.com only covers one layer:
api.example.com
Usually not covered:
api.partner.example.com
Should be used:
*.partner.example.com
or exact certificate:
api.partner.example.com
5. Return 403 Forbidden
Check order:
Is Domain Name Access Association AVAILABLE?
Domain Resource Policy
API Resource Policy
VPC Endpoint Policy
MethodAuthorization
JWT/IAM signature
API Key/Usage Plan
6. Return Missing Authentication Token
Common reasons:
Base Path error
Stage mapping error
HTTP method error
Resource path does not exist
API not redeployed
For example actual Mapping:
/v1 → prod
Correct:
https://api.partner.example.com/v1/orders
Error:
https://api.partner.example.com/prod/orders
7. The default execute-api URL can be accessed, but the Custom Domain cannot
Key points to check:
ACM certificate
Private Domain status
Domain Resource Policy
Domain Access Association
API Mapping
Route 53 Alias
Host/SNI
8. It can be accessed within the VPC, but not by external companies.
Usually stated:
API Gateway configuration is basically correct
The problem is focused on DX routing, Endpoint SG or external DNS
9. Small requests are normal, but large requests fail.
Check:
MTU
PMTUD
ICMP Fragmentation Needed
intermediate firewall
Jumbo Frame
23. The ten most easily missed places
- Direct Connect is not automatically encrypted.
- DNS and HTTPS are two different paths.
- The Resolver Endpoint must open both UDP and TCP 53.
- Private Hosted Zone must be associated with the VPC where the Resolver is located.
- Alias target is execute-api VPC Endpoint, not Resolver.
- The execute-api Endpoint security group must allow external company source network segment TCP 443.
- Private Domain Policy and Private API Policy are two policies.
- must create a Domain Name Access Association.
- needs to be redeployed after modifying the API's Endpoint association or resource.
- The DNS verification record of the ACM public certificate must be queryable from the public DNS and cannot be placed only in the private Hosted Zone.
24. Recommended final production configuration
The following configuration is recommended for formal B2B systems:
Two Direct Connect
+ VPN backup link
Transit VIF
+ Direct Connect Gateway
+ Transit Gateway
Standalone Shared Services VPC
Resolver Inbound Endpoint of two AZs
+ Only allow official DNS servers UDP/TCP 53
execute-api Interface Endpoint of two AZs
+ Only allow external business network segment TCP 443
Dedicated private subdomain
api.partner.example.com
Private Custom Domain
+ ACM Certificate
+ Domain Access Association
Private Domain Policy
+ API Resource Policy
+ Endpoint Policy
All restrictions aws:SourceVpce
JWT or IAM SigV4 authentication
+ API Gateway Access Logs
+ Resolver Query Logs
+ VPC Flow Logs
+ DX CloudWatch Alert
The final link can be summarized as:
DNS：
External DNS
→ Direct Connect
→ Resolver Inbound Endpoint
→ Private Hosted Zone
→ Return to VPC Endpoint private IP
HTTPS：
External business system
→ Direct Connect
→ execute-api Interface Endpoint
→ Private Custom Domain
→ API Mapping
→ Private REST API
→ Backend services