Restrictions on edge functions
The following topics describe the restrictions that apply to CloudFront Functions and Lambda@Edge. Some restrictions apply to all edge functions, while others apply only to CloudFront Functions or Lambda@Edge.
For information about quotas (formerly referred to as limits), see Quotas on CloudFront Functions and Quotas on Lambda@Edge.
Topics
Restrictions on all edge functions
The following restrictions apply to all edge functions, both CloudFront Functions and Lambda@Edge.
AWS account ownership
To associate an edge function with a CloudFront distribution, the function and distribution must be owned by the same AWS account.
Combining CloudFront Functions with Lambda@Edge
For a given cache behavior, the following restrictions apply:
-
Each event type (viewer request, origin request, origin response, and viewer response) can have only one edge function association.
-
You cannot combine CloudFront Functions and Lambda@Edge in viewer events (viewer request and viewer response).
All other combinations of edge functions are allowed. The following table explains the allowed combinations.
CloudFront Functions |
|||
Viewer request |
Viewer response |
||
Lambda@Edge |
Viewer request |
Not allowed |
Not allowed |
Origin request |
Allowed |
Allowed |
|
Origin response |
Allowed |
Allowed |
|
Viewer response |
Not allowed |
Not allowed |
HTTP status codes
CloudFront does not invoke edge functions for viewer response events when the origin returns HTTP status code 400 or higher.
Edge functions for viewer response events cannot modify the HTTP status code of the response, regardless of whether the response came from the origin or the CloudFront cache.
Lambda@Edge functions for origin response events are invoked for all origin responses, including when the origin returns HTTP status code 400 or higher. For more information, see Updating HTTP responses in origin response triggers.
HTTP headers
Certain HTTP headers are disallowed, which means they’re not exposed to edge functions and functions can’t add them. Other headers are read-only, which means functions can read them but can’t add or modify them.
Disallowed headers
The following HTTP headers are not exposed to edge functions, and functions can’t add them. If your function adds one of these headers, it fails CloudFront validation and 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-Auth
-
X-Amzn-Cf-Billing
-
X-Amzn-Cf-Id
-
X-Amzn-Cf-Xff
-
X-Amzn-Errortype
-
X-Amzn-Fle-Profile
-
X-Amzn-Header-Count
-
X-Amzn-Header-Order
-
X-Amzn-Lambda-Integration-Tag
-
X-Amzn-RequestId
-
X-Cache
-
X-Edge-*
-
X-Forwarded-Proto
-
X-Real-IP
Read-only headers
The following headers are read-only. Your function can read them and use them as input to the function logic, but it can’t change the values. If your function adds or edits a read-only header, the request fails CloudFront validation and CloudFront returns HTTP status code 502 (Bad Gateway) to the viewer.
Read-only headers in viewer request events
The following headers are read-only in viewer request events.
-
Content-Length
-
Host
-
Transfer-Encoding
-
Via
Read-only headers in origin request events (Lambda@Edge only)
The following headers are read-only in origin request events, which exist only in Lambda@Edge.
-
Accept-Encoding
-
Content-Length
-
If-Modified-Since
-
If-None-Match
-
If-Range
-
If-Unmodified-Since
-
Transfer-Encoding
-
Via
Read-only headers in origin response events (Lambda@Edge only)
The following headers are read-only in origin response events, which exist only in Lambda@Edge.
-
Transfer-Encoding
-
Via
Read-only headers in viewer response events
The following headers are read-only in viewer response events.
-
Content-Encoding
-
Content-Length
-
Transfer-Encoding
-
Warning
-
Via
Query strings
The following restrictions apply to functions that read, update, or create a query string in a request URI.
-
(Lambda@Edge only) To access the query string in an origin request or origin response function, your cache policy or origin request policy must be set to All for Query strings.
-
A function can create or update a query string for viewer request and origin request events (origin request events exist only in Lambda@Edge).
-
A function can read a query string, but cannot create or update one, for origin response and viewer response events (origin response events exist only in Lambda@Edge).
-
If a function creates or updates a query string, the following restrictions apply:
-
The query string can’t include spaces, control characters, or the fragment identifier (
#
). -
The total size of the URI, including the query string, must be less than 8,192 characters.
-
We recommend that you use percent encoding for the URI and query string. For more information, see URI and query string encoding.
-
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.
The total size of the URI, including the query string, must be less than 8,192 characters.
URI and query string encoding
URI and query string values passed to edge functions are UTF-8 encoded. Your function should use UTF-8 encoding for the URI and query string values that it returns. Percent encoding is compatible with UTF-8 encoding.
The following list explains how CloudFront handles URI and query string value encoding:
-
When values in the request are UTF-8 encoded, CloudFront forwards the values to your function without changing them.
-
When values in the request are ISO-8859-1 encoded
, CloudFront converts the values to UTF-8 encoding before forwarding them to your function. -
When values in the request are encoded using some other character encoding, CloudFront assumes that they’re ISO-8859-1 encoded and tries to convert from ISO-8859-1 to UTF-8.
Important The converted characters might be an inaccurate interpretation of the values in the original request. This might cause your function or your origin to produce an unintended result.
The URI and query string values that CloudFront forwards to your origin depend on whether a function changes the values:
-
If a function does not change the URI or query string, CloudFront forwards the values that it received in the request to your origin.
-
If a function changes the URI or query string, CloudFront forwards the UTF-8 encoded values.
Microsoft Smooth Streaming
You cannot use edge functions with a CloudFront distribution that you’re using for streaming media files that you’ve transcoded into the Microsoft Smooth Streaming format.
Tagging
You cannot add tags to edge functions. To learn more about tagging in CloudFront, see Tagging Amazon CloudFront distributions.
Restrictions on CloudFront Functions
The following restrictions apply only to CloudFront Functions.
Logs
Function logs in CloudFront Functions are truncated at 10 KB.
Request body
CloudFront Functions cannot access the body of the HTTP request.
Runtime
The CloudFront Functions runtime environment does not support dynamic code evaluation, and it restricts access to the network, file system, and timers. For more information, see Restricted features.
Compute utilization
CloudFront Functions have a limit on the time they can take to run, measured as compute utilization. Compute utilization is a number between 0 and 100 that indicates the amount of time that the function took to run as a percentage of the maximum allowed time. For example, a compute utilization of 35 means that the function completed in 35% of the maximum allowed time.
When you test a function, you can see the
compute utilization value in the output of the test event. For production functions,
you can view the compute utilization
metric on the Monitoring page in the CloudFront console
Restrictions on Lambda@Edge
The following restrictions apply only to Lambda@Edge.
Lambda function version
You must use a numbered version of the Lambda function, not $LATEST
or
aliases.
Lambda region
The Lambda function must be in the US East (N. Virginia) Region.
Lambda role permissions
The IAM execution role associated with the Lambda function must allow the service
principals lambda.amazonaws.com
and
edgelambda.amazonaws.com
to assume the role. For more information, see
Setting IAM permissions and roles for
Lambda@Edge.
Lambda features and supported runtimes
The following Lambda features are not supported by Lambda@Edge:
-
Configuration of your Lambda function to access resources inside your VPC.
-
Lambda functions with AWS Lambda layers.
-
Lambda functions with more than 512 MB of ephemeral storage.
Lambda@Edge supports Lambda functions with the following runtimes:
Node.js |
Python |
---|---|
|
|
¹This version of Node.js has reached end of life. You can’t create or update
functions with this version. If you have an existing function with this version, you
can associate it with a CloudFront distribution. Functions with this version that are
already associated with a distribution continue to run. However, we recommend moving
your function to a newer version of Node.js. For more information, see Runtime
deprecation policy in the AWS Lambda Developer Guide and the Node.js release
schedule
²This version of Node.js has reached end of life, and it reaches end of
support phase 2 in Lambda on August 30, 2021. Starting on August 30, 2021, you can’t
create or update functions with this version. If you have an existing function with
this version, you can associate it with a CloudFront distribution. Functions with this
version that are already associated with a distribution continue to run. However, we
recommend moving your function to a newer version of Node.js. For more information,
see Runtime deprecation policy in the AWS Lambda Developer Guide and the Node.js release
schedule
CloudFront headers
Lambda@Edge functions can read, edit, remove, or add any of the following CloudFront 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 add them using a cache policy or origin request policy.
-
CloudFront adds the headers after the viewer request event, which means they are not available to Lambda@Edge in a viewer request function.
-
If the viewer request includes headers that have these names, and you configured CloudFront to add these headers using a cache policy or origin request policy, then CloudFront overwrites the header values that were in the viewer request. Viewer-facing functions see the header value from the viewer request, while origin-facing functions see the header value that CloudFront added.
-
¹
CloudFront-Viewer-Country
header – If a viewer request function adds this header, it fails validation and CloudFront returns HTTP status code 502 (Bad Gateway) to the viewer.
Restrictions on the request body with the include body option
When you choose the Include Body option to expose the request body to your Lambda@Edge function, the following information and size quotas apply to the portions of the body that are exposed or replaced.
-
CloudFront always base64 encodes the request body before exposing it to Lambda@Edge.
-
If the request body is large, CloudFront truncates it before exposing it to Lambda@Edge, as follows:
-
For viewer request events, the body is truncated at 40 KB.
-
For origin request events, the body is truncated at 1 MB.
-
-
If you access the request body as read-only, CloudFront sends the full original request body to the origin.
-
If your Lambda@Edge function replaces the request body, the following size quotas apply to the body that the function returns:
-
If the Lambda@Edge function returns the body as plain text:
-
For viewer request events, the body is truncated at 40 KB.
-
For origin request events, the body is truncated at 1 MB.
-
-
If the Lambda@Edge function returns the body as base64 encoded text:
-
For viewer request events, the body is truncated at 53.2 KB.
-
For origin request events, the body is truncated at 1.33 MB.
-
-