Menu
Amazon CloudFront
Developer Guide (API Version 2016-09-29)

Requirements and Restrictions on Lambda Functions

See the following sections for requirements and restrictions on using Lambda functions with CloudFront.

CloudFront Distributions and Associations

  • You can create triggers (associations) for Lambda functions for a maximum of 25 distributions per AWS account.

  • You can create a maximum of 100 triggers (associations) for a distribution.

CloudFront Triggers for Lambda Functions

  • You can add triggers only for a numbered version, not for $LATEST or for aliases.

  • You can add triggers only for functions in the US East (N. Virginia) Region.

  • To add triggers, the IAM execution role associated with your Lambda function must be assumable by the service principals lambda.amazonaws.com and edgelambda.amazonaws.com. For more information, see Setting IAM Permissions and Roles for Lambda@Edge in the IAM User Guide.

CloudWatch Logs

For information about Amazon CloudWatch Logs limits, see CloudWatch Logs Limits in the Amazon CloudWatch User Guide.

Headers

Note the following requirements and restrictions on using headers with Lambda@Edge.

Blacklisted Headers

Blacklisted headers aren't exposed and can't be added by Lambda@Edge functions. If your Lambda function adds a blacklisted header, the request fails CloudFront validation. CloudFront returns HTTP status code 502 (Bad Gateway) to the viewer.

  • Connection

  • Expect

  • Keep-alive

  • Proxy-Authenticate

  • Proxy-Authorization

  • Proxy-Connection

  • Trailer

  • Upgrade

  • X-Accel-Buffering

  • X-Accel-Charset

  • X-Accel-Limit-Rate

  • X-Accel-Redirect

  • X-Amz-Cf-*

  • X-Amzn-*

  • X-Cache

  • X-Edge-*

  • X-Forwarded-Proto

  • X-Real-IP

Read-only Headers

Read-only headers can be read but not edited. You can use them as input to CloudFront caching logic, and your Lambda function can read the header values, but it can't change the values. If your Lambda function adds or edits a read-only header, the request fails CloudFront validation. CloudFront returns HTTP status code 502 (Bad Gateway) to the viewer.

Read-only Headers for CloudFront Viewer Request Events

  • Content-Length

  • Host

  • Transfer-Encoding

  • Via

Read-only Headers for CloudFront Origin Request Events

  • Accept-Encoding

  • Content-Length

  • If-Modified-Since

  • If-None-Match

  • If-Range

  • If-Unmodified-Since

  • Range

  • Transfer-Encoding

  • Via

Read-only Headers for CloudFront Origin Response Events

  • Content-Encoding

  • Content-Length

  • Transfer-Encoding

  • Via

Read-only Headers for CloudFront Viewer Response Events

  • Content-Encoding

  • Content-Length

  • Transfer-Encoding

  • Warning

  • Via

Restricted Headers for CloudFront Origin Request Events

By default, CloudFront removes the following headers from viewer requests. You can add or edit these headers in CloudFront origin request events only if the CloudFront distribution is configured to cache based on the headers. This causes CloudFront to forward the headers to your origin instead of removing them.

If a Lambda function adds or changes a restricted header and the CloudFront distribution is not configured to cache based on that header, the request fails CloudFront validation. CloudFront returns HTTP status code 502 (Bad Gateway) to the viewer.

For information about how to configure CloudFront to cache based on specified headers, see Cache Based on Selected Request Headers in the topic Values That You Specify When You Create or Update a Web Distribution.

  • Accept

  • Accept-Charset

  • Accept-Language

  • Authorization

  • Referer

  • TE

CloudFront-* Headers

A Lambda function can read, edit, remove, or add any of the following headers.

  • CloudFront-Forwarded-Proto

  • CloudFront-Is-Desktop-Viewer

  • CloudFront-Is-Mobile-Viewer

  • CloudFront-Is-SmartTV-Viewer

  • CloudFront-Is-Tablet-Viewer

  • CloudFront-Viewer-Country

