In this tutorial, you create a private custom domain name that you can invoke in a VPC in your own account. To accomplish this, you are the API provider and the API consumer. You need an existing private API and VPC endpoint to complete this tutorial. If you have a VPC endpoint that you use to access a public custom domain name, don't use it for this tutorial or to create any domain name access associations.
Step 1: Create a private custom domain name
You create your private custom domain name by specifying the domain name, the ACM certificate, and the
policy for the execute-api
service to control which VPC endpoints can invoke it.
To create a private custom domain name
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. -
In the main navigation pane, choose Custom domain names.
-
Choose Add domain name.
-
For Domain name, enter a domain name.
Your ACM certificate must cover this domain name, but the domain name doesn't need to be unique.
-
Select Private - new.
-
For ACM certificate, select a certificate.
Choose Add domain name.
API Gateway provisions a domain name with a deny
all resource policy. This is the resource policy for the
execute-api
service. You need to update this resource
policy to grant access to your VPC endpoints to invoke your private custom domain name.
To update your resource policy
-
Choose the Resource policy tab, and then choose Edit resource policy.
-
Enter the following resource policy in the code editor. Replace the VPC endpoint
vpce-abcd1234efg
with your own VPC endpoint ID.{ "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-abcd1234efg
" } } } ] } Choose Save changes.
Step 2: Create a base path mapping to map your
private API to your private custom domain name
After you create your private custom domain name, you map a private API to it. A base path mapping makes an API accessible through the combination of the private custom domain name and an associated base path. We recommend that you use a single private custom domain name as the hostname of multiple private APIs.
All API providers need to create a base path mapping, even if you don't plan on invoking your own API. You also need to grant access for VPC endpoints to invoke any private APIs that you map to your private custom domain name.
To create a base path mapping
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. -
In the main navigation pane, choose Custom domain names.
Choose a private custom domain name.
On the API mappings tab, choose Configure mappings.
Choose Add new mapping.
Enter an API, a Stage, and optionally a Path.
Choose Save.
Note
If you want other AWS accounts to invoke your private custom domain name, after you complete this tutorial, follow the steps in API provider: Share your private custom domain name using AWS RAM.
Step 3: Create a domain name
access association between your custom domain name and a VPC endpoint
Next, you create a domain name access association between your private custom domain name and your VPC endpoint. Your VPC endpoint uses the domain name access association to invoke your private custom domain name while isolated from the public internet.
To create a domain name access association
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. -
In the main navigation pane, choose Custom domain names.
-
Choose a private custom domain name.
-
In the Resource sharing tab, for Domain name access associations, choose Create domain name access association.
-
For Domain name ARN, select your domain name.
-
For VPC endpoint ID, select the VPC endpoint ID you provided access to in step 1.
-
Choose Domain name access association.
You can also create your domain name access association using the Domain name access associations page of the console.
After you create your domain name access association, it takes about 15 minutes to be ready. While you wait, you can proceed with the following steps.
Step 4: Create a Route 53 hosted zone
After you update your resource policy and associate your private custom domain name with your VPC endpoint, you create a private hosted zone in Route 53 to resolve your custom domain name. A hosted zone is container that holds information about how you want to route traffic for a domain within one or more VPCs without exposing your resources to the internet. For more information, see Working with private hosted zones.
To use the AWS Management Console, see Creating a private hosted zone in the Amazon Route 53 Developer Guide.
For Name, use the name of your private custom domain name. For VPC ID, use the VPC containing the VPC endpoint that you used in the previous steps.
Step 5: Create a Route 53 DNS record
After you create the hosted zone, you create an record to resolve your private custom domain name. You use the hosted zone ID you created in the previous step. In this example, you create an A record type. If you are using IPv6 for your VPC endpoint, create an AAAA record type. If you are using dualstack for your VPC endpoint, create both an AAAA and an A record type.
To use the AWS Management Console, see Routing traffic to an Amazon API Gateway API by using your domain name.
Use Quick create and turn on Alias. For endpoint, use the VPC endpoint DNS name.
If you don't plan on invoking your own private custom domain name, after you confirm your private custom domain name is working, you can delete these resources.
Step 6: Invoke your private custom domain name
You can now invoke your private custom domain name in your own AWS account. In your VPC, use the following curl command to access your private custom domain name.
curl https://private.example.com/v1
For more information about other ways to invoke your private API, see Invoke a private API using a custom domain name.
Step 7: Clean up
To prevent unnecessary costs, delete the association between your VPC endpoint and your private custom domain name, and then delete your private custom domain name.
To delete the domain name access association
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. -
In the main navigation pane, choose Domain name access associations.
-
Select your domain name access association, and then choose Delete.
-
Confirm your choice, and then choose Delete.
After you delete your domain name access association, you can delete your private custom domain name.
To delete your private custom domain name
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. -
In the main navigation pane, choose Custom domain names.
-
Choose your private custom domain name.
-
Choose Delete.
-
Confirm your choice, and then choose Delete.
If necessary, you can also delete your VPC endpoint. For more information, see Delete an interface endpoint.
Best practices
We recommend that you use the following best practices when you create your private custom domain name.
-
Use base path mapping to map multiple private APIs to the same private custom domain name.
-
When a VPC endpoint no longer needs access to a private custom domain name, delete the association. In addition, remove the VPC endpoint from the
policy
for theexecute-api
service for the private custom domain. -
Configure at least two Availability Zones per VPC endpoint.
-
Disable the default endpoint. We recommend that you disable the default endpoint to allow your API consumers to only call your API from the custom domain name. For more information, see Disable the default endpoint for REST APIs.
-
We recommend that you provision a Route 53 private hosted zone and an A-type record when you set up your private custom domain name. If you don't plan on invoking your own private custom domain name, you can delete these resources later.