wooodhead/serverless-api-cloudfront

Serverless Plugin - CloudFront distribution in front of your API Gateway

serverless-api-cloudfront

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.

⚡ 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/00000000-1111-2222-3333-444444444444
    waf: 00000000-0000-0000-0000-000000000000
    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 can be all, none (default) or a list of headers (see CloudFront custom behaviour):

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 can be TLSv1 (default), TLSv1_2016, TLSv1.1_2016, TLSv1.2_2018 or SSLv3:

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