Serverless API Cloudfront

Plugin that adds CloudFront distribution in front of your API Gateway for custom domain, CDN caching and access log.

user  

Droplr

serverless-api-cloudfront

serverless npm version MIT licensed npm downloads

Automatically creates properly configured AWS CloudFront distribution that routes traffic to API Gateway.

Due to limitations of API Gateway Custom Domains, we realized that setting self-managed CloudFront distribution is much more powerful.

:zap: Pros

  • Allows you to set-up custom domain for your API Gateway
  • Enables CDN caching of resources - so you don't waste Lambda invocations or API Gateway traffic for serving static files (just set proper Cache-Control in API responses)
  • Much more CloudWatch statistics of API usage (like bandwidth metrics)
  • Real world access log - out of the box, API Gateway currently does not provide any kind of real "apache-like" access logs for your invocations
  • Web Application Firewall support - enable AWS WAF to protect your API from security threats

Installation

$ npm install --save-dev serverless-api-cloudfront

Configuration

  • All apiCloudFront configuration parameters are optional - e.g. don't provide ACM Certificate ARN to use default CloudFront certificate (which works only for default cloudfront.net domain).
  • This plugin does not set-up automatically Route53 for newly created CloudFront distribution. After creating CloudFront distribution, manually add Route53 ALIAS record pointing to your CloudFront domain name.
  • First deployment may be quite long (e.g. 10 min) as Serverless is waiting for CloudFormation to deploy CloudFront distribution.
# add in your serverless.yml

plugins:
  - serverless-api-cloudfront

custom:
  apiCloudFront:
    domain: my-custom-domain.com
    certificate: arn:aws:acm:us-east-1:000000000000:certificate/000000112233444444444444
    waf: 000000000000000000000000
    compress: true
    logging:
      bucket: my-bucket.s3.amazonaws.com
      prefix: my-prefix
    cookies: none
    headers:
      - x-api-key
    querystring:
      - page
      - per_page
    priceClass: PriceClass_100
    minimumProtocolVersion: TLSv1

Notes

  • domain can be list, so if you want to add more domains, instead string you list multiple ones:
domain:
  - my-custom-domain.com
  - secondary-custom-domain.com
  • cookies can be all (default), none or a list that lists the cookies to whitelist
cookies:
  - FirstCookieName
  - SecondCookieName
headers: all
  • querystring can be all (default), none or a list, in which case all querystring parameters are forwarded, but cache is based on the list:
querystring: all
  • priceClass can be PriceClass_All (default), PriceClass_100 or PriceClass_200:
priceClass: PriceClass_All
minimumProtocolVersion: TLSv1

IAM Policy

In order to make this plugin work as expected a few additional IAM Policies might be needed on your AWS profile.

More specifically this plugin needs the following policies attached:

  • cloudfront:CreateDistribution
  • cloudfront:GetDistribution
  • cloudfront:UpdateDistribution
  • cloudfront:DeleteDistribution
  • cloudfront:TagResource

You can read more about IAM profiles and policies in the Serverless documentation.

Error troubleshooting

  • Make sure you have at least one http event otherwise you'll get The CloudFormation template is invalid: Template format error: Unresolved resource dependencies [ApiGatewayRestApi] in the Resources block of the template
view on Github

Latest commit b2f54ec on Sep 24, 2017

New to serverless?

To get started, pop open your terminal & run:

npm install serverless -g