serverless-domain-manager

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: * nodejs * npm * serverless

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

acm:ListCertificates                   *
acm:DescribeCertificate                *
apigateway:AddCertificateToDomain      /domainnames*
apigateway:RemoveCertificateFromDomain /domainnames*
apigateway:GET                         /domainnames*, /apis*, /restapis*
apigateway:DELETE                      /domainnames*, /apis*, /restapis*
apigateway:POST                        /domainnames*, /apis*, /restapis*
apigateway:PATCH                       /domainnames*, /apis*, /restapis*
cloudformation:GET                     *
cloudformation:ListStacks              *
cloudformation:DescribeStacks          *
cloudfront:UpdateDistribution          *
route53:ListHostedZones                *
route53:ChangeResourceRecordSets       hostedzone/{HostedZoneId}
route53:GetHostedZone                  *
route53:ListResourceRecordSets         *
iam:CreateServiceLinkedRole            arn:aws:iam::${AWS::AccountId}: role/aws-service-role/ops.apigateway.amazonaws.com/AWSServiceRoleForAPIGateway
s3:ListBucket                          *
s3:GetObject                           *

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). For a single domain and API type the following structure can be used.

custom:
  customDomain:
    domainName: serverless.foo.com
    stage: ci
    basePath: api
    certificateName: '*.foo.com'
    createRoute53Record: true
    createRoute53IPv6Record: true
    endpointType: REGIONAL
    securityPolicy: tls_1_2
    apiType: rest
    autoDomain: false

Multiple API types mapped to different domains can also be supported with the following structure. The key is the API Gateway API type.

custom:
  customDomain:
    rest:
      domainName: rest.serverless.foo.com
      stage: ci
      basePath: api
      certificateName: '*.foo.com'
      createRoute53Record: true
      createRoute53IPv6Record: true
      endpointType: REGIONAL
      securityPolicy: tls_1_2
    http:
      domainName: http.serverless.foo.com
      stage: ci
      basePath: api
      certificateName: '*.foo.com'
      createRoute53Record: true
      createRoute53IPv6Record: true
      endpointType: REGIONAL
      securityPolicy: tls_1_2
    websocket:
      domainName: ws.serverless.foo.com
      stage: ci
      basePath: api
      certificateName: '*.foo.com'
      createRoute53Record: true
      createRoute53IPv6Record: true
      endpointType: REGIONAL
      securityPolicy: tls_1_2

Or for multiple domains

custom:
  customDomains:
    - http:
        domainName: http-api-${opt:RANDOM_STRING}.${env:TEST_DOMAIN}
        basePath: ''
        endpointType: REGIONAL
    - http:
        domainName: http-api-${opt:RANDOM_STRING}.${env:TEST_DOMAIN}.foo
        basePath: ''
        endpointType: REGIONAL

For multi-region deployments, a route53Params structure can be used to support latency or weighted routing policies

custom:
  customDomain:
    domainName: serverless.foo.com
    stage: ci
    basePath: api
    certificateName: '*.foo.com'
    createRoute53Record: true
    endpointType: REGIONAL
    securityPolicy: tls_1_2
    route53Params:
      routingPolicy: latency

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 A Alias and AAAA Alias records in Route53 mapping the domainName to the generated distribution domain name. If false, does not create a record. | | createRoute53IPv6Record | true | Toggles whether or not the plugin will create an AAAA Alias record in Route53 mapping the domainName to the generated distribution domain name. If false, does not create a record. | | route53Profile | (none) | Profile to use for accessing Route53 resources when Route53 records are in a different account | | route53Region | (none) | Region to send Route53 services requests to (only applicable if also using route53Profile option) | | endpointType | EDGE | Defines the endpoint type, accepts REGIONAL, EDGE, or PRIVATE. Note: PRIVATE endpoints are only supported with REST APIs and can only be accessed from within a VPC. Private endpoints do not support HTTP APIs, WebSocket APIs, mutual TLS, or non-simple routing policies. | | apiType | rest | Defines the api type, accepts rest, http or websocket. | | tlsTruststoreUri | undefined | An Amazon S3 url that specifies the truststore for mutual TLS authentication, for example s3://bucket-name/key-name. The truststore can contain certificates from public or private certificate authorities. Be aware mutual TLS is only available for regional APIs. | | tlsTruststoreVersion | undefined | The version of the S3 object that contains your truststore. To specify a version, you must have versioning enabled for the S3 bucket. | | 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). If records need to be set in both private and public hoste