Note the following:

  • If you want CloudFront to add these headers, you must configure CloudFront to cache based on these headers. For information about configuring CloudFront to cache based on specified headers, see Cache Based on Selected Request Headers in the topic Values That You Specify When You Create or Update a Web Distribution.

  • CloudFront adds the headers after the viewer request event.

  • If the viewer adds headers that have these names, CloudFront overwrites the header values.

  • For viewer events, CloudFront-Viewer-Country is blacklisted. Blacklisted headers aren't exposed and can't be added by Lambda@Edge functions. If your Lambda function adds a blacklisted header, the request fails CloudFront validation, and CloudFront returns HTTP status code 502 (Bad Gateway) to the viewer.

For more information, see the following examples:

HTTP Status Codes

CloudFront doesn't execute Lambda functions for origin response and viewer response events if the origin returns HTTP status code 400 or higher.

Lambda Function Configuration and Execution Environment

  • You must create functions with the nodejs6.10 runtime property.

  • A function can use a maximum of 128 MB of memory.

  • You can't configure your Lambda function to access resources inside your VPC.

  • The maximum execution timeout for CloudFront origin request and origin response events is 3 seconds.

  • The maximum execution timeout for CloudFront viewer request events and viewer response events is 1 second.

  • The Dead Letter Queue (DLQ) isn't supported.

  • The maximum compressed size of your Lambda function and any included libraries is 1 MB.

  • Environment variables aren't supported.

Limits

For information about limits, see the following documentation:

Microsoft Smooth Streaming

You can't create triggers for a CloudFront distribution that you're using for on-demand streaming of media files that you've transcoded into the Microsoft Smooth Streaming format.

Network Access

Functions triggered by origin request and origin response events can make network calls to resources on the internet and services in AWS regions such as S3 buckets, DynamoDB tables, or EC2 instances.

We don't support network calls for viewer request and viewer response events.

Query String Parameters

  • To access a query string in a Lambda function, use event.Records[0].cf.request.querystring.

  • A function can update a query string for viewer and origin request events. The updated query string can't include spaces, control characters, or the fragment identifier (#).

  • A function can read a query string only for origin and viewer response events.

  • Configuring CloudFront to cache based on query string parameters affects whether a function can access the query string:

    • Viewer request and response events – A function can access a query string regardless of the setting for Query String Forwarding and Caching.

    • Origin request and response events – A function can access a query string only if Query String Forwarding and Caching is set either to Forward All, Cache Based on Whitelist or to Forward All, Cache Based on All.

  • We recommend that you use percent encoding for the URI and query string. For more information, see URI and Query String Encoding.

  • The total size of the URI (event.Records[0].cf.request.uri) and the query string (event.Records[0].cf.request.querystring) must be less than 8,192 characters.

For more information, see Configuring CloudFront to Cache Based on Query String Parameters.

Response Size Limits

The maximum size of a response that is generated by a Lambda function (including the headers and body) depends on the event that triggered the function:

  • Viewer request events – 40 KB

  • Origin request events – 256 KB

If the response is larger than the allowed size, CloudFront returns an HTTP 502 status code (Bad Gateway) to the viewer.

URI

If a function changes the URI for a request, that doesn't change the cache behavior for the request or the origin that the request is forwarded to.

URI and Query String Encoding

Lambda functions require the URI and query string to be UTF-8 encoded. (Percent encoding is compatible with UTF-8 encoding.) The behavior of CloudFront and Lambda depends on the following:

  • The encoding of the URI and query string that CloudFront received in the request from the viewer

  • Whether the URI or query string is changed by a function that is triggered by a viewer request or origin request event

Values Are UTF-8 Encoded

CloudFront forwards the values to your Lambda function without changing them.

Values Are ISO 8859-1 Encoded

CloudFront converts ISO 8859-1 character encoding to UTF-8 encoding before forwarding the values to your Lambda function.

Values Are Encoded Using Some Other Character Encoding

If the values are encoded using any other character encoding, CloudFront assumes that they're ISO 8859-1 encoded and tries to convert from ISO 8859-1 encoding to UTF-8 encoding.

Important

The converted version might be an inaccurate interpretation of the values in the original request. This can cause a Lambda function or your origin to produce an unintended result.

The value that CloudFront forwards to your origin server depends on whether functions that are triggered by viewer request or origin request events change the URI or query string:

  • If the functions don't change the URI or query string – CloudFront forwards the values that CloudFront received in the request from the viewer to your origin server.

  • If the functions do change the URI or query string – CloudFront forwards the UTF-8 encoded value.

In both cases, the behavior is unaffected by the character encoding of the request from the viewer.