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 certif

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.