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.

  • You cannot associate a Lambda function with a CloudFront distribution owned by another AWS account.

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

  • Transfer-Encoding

  • Via

Read-only Headers for CloudFront Viewer Response Events

  • Content-Encoding

  • Content-Length

  • Transfer-Encoding

  • Warning

  • Via

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 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 or nodejs8.10 runtime property.

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

  • You can't associate your Lambda function to a CloudFront distribution owned by another AWS account.

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

  • 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 response events as well as functions triggered by viewer request and response events can make network calls to resources on the internet, and to services in AWS regions such as Amazon S3 buckets, DynamoDB tables, or Amazon EC2 instances.

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.

Tagging

Some AWS services, including Amazon CloudFront and AWS Lambda, support adding tags to resources within the service. However, at this time, you cannot apply tags to Lambda@Edge resources. To learn more about tagging in CloudFront, see Tagging Amazon CloudFront Distributions.

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.