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

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

Make sure you have the following installed before starting:

• nodejs
• npm
• serverless

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}

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

deployment policy cloudformation template

# 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'

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

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.

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

• (5/23/2017) CloudFormation does not support changing the base path from empty to something or vice a versa. You must run sls remove to remove the base path mapping.
• (1/17/2018) The create_domain command provided by this plugin does not currently update an existing Custom Domain's configuration. Instead, it only supports updating the Route 53 record pointing to the Custom Domain. For example, one must delete and recreate a Custom Domain to migrate it from regional to edge or vice versa, or to modify the certificate.
• (8/22/2018) Creating a custom domain creates a CloudFront Distribution behind the scenes for fronting your API Gateway. This CloudFront Distribution is managed by AWS and cannot be viewed/managed by you. This is not a bug, but a quirk of how the Custom Domain feature works in API Gateway.

If you have any security issue to report, contact project maintainers privately. You can reach us at [email protected]

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.