Menu
AWS Lambda
Developer Guide

AWS Lambda@Edge (Preview)

Lambda@Edge (preview) allows you to run Lambda functions at the AWS Edge locations in response to CloudFront events, without provisioning or managing servers, by using the AWS Lambda serverless programming model. Before Lambda@Edge, while you could use CloudFront to deliver pages faster, customized processing still required requests to be forwarded back to compute resources at centralized servers. This slows down the end user experience. You can use Lambda@Edge in response to CloudFront events and to customize content delivered through CloudFront at reduced network latency with execution at the AWS edge locations.

Functions deployable to edge locations are written in Node.js. With Lambda@Edge, a virtually unlimited set of solutions is available, including the following:

  • Write Lambda functions to inspect cookies to rewrite URLs to different versions of a site for A/B testing.

  • Send different objects to your users based on the user-agent header (for example, send images that have different resolutions to users based on their devices).

  • Inspect headers or authorized tokens, inserting a corresponding header and allowing access control before forwarding a request to the origin.

  • Add, drop, and modify headers, and rewrite the URL path to direct users to different objects in cache.

  • Generate new HTTP responses to do things like redirect unauthenticated users to login pages, or create and deliver static webpages right from the edge. For more information, see HTTP Response Generation.

While the runtime (nodejs4.3-edge) is the same as the standard Node environment supported in AWS Lambda (nodejs4.3), there are some additional restrictions. For example, there are no built-in libraries available. You can use Lambda functions to respond to four different trigger points for a CloudFront request:

  • When a request is first received from a viewer (viewer request).

  • When the Lambda function receives a response from the origin (origin response).

  • When the Lambda function forwards a request to the origin (origin request).

  • Before the Lambda function responds to the end viewer (viewer response).

For more information about setting up CloudFront with Lambda@Edge, see Using CloudFront with Lambda@Edge.

How It Works

After you have identified a decision that can be made at the AWS Edge location (where all the information needed to make the decision is available within the function and the request/response itself), first identify which cache behaviors and at what point in the request flow (viewer request, origin request, origin response, or viewer response) the logic applies to.

You then create a Lambda function to encapsulate the logic. Functions that run on Lambda@Edge are written in nodejs4.3; however, instead of selecting the standard nodejs4.3 as the runtime of your Lambda function, you must select nodejs4.3-edge. Next, you use CloudFront API operations or the AWS Lambda console to associate the appropriate events (viewer request etc.) for a specific CloudFront distribution to your Lambda function. This the same model as all other event sources—for example, when triggering Lambda functions for Amazon S3 events, you associate specific events like Amazon S3 PUT for a specific bucket. Once saved, the next time an applicable request is made to your distribution, the function is propagated to the CloudFront edge, scaled, and executed as needed.

Authoring Functions for Lambda@Edge

The programming model for using Node.js with Lambda@Edge is the same as using Lambda in a region. For more information, see Programming Model (Node.js). You can also include third-party packages. However, when responding to request events, the request object should be returned as part of callback so that CloudFront can modify the request. The same applies while responding to response events. The response object should be returned.

Copy
exports.origin_response_handler = function(event, context, callback) { var headers = event.Records[0].cf.response.headers; for (var header in headers) { /* your custom header logic */; } callback(null, event.Records[0].cf.response); }
Copy
exports.origin_request_handler = function(event, context, callback) { var request = event.Records[0].cf.request; request.uri = /* your custom uri logic */; var headers = request.headers; for (var header in headers) { /* your custom header logic */; } callback(null , event.Records[0].cf.request); }

Note

Lambda@Edge functions will not have write access to write to the local file system, and cannot make remote network calls to external services.

Permissions

If you are using the AWS CLI, Lambda@Edge requires an additional permission. You will need to add the following principal to the resource policy, as shown below:

Copy
aws lambda add-permission --function-name arn --statement-id statement-id --action lambda:GetFunction --principal edgelambda.amazonaws.com

When using the Lambda console, these permissions are added automatically.

Testing and Debugging

Lambda@Edge functions can be tested on the Lambda console with test events modeled after the Request or Response events. For sample events, see Lambda@Edge Event Structure. However, the testing in the console only validates logic, and does not apply service limits specific to Lambda@Edge which come into play if your function is deployed to the AWS Edge. To avoid discrepancies in behavior while testing in a region, ensure that your function does not make remote calls (either through the AWS SDK or via direct http/https requests) or use environment variables, and configure the function to approximate its eventual edge deployment by selecting 128MB and 1 second of duration. Note that the actual duration limit during the preview is 50ms. For more information, see Lambda@Edge Limits. You can create logging statements for Lambda functions running on Lambda@Edge that will write to CloudWatch Logs. For more information, see Programming Model for Logs.

Simple Setup

In the Lambda console:

  1. Choose the cloudfront-ab-test blueprint.

  2. In Triggers, choose the CloudFront distribution, cache behavior, and an event type.

    • Choose CloudFront from the service list.

    • Choose distribution.

    • Choose cache behavior identified by the URL pattern.

      With Lambda@Edge, you associate functions at the cache behavior level. To specify different caching policies (how long to cache an object, what headers to include in the cache key, which origin has the content) you have the following options:

      • *.jpg

      • *.php

      • * (default)

    • Choose the CloudFront event type.

  3. Choose Edge-Node.js 4.3 as the runtime for your function. Edge-Node.js 4.3 is the only supported runtime for functions that run on Lambda@Edge today.

  4. Choose Create function. When the specified CloudFront distribution receives a request, the function is propagated to the edge location, and your function will start triggering to the associated event.

Note

Note that you need to add a special permission to allow Lambda@Edge to propagate your functions to edge locations. When using the console, these are automatically added. If you create your functions using the API or AWS CLI, see Permissions.

Lambda@Edge Limits

Due to the constrained execution environment, Lambda@Edge has additional restrictions over and above the default Lambda limits. Functions running in Edge locations do not count against your concurrency limit for the region. For more information, see AWS Lambda Limits.

Item Default Limit
Max memory setting 128 MB
Maximum duration 50 ms
Size of code/dependencies that you can zip into a deployment package (uncompressed zip/jar size) 1 MB
Maximum Global TPS 100