Helper methods for origin modification
This section applies if you dynamically update or change the origin used on the request inside your CloudFront Functions code. You can update the origin on viewer request CloudFront Functions only. CloudFront Functions has a module that provides helper methods to dynamically update or change the origin.
To use this module, create a CloudFront function using JavaScript runtime 2.0 and include the following statement in the first line of the function code:
import cf from 'cloudfront';
For more information, see JavaScript runtime 2.0 features for CloudFront Functions.
Note
The Test API and Test console pages don't test whether an origin modification has occurred. However, testing ensures that the function code executes without error.
Choose between CloudFront Functions and Lambda@Edge
You can update your origins by using either CloudFront Functions or Lambda@Edge.
When using CloudFront Functions to update origins, you use the viewer request event trigger, which means this logic will run on every request when this function is used. When using Lambda@Edge, the origin updating capabilities are on the origin request event trigger, which means this logic only runs on cache misses.
Your choice depends largely on your workload and any existing usage of CloudFront Functions and Lambda@Edge on your distributions. The following considerations can help you decide whether to use CloudFront Functions or Lambda@Edge to update your origins.
CloudFront Functions is most useful in the following situations:
When your requests are dynamic (meaning they cannot be cached) and will always go to origin. CloudFront Functions provides better performance and lower overall cost.
When you already have an existing viewer request CloudFront function that will run on every request, you can add the origin updating logic into the existing function.
To use CloudFront Functions to update origins, see the helper methods in the following topics.
Lambda@Edge is most useful in the following situations:
When you have highly cacheable content, Lambda@Edge can be more cost-efficient because it runs only on cache misses, while CloudFront Functions runs on every request.
When you already have an existing origin request Lambda@Edge function, you can add the origin updating logic into the existing function.
When your origin update logic requires fetching data from third-party data sources, such as Amazon DynamoDB or Amazon S3.
For more information about Lambda@Edge, see Customize at the edge with Lambda@Edge.
updateRequestOrigin() method
Use the updateRequestOrigin()
method to update the origin settings
for a request. You can use this method to update existing origin properties for
origins that are already defined in your distribution, or to define a new origin for
the request. To do so, specify the properties that you want to change.
Important
Any settings that you don't specify in the updateRequestOrigin()
will inherit the same settings from the
existing origin's configuration.
The origin set by the updateRequestOrigin()
method can be any HTTP
endpoint and doesn't need to be an existing origin within your CloudFront
distribution.
Notes
-
If you're updating an origin that is part of an origin group, only the primary origin of the origin group is updated. The secondary origin remains unchanged.
-
You can't use the
updateRequestOrigin()
method to update VPC origins. The request will fail.
Request
updateRequestOrigin({origin properties})
The origin properties
can contain the following:
- domainName (optional)
-
The domain name of the origin. If this is not provided, the domain name from the assigned origin is used instead.
- For custom origins
-
Specify a DNS domain name, such as
www.example.com
. The domain name can't include a colon (:) and can't be an IP address. The domain name can be up to 253 characters. - For S3 origins
-
Specify the DNS domain name of the Amazon S3 bucket, such as
amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com
. The name can be up to 128 characters, and must be all lowercase.
- originPath (optional)
-
The directory path at the origin where the request should locate content. The path should start with a forward slash (/) but shouldn't end with one. For example, it shouldn't end with
example-path/
. If this is not provided, then the origin path from the assigned origin is used.- For custom origins
-
The path should be URL encoded and have a maximum length of 255 characters.
- customHeaders (optional)
-
You can include custom headers with the request by specifying a header name and value pair for each custom header. The format is different than that of the request and response headers in the event structure. Use the following key-value pair syntax:
{"key1": "value1", "key2": "value2", ...}
You can't add headers that are disallowed, and a header with the same name can't also be present in the incoming request
headers
. Header name must be lowercase in your function code. When CloudFront Functions converts the event object back into an HTTP request, the first letter of each word in header names is capitalized, and words are separated by a hyphen.For example, if you function code adds a header named
example-header-name
, CloudFront converts this toExample-Header-Name
in the HTTP request. For more information, see Custom headers that CloudFront can’t add to origin requests and Restrictions on edge functions.If this is not provided, then any custom headers from the assigned origin are used.
- connectionAttempts (optional)
-
The number of times that CloudFront attempts to connect to the origin. The minimum is 1 and the maximum is 3. If this is not provided, the connection attempts from the assigned origin are used.
- originShield (optional)
-
This enables or updates CloudFront Origin Shield. Using Origin Shield can help reduce the load on your origin. For more information, see Using Amazon CloudFront Origin Shield. If this is not provided, the Origin Shield settings from the assigned origin are used.
- enabled (required)
-
Boolean expression to enable or disable Origin Shield. Accepts a
true
orfalse
value. - region (required when enabled)
-
The AWS Region for Origin Shield. Specify the AWS Region that has the lowest latency to your origin. Use the Region code, not the Region name. For example, use
us-east-2
to specify the US East (Ohio) Region.When you enable CloudFront Origin Shield, you must specify the AWS Region for it. For a list of available AWS Regions and help choosing the best Region for your origin, see Choosing the AWS Region for Origin Shield.
- originAccessControlConfig (optional)
-
The unique identifier of an origin access control (OAC) for this origin. This is only used when the origin supports a CloudFront OAC, such as Amazon S3, Lambda function URLs, MediaStore, and MediaPackage V2. If this is not provided, then the OAC settings from the assigned origin are used.
This does not support the legacy origin access identity (OAI). For more information, see Restrict access to an AWS origin.
- enabled (required)
-
Boolean expression to enable or disable OAC. Accepts a
true
orfalse
value. - signingBehavior (required when enabled)
-
Specifies which requests CloudFront signs (adds authentication information to). Specify
always
for the most common use case. For more information, see .This field can have one of the following values:
-
always
– CloudFront signs all origin requests, overwriting theAuthorization
header from the viewer request if one exists. -
never
– CloudFront doesn’t sign any origin requests. This value turns off origin access control for the origin. -
no-override
– If the viewer request doesn’t contain theAuthorization
header, then CloudFront signs the origin request. If the viewer request contains theAuthorization
header, then CloudFront doesn’t sign the origin request and instead passes along theAuthorization
header from the viewer request.Warning
To pass along the
Authorization
header from the viewer request, you must add it to an origin request policy for all cache behaviors that use origins associated with this origin access control. For more information, see Control origin requests with a policy.
-
- signingProtocol (required when enabled)
-
The signing protocol of the OAC, which determines how CloudFront signs (authenticates) requests. The only valid value is
sigv4
. - originType (required when enabled)
-
The type of origin for this OAC. Valid values include
s3
,mediapackagev2
,mediastore
, andlambda
.
- timeouts (optional)
-
Timeouts that you can specify for how long CloudFront should attempt to wait for origins to respond or send data. If this is not provided, then the timeout settings from the assigned origin are used.
- readTimeout (optional)
-
Timeouts only apply to custom origins, not Amazon S3 origins. (S3 origin configurations will ignore these settings.)
readTimeout
applies to both of the following values:-
How long (in seconds) CloudFront waits for a response after forwarding a request to the origin.
-
How long (in seconds) CloudFront waits after receiving a packet of a response from the origin and before receiving the next packet.
The minimum timeout is 1 second and the maximum is 60 seconds. For more information, see Response timeout (custom origins only).
-
- keepAliveTimeout (optional)
-
Timeouts only apply to custom origins, not Amazon S3 origins. (S3 origin configurations will ignore these settings.)
keepAliveTimeout
specifies how long CloudFront should try to maintain the connection to the origin after receiving the last packet of the response. The minimum timeout is 1 second and the maximum is 60 seconds. For more information, see Keep-alive timeout (custom origins only). - connectionTimeout (optional)
-
The number of seconds that CloudFront waits when trying to establish a connection to the origin. The minimum timeout is 1 second and the maximum is 10 seconds. For more information, see Connection timeout.
- customOriginConfig (optional)
-
Use
customOriginConfig
to specify connection settings for origins that are not an Amazon S3 bucket. There is one exception: you can specify these settings if the S3 bucket is configured with static website hosting. (Other types of S3 bucket configurations will ignore these settings.) IfcustomOriginConfig
is not provided, then the settings from the assigned origin are used.- port (required)
-
The HTTP port that CloudFront uses to connect to the origin. Specify the HTTP port that the origin listens on.
- protocol (required)
-
Specifies the protocol (HTTP or HTTPS) that CloudFront uses to connect to the origin. Valid values are as follows:
-
http
– CloudFront always uses HTTP to connect to the origin -
https
– CloudFront always uses HTTPS to connect to the origin
-
- sslProtocols (required)
-
A list that specifies the minimum SSL/TLS protocol that CloudFront uses when connecting to your origin over HTTPS. Valid values include
SSLv3
,TLSv1
,TLSv1.1
, andTLSv1.2
. For more information, see Minimum origin SSL protocol.
Example – Update to Amazon S3 request origin
The following example changes the viewer request’s origin to an S3 bucket, enables OAC, and resets custom headers sent to the origin.
cf.updateRequestOrigin({ "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com", "originAccessControlConfig": { "enabled": true, "signingBehavior": "always", "signingProtocol": "sigv4", "originType": "s3" }, // Empty object resets any header configured on the assigned origin "customHeaders": {} });
Example – Update to Application Load Balancer request origin
The following example changes the viewer request’s origin to an Application Load Balancer origin and sets a custom header and timeouts.
cf.updateRequestOrigin({ "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com", "timeouts": { "readTimeout": 30, "connectionTimeout": 5 }, "customHeaders": { "x-stage": "production", "x-region": "us-east-1" } });
Example – Update to origin with Origin Shield enabled
In the following example, the origin in the distribution has Origin Shield enabled. The function code updates only the domain name used for the origin and omits all the other optional parameters. In this case, Origin Shield will still be used with the modified origin domain name because the Origin Shield parameters were not updated.
cf.updateRequestOrigin({ "domainName" : "www.example.com" });