AWS Edge@Lambda

This document describes integrating with the Spec Platform using an AWS Edge@Lambda function on an existing CloudFront distribution.

Introduction

This guide will create two separate Edge@Lambda function bundles: one for the origin request and another for the origin response. The origin request function will package the request for processing by the Spec Platform, while the origin response function will augment the response for proper Customer Journey Security.

Prerequisites

• An existing CloudFront distribution.

• Check out the configuration options for the Spec Platform in Config, also check out the known limitations below.

• Use your favorite javascript package installer( yarn or npm )to install the following package into your lambda project.

  • NPM Spec Proxy AWS Edge@Lambda

• An Origin Request Bundle

• An Origin Response Bundle

Instructions

Please note the following:

• All Edge@Lambdas must be created in the us-east-1 region in order to be associated to a CloudFront distribution. CloudFront will still replicate this function in other regions based on viewer request.

• The function must not have environment variables. Everything in a replicated edge function must be self-contained.

• The function cannot be placed inside a VPC. This limits control of egress beyond AWS CIDR ranges.

Add Origin Request Edge@Lambda

1. Create a new Lambda function in the AWS console in the us-east-1 region.

2. Use the AWS managed Edge@Lambda service role.

3. Upload the Origin Request bundle to the console.

4. Publish a new version of the lambda bundle.

5. Copy the ARN including the version.

6. Head to the CloudFront console and select the distribution to add the Lambda to.

7. Under behaviors, find the route that should be protected by Spec.

8. Paste the ARN into the Origin Request section.

9. Check "include body" option.

10. Save and wait for Edge@Lambda to propagate.

Add Origin Response Edge@Lambda

1. Create a new Lambda function in the AWS console in the us-east-1 region.

2. Use the AWS managed Edge@Lambda service role.

3. Upload the Origin Response bundle to the console.

4. Publish a new version of the lambda bundle.

5. Copy the ARN including the version.

6. Head to the CloudFront console and select the distribution to add the Lambda to.

7. Under behaviors, find the route that should be protected by Spec.

8. Paste the ARN of the origin-response-lambda into the Origin Response section.

9. Check "include body" option.

10. Save and wait for Edge@Lambda to propagate.

Confirm the installation

1. Requests to the routes protected by the Spec Platform should behave normally.

2. Any logging added to the Code Bundles should appear in the logs. See tips below.

Lambda Function Code Bundles

Spec provides the Code Bundles as public NPM packages. They are built using Typescript and designed to work alongside other edge worker functionality.

Use your favorite javascript package installer( yarn or npm )to install the following package into the project with your lambda code.

NPM Spec Proxy AWS Edge@Lambda

Building an Origin Request Bundle

The following snippet is the minimum amount of code required to create the origin request Edge@Lambda bundle:

import { specProxyProcessRequest } from "@specprotected/spec-proxy-aws-edge-lambda";
import { CloudFrontRequestEvent } from "aws-lambda";

const config = {
    disableSpecProxy: false,
    inlineMode: false
}

export const handler = async (event: CloudFrontRequestEvent) => {
    return await specProxyProcessRequest(event, config);
}

Check Edge Workers page for config options

Building an Origin Response Bundle

The process for this should be very similar to the previous bundle, with a slight variation on the methods we are calling to handle the response:

import { specProxyProcessResponse } from "@specprotected/spec-proxy-aws-edge-lambda";
import { CloudFrontResponseEvent } from "aws-lambda";

const config = {
    disablespecproxy: false,
    inlinemode: false
}

export const handler = async (event: CloudFrontResponseEvent) => {
    return await specProxyProcessResponse(event, config);
}

Check Edge Workers page for config options

Limitations of Edge@Lambdas

Before using this integration, understand these limitations:

• The timeout can be at most 5 seconds.

  • If Spec and Origin Server combined take more than 5 seconds to respond, the Edge@Lambda will return a 502 error.

• The max memory can be 128MB.

  • Our library is very compact and does little processing, but this limit can come into play when integrating with existing functions that are heavy in business logic.

  • We can also run into issues here with very large request sizes.

Lambda@Edge Tips

• For more information on working with lambdas and typescript:AWS Building Functions with TypeScript

• Since there is no debugger in Edge@Lambdas, it can be helpful to add log statements in the code for the entire event object and view the logs in CloudWatch.

• CloudWatch logs will be in the region closest to the viewer. It helps to know which region you are closest to when trying to access these logs.

• In order to deploy a new Edge@Lambda, you must first create a new version. You can't use $LATEST to refer to an Edge@Lambda in the CloudFront console.