Serverless Domain Manager

homepage icon https://github.com/amplify-education/serverless-domain-manager
Follow @amplify-education

Tracked

NPM Downloads Last Month
70659
Issues
26
Stars
273
Forks
65
Watchers
273
Watch Star Fork Issue Download License NPM Build Status Coverage Status Contributors

Repo README Contents:

serverless-domain-manager

serverless Build Status npm version MIT licensed Codacy Badge npm downloads

Create custom domain names that your lambda can deploy to with serverless. Allows for base path mapping when deploying and deletion of domain names.

About Amplify

Amplify builds innovative and compelling digital educational products that empower teachers and students across the country. We have a long history as the leading innovator in K-12 education - and have been described as the best tech company in education and the best education company in tech. While others try to shrink the learning experience into the technology, we use technology to expand what is possible in real classrooms with real students and teachers.

Learn more at https://www.amplify.com

Getting Started

Prerequisites

Make sure you have the following installed before starting:

The IAM role that is deploying the lambda will need the following permissions:

acm:ListCertificates                *
apigateway:GET                      /domainnames/*
apigateway:DELETE                   /domainnames/*
apigateway:POST                     /domainnames
apigateway:POST                     /domainnames/*/basepathmappings
cloudfront:UpdateDistribution       *
route53:ListHostedZones             *
route53:ChangeResourceRecordSets    hostedzone/{HostedZoneId}
route53:GetHostedZone               hostedzone/{HostedZoneId}
route53:ListResourceRecordSets      hostedzone/{HostedZoneId}

CloudFormation

Alternatively you can generate an least privileged IAM Managed Policy for deployment with this:

deployment policy cloudformation template

Installing

# From npm (recommended)
npm install serverless-domain-manager --save-dev

Then make the following edits to your serverless.yaml file:

Add the plugin.

plugins:
  - serverless-domain-manager

Add the plugin configuration (example for serverless.foo.com/api).

custom:
  customDomain:
    domainName: serverless.foo.com
    stage: ci
    basePath: api
    certificateName: '*.foo.com'
    createRoute53Record: true
    endpointType: 'regional'
Parameter Name Default Value Description
domainName (Required)   The domain name to be created in API Gateway and Route53 (if enabled) for this API.
basePath (none) The base path that will prepend all API endpoints.
stage Value of --stage, or provider.stage (serverless will default to dev if unset) The stage to create the domain name for. This parameter allows you to specify a different stage for the domain name than the stage specified for the serverless deployment.
certificateName Closest match The name of a specific certificate from Certificate Manager to use with this API. If not specified, the closest match will be used (i.e. for a given domain name api.example.com, a certificate for api.example.com will take precedence over a *.example.com certificate).

Note: Edge-optimized endpoints require that the certificate be located in us-east-1 to be used with the CloudFront distribution.
certificateArn (none) The arn of a specific certificate from Certificate Manager to use with this API.
createRoute53Record true Toggles whether or not the plugin will create an A Alias record in Route53 mapping the domainName to the generated distribution domain name. If false, does not create a record.
endpointType edge Defines the endpoint type, accepts regional or edge.
hostedZoneId   If hostedZoneId is set the route53 record set will be created in the matching zone, otherwise the hosted zone will be figured out from the domainName (hosted zone with matching domain).
hostedZonePrivate   If hostedZonePrivate is set to true then only private hosted zones will be used for route 53 records. If it is set to false then only public hosted zones will be used for route53 records. Setting this parameter is specially useful if you have multiple hosted zones with the same domain name (e.g. a public and a private one)
enabled true Sometimes there are stages for which is not desired to have custom domain names. This flag allows the developer to disable the plugin for such cases. Accepts either boolean or string values and defaults to true for backwards compatibility.

Running

To create the custom domain:

serverless create_domain

To deploy with the custom domain:

serverless deploy

To remove the created custom domain:

serverless delete_domain

How it works

Creating the custom domain takes advantage of Amazon’s Certificate Manager to assign a certificate to the given domain name. Based on already created certificate names, the plugin will search for the certificate that resembles the custom domain’s name the most and assign the ARN to that domain name. The plugin then creates the proper A Alias records for the domain through Route 53. Once the domain name is set it takes up to 40 minutes before it is initialized. After the certificate is initialized, sls deploy will create the base path mapping and assign the lambda to the custom domain name through CloudFront.

Running Tests

To run the test:

npm test

All tests should pass.

If there is an error update the node_module inside the serverless-vpc-discovery folder:

npm install

Known Issues

Responsible Disclosure

If you have any security issue to report, contact project maintainers privately. You can reach us at github@amplify.com

Contributing

We welcome pull requests! For your pull request to be accepted smoothly, we suggest that you:

  1. For any sizable change, first open a GitHub issue to discuss your idea.
  2. Create a pull request. Explain why you want to make the change and what it’s for. We’ll try to answer any PR’s promptly.