There’s some very good articles on using the Serverless Framework to setup custom domains for API Gateway endpoints. For my use case I wasn’t planning to use Route 53 for DNS hosting for the domain so they were missing a crucial step. This post documents that step.
Follow the article linked above to setup the plugin and basic configuration. The configuration for the custom domain in the
serverless.yml file is almost exactly as shown in the article with the exception of the
createRoute53Record line which I changed to turn off the Route 53 DNS interaction.
customDomain: domainName: api.example.com basePath: app createRoute53Record: false
With that change the steps required to do the setup are the same as shown in the article but there is one final step required. Here’s the process.
Run the create_domain command
This one was one of the things that confused me since I didn’t want to create a new DNS entry in Route 53. This command does not create a domain since we’ve disabled the Route 53 integration. We do still need to run it because it sets up an AWS CloudFront distribution to front the API Gateway Endpoint. This takes time, up to 40 minutes according to the command output.
Run a standard deploy
After the standard deploy the output will show the custom domain and, most importantly the
Distribution Domain Name. That is the DNS name of the CloudFront endpoint that is pointing to the API Gateway deployment. That’s the information you’ll need to user in your DNS.
sls deploy ... // other output here Serverless Domain Manager Summary Domain Name api.example.com Distribution Domain Name a2fcnefljuq1t1.cloudfront.net
Update Your DNS – Missing Step
Now you have all the information you need to setup the DNS entry to have the custom domain resolve to CloudFront and eventually the API Gateway Endpoint. Using whatever DNS configuration tool you use for your domain, add the
Distribution Domain Name shown in the output of the deploy command as an ALIAS record for the custom domain. In the example shown above that would be Hostname
a2fcnefljuq1t1.cloudfront.net. Note that not all DNS hosting services support ALIAS records so if you don’t see it your provider might not support it.
Check That it Worked
Now use a client like Postman or other to hit the API on the custom domain. In the example configuration I used a base path so that I can potentially have multiple API Gateway definitions on the same custom domain. That means that the path to the API will have to also use the base path. As an example if the API Gateway definition was a path of
/dostuff the resulting full URL for the example shown would be:
Don’t forget that the
create_domain step will take time, like 40 minutes, and nothing will work until that completes.