Implementing Custom Domain using Serverless Framework

We all know that API development in AWS can be done using a serverless framework. Serverless is very useful to help us execute software development technique since you can deploy your API using development and staging environment. However as you all know, deploying your API using serverless framework produces url endpoint that are hard to read and hard to remember like this:

https://abc123ef45.execute-api.ap-southeast-1.amazonaws.com/method-name

This could slow down the development process since communicating your fresh-made API with your front-end developer partner needs time and precaution.

But don’t worry, there is already a plugin where you can connect the deployed API into your own domain, which is serverless-domain-manager. With this plugin you can deploy any API in development or staging environment using serverless and still get an easier access to it. You can even use the same subdomain for different services. This custom domain plugins allows base path mapping when deploying and also deleting the custom domain when necessary. You can learn more about it by visiting their github.

The first thing you need to do is just install the plugin ‘serverless-domain-manager’ and just add some configuration in the serverless file. The configuration in serverless is easier than you think. Just a bit tweak like this in the serverless.yml and you’re good to go.

plugins:
 - serverless-domain-manager

And

custom:
  customDomain:
    domainName: https://api.yoursubdomain.com
    basePath: your-service-name
    stage: ${self:provider.stage}
    endPointType: regional
    certificateName: '*.sertificate.com'
    createRoute53Record: true
    enabled: true
    securityPolicy: tls_1_2

If you want to customize this serverless.yml more, you can do it in the custom section here. Here is the simple explanation of each parameters do:

• domainName is the name of your domain in the you want to create in API Gateway and Route53.
• basePath is the path where all your API endpoint starts. The ‘stage’ allow you to specify the stage where your API is deployed, and it will set to ‘dev’ as default.
• certificateName is the name of the certificate used for your domain. You can also use ‘certificateArn’ as alternative where its the arn of the specific certificate in the Certificate Manager.
• createRoute53Record is the toggles on wherever you want to create Alias Records on the route53 or not.
• endPointType defines the type of endpoint and only receive ‘edge’ and ‘regional’. The ‘enabled’ parameter is to specify whether you need this custom domain or not since not all environment needs a custom domain.
• securityPolicy only accept ‘tls_1_0’ and ‘tls_1_2’. For more information, check the github directly here.

That’s most of the things that you can customize in this plugin. You can put a lot of API on the same sub-domain and change the base path according to your API service name. This way, communicating with your developer team can be easier since the API request will always be :

https://api.yoursubdomain.com/your-service-name/method-name

Serverless.yml file doesn’t support conditional logic, but you can simulate it using mapping! This helps if you want to condition your custom domain or other configuration serverless.yml. For example, if you want to conditionally put different custom domain for different environment you can do this:

custom:  
  development:
    domainNameCondition: dev-api.yoursubdomain.com
  staging:
    domainNameCondition: staging-api.yoursubdomain.com
  production:
    domainNameCondition: api.yoursubdomain.com
  customDomain:
    domainName: ${self:custom.${env:STAGE}.domainNameCondition}

The serverless.yml file have the ability to refer to another variable inside of its own section, so that’s why its one of the reason to use mapping to simulate if condition. Using the ‘${env:stage}’ in the environment variable (assuming you only have development, staging and production as environment stage) we can pinpoint which domain name we want to use in the custom domain configuration.

Oh and one other thing, if you don’t already have the custom domain ready, you can manually create it whenever you deploy your application by using the command ‘serverless create_domain’ or ‘sls create_domain’ before the command ‘sls deploy’. You won’t need to worry about stacking your domain since serverless will automatically check whether you already have that specific domain or not, if you do serverless will simply give the message “custom-domain already exists”. To delete the custom domain, simply use the command ‘serverless delete_domain’.

Creating the custom domain takes advantages of Amazon’s Certificate Manager to assign a certificate to the given domain name. And if you set the createRoute53Record to ‘true’ then the plugins will also create an alias record of the domain in Route 53. For more information, you can check how it works here.

Hope this article helps you guys on implementing your application into a custom domain and since its easy to do, this can help you smooth things over your development process.

Learn more about HARA

• Visit the HARA website
• Follow our Social Media
  Facebook, Twitter, Instagram, Medium & LinkedIn