Cache behavior settings - Amazon CloudFront (original) (raw)

By setting the cache behavior, you can configure a variety of CloudFront functionality for a given URL path pattern for files on your website. For example, one cache behavior might apply to all .jpg files in the images directory on a web server that you're using as an origin server for CloudFront. The functionality that you can configure for each cache behavior includes:

• The path pattern
• If you have configured multiple origins for your CloudFront distribution, the origin to which you want CloudFront to forward your requests
• Whether to forward query strings to your origin
• Whether accessing the specified files requires signed URLs
• Whether to require users to use HTTPS to access those files
• The minimum amount of time that those files stay in the CloudFront cache regardless of the value of any Cache-Control headers that your origin adds to the files

When you create a new distribution, you specify settings for the default cache behavior, which automatically forwards all requests to the origin that you specify when you create the distribution. After you create a distribution, you can create additional cache behaviors that define how CloudFront responds when it receives a request for objects that match a path pattern, for example,*.jpg. If you create additional cache behaviors, the default cache behavior is always the last to be processed. Other cache behaviors are processed in the order in which they're listed in the CloudFront console or, if you're using the CloudFront API, the order in which they're listed in theDistributionConfig element for the distribution. For more information, see Path pattern.

When you create a cache behavior, you specify the one origin from which you want CloudFront to get objects. As a result, if you want CloudFront to distribute objects from all of your origins, you must have at least as many cache behaviors (including the default cache behavior) as you have origins. For example, if you have two origins and only the default cache behavior, the default cache behavior causes CloudFront to get objects from one of the origins, but the other origin is never used.

For the current maximum number of cache behaviors that you can add to a distribution, or to request a higher quota (formerly known as limit), see General quotas on distributions.

Topics

• Path pattern
• Origin or origin group
• Viewer protocol policy
• Allowed HTTP methods
• Field-level encryption config
• Cached HTTP methods
• Allow gRPC requests over HTTP/2
• Cache based on selected request headers
• Allowlist headers
• Object caching
• Minimum TTL
• Maximum TTL
• Default TTL
• Forward cookies
• Allowlist cookies
• Query string forwarding and caching
• Query string allowlist
• Smooth Streaming
• Restrict viewer access (use signed URLs or signed cookies)
• Trusted signers
• AWS account numbers
• Compress objects automatically
• CloudFront event
• Lambda function ARN
• Include body

Path pattern

