The HTTP endpoints that AWS generates are cryptic and arbitrary. If you create a custom domain name for your aws lambda, you can have an endpoint that is more attractive to developers and easier to manage.
In this article, I will explain how to create a custom domain name for your aws lambda. I use the serverless framework to manage and deploy my AWS services. This article assumes that you do the same.
When you deploy your AWS Lambda, you will see some information on the CLI, assuming your deployment was a success. One of these blocks of information is “endpoints”. AWS generates your HTTP URLs automatically for you. This is great (I’m serious when I say that). And for most scenarios, that is enough. But what about when you want to share your endpoint with the world? Be it developers or customers, api.mydomain.com/orders is much easier to remember or manage than d8tce1pthd.execute-api.us-east-1.amazonaws.com/dev/orders.
The serverless-domain-manager NPM module is a serverless framework plugin that makes it easy to create a custom domain name for your aws lambda. There is a two-step process. Step 1 is to create your custom domain. Step 2 is to deploy your service. Before we dive into those steps, let’s go over the prerequisites and review the code examples.
Prerequisites
Serverless framework
If you plan to follow along with the code examples, you will need to install the serverless framework.
Domain Registration and SSL certificate
In order to create a custom domain name for your aws lambda, you need to have that domain registered with AWS. Once you have that domain registered with AWS, you will need an SSL certificate for that domain. Below are a few links that provide helpful information on these topics:
https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html
https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html
Also, this video is helpful:
Getting a free SSL certificate with AWS Certificate Manager for CloudFront (AWS howto)
(you can probably stop at 3:20)
Example 1 – package.json
https://gist.github.com/kevinchisholm/8d59ffd7e605b9806c8c342ecdb7f4e9
In Example # 1, we have the package.json file for our code. Not too much to discuss here. Just note that the serverless-domain-manager plugin is a dev dependency.
Example 2 – serverless.yml
https://gist.github.com/kevinchisholm/d1799ce76bcf5a5d22b50652415af11e
In Example # 2, we have the serverless.yml file for our code. On line # 3, we have added the serverless-domain-manager plugin to the plugins section. On line # 12, we have added a custom.customDomain section. Let’s take a closer look at each property:
- basePath – allows us to define what each lambda’s path builds upon. For example, if our base path is “orders” then our endpoints might look something like this: api.foo.com/orders/hats, api.foo.com/orders/shoes, api.foo.com/orders/shirts, etc.
- createRoute53Record – Tells AWS to create an A Alias and AAAA Alias records in Route53.
- stage – The stage to create the domain name for.
- domainName – The domain name to be created in API Gateway and Route53 (if enabled) for this service.
- certificateName – The name of a specific certificate from Certificate Manager to use with this service.
- certificateArn – The arn of a specific certificate from Certificate Manager to use with this API.
Example 3 – The Lambda Function
https://gist.github.com/kevinchisholm/4533a38af8662d19fa463f0936a9d965
In Example # 3, we have our AWS Lambda file. I this case, we have two functions defined in our serverless.yml file, but we reference two module.exports properties in the same file. This was done to keep the code examples as simple as possible.
Both of the functions exported here are very simple: they return JSON that indicates which function they belong to.
Deploying Your Service
Use the serverless-domain-manager NPM module to create the sub-domain (one-time step)
- Move into the root of your project folder
- Run the command: serverless create_domain -s dev
- Wait 20-40 minutes for the sub-domain to be created
Deploy your project
- Move into the root of your project folder
- Run the command: npm install
- Run the command: sls deploy -s dev
View your endpoints
- Visit the endpoint https://XXX.YOUR-DOMAIN.com/orders/hats
- Visit the endpoint https://XXX.YOUR-DOMAIN.com/orders/shoes
- You should see the appropriate messages in the browser.
NOTE: replace XXX.YOUR-DOMAIN.com with your actual custom domain
