I want to share some experience around deploying node based Lambda services in a microservice architecture. How can we solve the problem of having multiple API versions of the same microservices deployed under a single custom domain?

We can achieve this with simple SLS commands and certificates from the AWS certificate manager.

What is our Goal?

Let’s assume you have a set of serverless aka Lambda services in node.js. You want to package and deploy these services in separate microservices/stacks.

Goal: Capability to deploy multiple versions of the API REST services and manage the API versions on API Gateway without affecting existing API consumers

For example, reasons, let‘s say we have three services — core services, data services, and payment services. We want to deploy two versions of the above services like

(similarly for other services.)

NOTE: Multiple versions of your lambda services co-exist now without affecting each other

How do we deploy multiple API versions?

We need to follow the below steps and achieve our goal

1. Setup a custom API domain with API gateway (of course with https — explained in a later link)

2. Map the serverless stacks to the custom domain path

3. With the traditional SLS deploy command, map the certificate in AWS certificate manager to the corresponding stage/path mapping under the custom domain in API gateway

Let’s look at a typical serverless.yml file

Sample serverless.yml with custom domain API example

Key sections to note here are

1. Plugin for the serverless-domain-manager. This is like any other plugin with serverless — https://github.com/amplify-education/serverless-domain-manager

2. You need to run below command to add the plugin entry into yml

npm install serverless-domain-manager — save-dev

3. Custom section with the custom domain mapping

i. The endpoint type must be regional. The lambda when deployed will have the endpoint type as Edge by default. We should change this. This is one very important factor not mentioned anywhere

ii.  API type must be HTTP

iii. Set the createRoute53Record to true so that you don’t need to take any manual action in Route53

iv.  Certificate name — must be a name registered in your AWS region with a valid SSL certificate. If you are unsure how to generate a free SSL certificate, please read this — https://www.serverless.com/blog/serverless-api-gateway-domain
P.S: I wrote this article based on the ambiguities I see in this article. But, the certificate creation process is well explained with snapshots.

4. Once we are ready we can just deploy with normal deploy command like

Using GoDaddy / my DNS provider

Most of you reading this article may be wondering, if you should migrate your DNS into AWS Route53 to make this work.

The answer is: NO. You can use your existing domain provider.

How can I do that?

With the above configuration of serverless.yml, when you make a deployment you will get a result like this

Custom Domain page in API Gateway

APIs listed in API gateway. NOTE that the endpoints have been changed by me to Regional

You need to copy the API gateway domain name and map it to your GoDaddy or any DNS provider CNAME entry.

GoDaddy or any DNS provider mapping for API

Hope this explains the API management process for handling multiple versions of API. You can literally use the serverless.yml I gave above and change the domain and certificates and it should work. Also, you need to change the stage and stack names to core-v2 or core-v3 or anything you need to deploy parallel versions of the given services.

Good luck with this and feel free to reach out to me in case any additional details are needed.