A path pattern (for example, images/*.jpg) specifies to which requests you want this cache behavior to apply. When CloudFront receives an end-user request, the requested path is compared with path patterns in the order in which cache behaviors are listed in the distribution. The first match determines which cache behavior is applied to that request. For example, suppose you have three cache behaviors with the following three path patterns, in this order:

• images/*.jpg
• images/*
• *.gif

Note

You can optionally include a slash (/) at the beginning of the path pattern, for example, /images/*.jpg. CloudFront behavior is the same with or without the leading /. If you don't specify the / at the beginning of the path, this character is automatically implied; CloudFront treats the path the same with or without the leading /. For example, CloudFront treats /*product.jpg the same as*product.jpg

A request for the file images/sample.gif doesn't satisfy the first path pattern, so the associated cache behaviors are not applied to the request. The file does satisfy the second path pattern, so the cache behaviors associated with the second path pattern are applied even though the request also matches the third path pattern.

Note

When you create a new distribution, the value of Path Pattern for the default cache behavior is set to* (all files) and cannot be changed. This value causes CloudFront to forward all requests for your objects to the origin that you specified in the Origin domain field. If the request for an object does not match the path pattern for any of the other cache behaviors, CloudFront applies the behavior that you specify in the default cache behavior.

Important

Define path patterns and their sequence carefully or you may give users undesired access to your content. For example, suppose a request matches the path pattern for two cache behaviors. The first cache behavior does not require signed URLs and the second cache behavior does require signed URLs. Users are able to access the objects without using a signed URL because CloudFront processes the cache behavior associated with the first match.

If you're working with a MediaPackage channel, you must include specific path patterns for the cache behavior that you define for the endpoint type for your origin. For example, for a DASH endpoint, you type *.mpd for Path Pattern. For more information and specific instructions, see Serve live video formatted with AWS Elemental MediaPackage.

The path you specify applies to requests for all files in the specified directory and in subdirectories below the specified directory. CloudFront does not consider query strings or cookies when evaluating the path pattern. For example, if an images directory contains product1 and product2 subdirectories, the path patternimages/*.jpg applies to requests for any .jpg file in theimages, images/product1, andimages/product2 directories. If you want to apply a different cache behavior to the files in the images/product1 directory than the files in the images andimages/product2 directories, create a separate cache behavior for images/product1 and move that cache behavior to a position above (before) the cache behavior for the images directory.

You can use the following wildcard characters in your path pattern:

• * matches 0 or more characters.
• ? matches exactly 1 character.

The following examples show how the wildcard characters work:

The maximum length of a path pattern is 255 characters. The value can contain any of the following characters:

• A-Z, a-z
  Path patterns are case-sensitive, so the path pattern*.jpg doesn't apply to the fileLOGO.JPG
• 0-9
• _ - . * $ / ~ " ' @ : +
• &, passed and returned as &

Path normalization

CloudFront normalizes URI paths consistent with RFC 3986 and then matches the path with the correct cache behavior. Once the cache behavior is matched, CloudFront sends the raw URI path to the origin. If they don't match, requests are instead matched to your default cache behavior.

Some characters are normalized and removed from the path, such as multiple slashes (//) or periods (..). This can alter the URL that CloudFront uses to match the intended cache behavior.

Example

You specify the /a/b* and /a* paths for your cache behavior.

• A viewer sending the /a/b?c=1 path will match the/a/b* cache behavior.
• A viewer sending the /a/b/..?c=1 path will match the /a* cache behavior.

To work around the paths being normalized, you can update your request paths or the path pattern for the cache behavior.

Origin or origin group

This setting applies only when you create or update a cache behavior for an existing distribution.

Enter the value of an existing origin or origin group. This identifies the origin or origin group to which you want CloudFront to route requests when a request (such as https://example.com/logo.jpg) matches the path pattern for a cache behavior (such as *.jpg) or for the default cache behavior (*).

Viewer protocol policy

Choose the protocol policy that you want viewers to use to access your content in CloudFront edge locations:

• HTTP and HTTPS: Viewers can use both protocols.
• Redirect HTTP to HTTPS: Viewers can use both protocols, but HTTP requests are automatically redirected to HTTPS requests.
• HTTPS Only: Viewers can only access your content if they're using HTTPS.

For more information, see Require HTTPS for communication between viewers and CloudFront.

Allowed HTTP methods

Specify the HTTP methods that you want CloudFront to process and forward to your origin:

• GET, HEAD: You can use CloudFront only to get objects from your origin or to get object headers.
• GET, HEAD, OPTIONS: You can use CloudFront only to get objects from your origin, get object headers, or retrieve a list of the options that your origin server supports.
• GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE: You can use CloudFront to get, add, update, and delete objects, and to get object headers. In addition, you can perform other POST operations such as submitting data from a web form.

Note

If you're using gRPC in your workload, you must selectGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE. gRPC workloads require the POST method. For more information, see Using gRPC with CloudFront distributions.
CloudFront caches responses to GET and HEAD requests and, optionally, OPTIONS requests. Responses to OPTIONS requests are cached separately from responses to GET and HEAD requests (theOPTIONS method is included in the cache key forOPTIONS requests). CloudFront does not cache responses to requests that use other methods.

Important

If you choose GET, HEAD, OPTIONS orGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE, you might need to restrict access to your Amazon S3 bucket or to your custom origin to prevent users from performing operations that you don't want them to perform. The following examples explain how to restrict access:

• If you're using Amazon S3 as an origin for your distribution: Create a CloudFront origin access control to restrict access to your Amazon S3 content, and give permissions to the origin access control. For example, if you configure CloudFront to accept and forward these methods_only_ because you want to usePUT, you must still configure Amazon S3 bucket policies to handle DELETE requests appropriately. For more information, see Restrict access to an Amazon S3 origin.
• If you're using a custom origin: Configure your origin server to handle all methods. For example, if you configure CloudFront to accept and forward these methods only because you want to use POST, you must still configure your origin server to handle DELETE requests appropriately.

Field-level encryption config

If you want to enforce field-level encryption on specific data fields, in the dropdown list, choose a field-level encryption configuration.

For more information, see Use field-level encryption to help protect sensitive data.

Cached HTTP methods

Specify whether you want CloudFront to cache the response from your origin when a viewer submits an OPTIONS request. CloudFront always caches the response to GET and HEAD requests.

Allow gRPC requests over HTTP/2

Specify whether you want your distribution to allow gRPC requests. To enable gRPC, select the following settings:

• For Allowed HTTP methods, select theGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE methods. gRPC requires the POST method.
• Select the gRPC checkbox that appears after you select thePOST method.
• For Supported HTTP versions, select HTTP/2.

For more information, see Using gRPC with CloudFront distributions.

Specify whether you want CloudFront to cache objects based on the values of specified headers:

• None (improves caching) – CloudFront doesn't cache your objects based on header values.
• Allowlist – CloudFront caches your objects based only on the values of the specified headers. Use Allowlist Headers to choose the headers that you want CloudFront to base caching on.
• All – CloudFront doesn't cache the objects that are associated with this cache behavior. Instead, CloudFront sends every request to the origin. (Not recommended for Amazon S3 origins.)

Regardless of the option that you choose, CloudFront forwards certain headers to your origin and takes specific actions based on the headers that you forward. For more information about how CloudFront handles header forwarding, seeHTTP request headers and CloudFront behavior (custom and Amazon S3 origins).

For more information about how to configure caching in CloudFront by using request headers, see Cache content based on request headers.

These settings apply only when you choose Allowlist for Cache Based on Selected Request Headers.

Specify the headers that you want CloudFront to consider when caching your objects. Select headers from the list of available headers and chooseAdd. To forward a custom header, enter the name of the header in the field, and choose Add Custom.

For the current maximum number of headers that you can allowlist for each cache behavior, or to request a higher quota (formerly known as limit), seeQuotas on headers.

Object caching

If your origin server is adding a Cache-Control header to your objects to control how long the objects stay in the CloudFront cache and if you don't want to change the Cache-Control value, chooseUse Origin Cache Headers.

To specify a minimum and maximum time that your objects stay in the CloudFront cache regardless of Cache-Control headers, and a default time that your objects stay in the CloudFront cache when the Cache-Control header is missing from an object, choose Customize. Then specify values in the Minimum TTL,Default TTL, and Maximum TTL fields.

For more information, see Manage how long content stays in the cache (expiration).

Minimum TTL

Specify the minimum amount of time, in seconds, that you want objects to stay in the CloudFront cache before CloudFront sends another request to the origin to determine whether the object has been updated.

For more information, see Manage how long content stays in the cache (expiration).

Maximum TTL

Specify the maximum amount of time, in seconds, that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated. The value that you specify for Maximum TTL applies only when your origin adds HTTP headers such asCache-Control max-age, Cache-Control s-maxage, or Expires to objects. For more information, see Manage how long content stays in the cache (expiration).

To specify a value for Maximum TTL, you must choose the Customize option for the Object Caching setting.

The default value for Maximum TTL is 31536000 seconds (one year). If you change the value of Minimum TTL orDefault TTL to more than 31536000 seconds, then the default value of Maximum TTL changes to the value ofDefault TTL.

Default TTL

Specify the default amount of time, in seconds, that you want objects to stay in CloudFront caches before CloudFront forwards another request to your origin to determine whether the object has been updated. The value that you specify for Default TTL applies only when your origin does_not_ add HTTP headers such as Cache-Control max-age, Cache-Control s-maxage, orExpires to objects. For more information, see Manage how long content stays in the cache (expiration).

To specify a value for Default TTL, you must choose the Customize option for the Object Caching setting.

The default value for Default TTL is 86400 seconds (one day). If you change the value of Minimum TTL to more than 86400 seconds, then the default value of Default TTL changes to the value of Minimum TTL.

Forward cookies

Note

For Amazon S3 origins, this option applies to only buckets that are configured as a website endpoint.

Specify whether you want CloudFront to forward cookies to your origin server and, if so, which ones. If you choose to forward only selected cookies (an allowlist of cookies), enter the cookie names in the Allowlist Cookies field. If you choose All, CloudFront forwards all cookies regardless of how many your application uses.

Amazon S3 doesn't process cookies, and forwarding cookies to the origin reduces cache ability. For cache behaviors that are forwarding requests to an Amazon S3 origin, choose None for Forward Cookies.

For more information about forwarding cookies to the origin, go to Cache content based on cookies.

Allowlist cookies

Note

For Amazon S3 origins, this option applies to only buckets that are configured as a website endpoint.

If you chose Allowlist in the Forward Cookies list, then in the Allowlist Cookies field, enter the names of cookies that you want CloudFront to forward to your origin server for this cache behavior. Enter each cookie name on a new line.

You can specify the following wildcards to specify cookie names:

• * matches 0 or more characters in the cookie name
• ? matches exactly one character in the cookie name

For example, suppose viewer requests for an object include a cookie named:

userid_`member-number`

Where each of your users has a unique value formember-number. You want CloudFront to cache a separate version of the object for each member. You could accomplish this by forwarding all cookies to your origin, but viewer requests include some cookies that you don't want CloudFront to cache. Alternatively, you could specify the following value as a cookie name, which causes CloudFront to forward to the origin all of the cookies that begin with userid_:

userid_*

For the current maximum number of cookie names that you can allowlist for each cache behavior, or to request a higher quota (formerly known as limit), see Quotas on cookies (legacy cache settings).

Query string forwarding and caching

CloudFront can cache different versions of your content based on the values of query string parameters. Choose one of the following options:

None (Improves Caching)

Choose this option if your origin returns the same version of an object regardless of the values of query string parameters. This increases the likelihood that CloudFront can serve a request from the cache, which improves performance and reduces the load on your origin.

Forward all, cache based on allowlist

Choose this option if your origin server returns different versions of your objects based on one or more query string parameters. Then specify the parameters that you want CloudFront to use as a basis for caching in the Query string allowlist field.

Forward all, cache based on all

Choose this option if your origin server returns different versions of your objects for all query string parameters.

For more information about caching based on query string parameters, including how to improve performance, see Cache content based on query string parameters.

Query string allowlist

This setting applies only when you choose Forward all, cache based on allowlist for Query string forwarding and caching. You can specify the query string parameters that you want CloudFront to use as a basis for caching.

Smooth Streaming

Choose Yes if you want to distribute media files in the Microsoft Smooth Streaming format and you do not have an IIS server.

Choose No if you have a Microsoft IIS server that you want to use as an origin to distribute media files in the Microsoft Smooth Streaming format, or if you are not distributing Smooth Streaming media files.

Note

If you specify Yes, you can still distribute other content using this cache behavior if that content matches the value of Path Pattern.

For more information, see Configure video on demand for Microsoft Smooth Streaming.

Restrict viewer access (use signed URLs or signed cookies)

If you want requests for objects that match the PathPattern for this cache behavior to use public URLs, chooseNo.

If you want requests for objects that match the PathPattern for this cache behavior to use signed URLs, choose Yes. Then specify the AWS accounts that you want to use to create signed URLs; these accounts are known as trusted signers.

For more information about trusted signers, see Specify signers that can create signed URLs and signed cookies.

Trusted signers

This setting applies only when you choose Yes for Restrict Viewer Access (Use Signed URLs or Signed Cookies.

Choose which AWS accounts you want to use as trusted signers for this cache behavior:

• Self: Use the account with which you're currently signed into the AWS Management Console as a trusted signer. If you're currently signed in as an IAM user, the associated AWS account is added as a trusted signer.
• Specify Accounts: Enter account numbers for trusted signers in the AWS Account Numbers field.

To create signed URLs, an AWS account must have at least one active CloudFront key pair.

Important

If you're updating a distribution that you're already using to distribute content, add trusted signers only when you're ready to start generating signed URLs for your objects. After you add trusted signers to a distribution, users must use signed URLs to access the objects that match the PathPattern for this cache behavior.

AWS account numbers

This setting applies only when you choose Specify Accounts for Trusted Signers.

If you want to create signed URLs using AWS accounts in addition to or instead of the current account, enter one AWS account number per line in this field. Note the following:

• The accounts that you specify must have at least one active CloudFront key pair. For more information, see Create key pairs for your signers.
• You can't create CloudFront key pairs for IAM users, so you can't use IAM users as trusted signers.
• For information about how to get the AWS account number for an account, see View AWS account identifiers in the AWS account Management Reference Guide.
• If you enter the account number for the current account, CloudFront automatically checks the Self check box and removes the account number from the AWS Account Numbers list.

Compress objects automatically

If you want CloudFront to automatically compress files of certain types when viewers support compressed content, choose Yes. When CloudFront compresses your content, downloads are faster because the files are smaller, and your web pages render faster for your users. For more information, see Serve compressed files.

CloudFront event

This setting applies to Lambda Function Associations.

You can choose to run a Lambda function when one or more of the following CloudFront events occur:

• When CloudFront receives a request from a viewer (viewer request)
• Before CloudFront forwards a request to the origin (origin request)
• When CloudFront receives a response from the origin (origin response)
• Before CloudFront returns the response to the viewer (viewer response)

For more information, see Choose the event to trigger the function.

Lambda function ARN

This setting applies to Lambda Function Associations.

Specify the Amazon Resource Name (ARN) of the Lambda function that you want to add a trigger for. To learn how to get the ARN for a function, see step 1 of the procedure Adding Triggers by Using the CloudFront Console.

Include body

This setting applies to Lambda Function Associations.

For more information, see Include body.