aws

Creating custom domain for AWS Serverless API

Nelly Sattari

Mar 4, 2018 • 2 min read

Once you deploy your lambda function along with the Api Gateway, a random unique URL will be assigned to the api endpoint.

It might happen sometimes that you want some major changes or you just deleted the whole stack or you can think of any other scenario which ends up generating a new url. Then you have too update all dependent service and systems and do a new unnecessary release.

The obvious solution is introducing custom domain for your api so you always deal with the custom domain rather than random ones.

Versioning

I have another article about Versioning but very briefly you sometimes need to keep the new and old versions of the Gateway so you just need to add a versioning in Api Gateway Level but basically all the versions should be attached to a specific custom domain and only differentiate them with Version in the Path. The custom domain should be configed in a way that can refer to all different base paths if needed.

Introducing the custom domain

Creating the Certification

You need to take this step first since you need the certification being in place to use it in the code which is pretty straight forwarded and you just need to generate the cert in the client Certification section and get the approval from aws.

Update Serverless.yml

Assuming we use serverless framework, you need to get this code in the serverless.yml file in the custom section. You need to use the certification that you generated before.

I first show you the code and the result but to get the same result you need to do some extra steps other than updating this file which I will go through down the below.

custom:
  version: V1 
  customDomain:
    basePath: ${self:custom.version}
    RestApiId: 
      Ref: ApiGatewayRestApi
    domainName: XXXServiceNameXXX.api.${opt:stage}.svc.mynrma.com.au 
    certificateName: api.${opt:stage}.svc.mynrma.com.au
    endpointType: 'regional'
    stage: ${opt:stage}
    createRoute53Record: false

Then you need to run a serverless command to create the domain and deploy your function as below:

sls create_domain --stage preprod 
sls deploy -v --stage preprod

$STAGE is a variable that you can pass it through your CI/CD pipeline like this :

sls create_domain --stage $STAGE 
sls deploy -v --stage $STAGE

or directly use it in the command line as above.
Here is the result in your AWS console:
custom-domain-1

Rout53

SOme people change createRoute53Record to true in the code above but I ignored this one and created a proper Rout53 and connect it to the Target Domain Name in the Custom DOmain section of AWS. (You can see this value in the image above)

Once you do it the custom domain will be accisable for you and whatever basepath you map to this Api Gateway that would wok properly.

Introducing serverless-domain-manager plugin

Serverless framework uses a third party to create and setup the custom domain.
you need to install the plugin and introduce it in the serverless file in the plugin section.

npm i --save serverless-domain-manager

and add it to the serverless.yml file:

plugins:
  - serverless-domain-manager

References

https://serverless.com/blog/serverless-api-gateway-domain/
https://github.com/amplify-education/serverless-domain-manager