How to add a custom domain for a serverless-1.0.0 framework defined/deployed API?

Question

Serverless-1.0.0-rc.1 enables to deploy an API to be accessible via a AWS API Gateway.

The question: I need the deployed API exposed via a custom domain with SSL certificate instead of the randomly assigned one (URL https://qwertylgbtqert.execute-api....)?

Can that be done from within serverless.yml or serverless framework?

Here is my simple service serverless.yml definition:

service: my-service
provider:
  name: aws
  runtime: nodejs4.3

functions:
  generate:
    handler: handler.generate
    events:
      - http:
         method: get
         path: url
         cors: true

There is an question which relates to this: the answer here, but does not provide an applicable answers. Especially how to assign the custom domain from within the serverless.yml itself.

It thought if it is possible to create a AWS::Route53 resource and leverage that, however I don't know how to do that in serverless.

Answer 1

You need to create the custom domain first and upload the certificates. This should not be part of this code or your deployment of this piece of software.

After you have a custom domain you need to think in terms of CloudFormation.

Like with everything else in Serverless Framework; you can leverage CloudFormation templates to administer resources in AWS.

So your question becomes how can you add your API Gateway to your Custom Domain in CloudFormation (hint: there is much more help on Google if you search for CloudFormation instead of Serverless Framework)? By creating a AWS::ApiGateway::BasePathMappingin CloudFormation is the answer.

This is done in the Resources in your serverless.yml file. Like this for example:

resources:
    Resources:
        pathmapping:
            Type: AWS::ApiGateway::BasePathMapping
            Properties:
                BasePath: oauth2
                DomainName: ${self:vars.domainName}
                RestApiId: 
                    Ref: ApiGatewayRestApi
                Stage: ${self:vars.stage}

This requires you to have variables for the domainName and stageName in the serverless.env.yml file for the stages you use.

Edit: For versions of Serverless Framework 1 before rc1 you have to add DependsOn: IamPolicyLambda to the pathmapping resource. This was fixed in: https://github.com/serverless/serverless/pull/1783

Before rc1 you should use RestApiApigEvent instead of ApiGatewayRestApi

Answer 2

I think this topic deserves an update, so I will give it a try. Be sure to first create a certificate with Certificate Manager. Then be sure your "serverless user" has the right admin permissions to modify Route53 record sets. Then add the following to your serverless.yaml:

custom:
  customDomain:
    domainName: "api.example.com"
    certificateName: "*.example.com"
    createRoute53Record: true

plugins:
  - serverless-domain-manager

Before you deploy run (this can take a while):

serverless create_domain

Source and additional options can be found here.