View a markdown version of this page

Cache behavior settings - Amazon CloudFront
Path patternOrigin or origin groupViewer protocol policyAllowed HTTP methodsField-level encryption configCached HTTP methodsAllow gRPC requests over HTTP/2Cache based on selected request headersAllowlist headersObject cachingMinimum TTLMaximum TTLDefault TTLForward cookiesAllowlist cookiesQuery string forwarding and cachingQuery string allowlistSmooth StreamingRestrict viewer access (use signed URLs or signed cookies)Trusted signersAWS account numbersCompress objects automaticallyCloudFront eventLambda function ARNInclude body

Cache behavior settings

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 the DistributionConfig 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.

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 pattern images/*.jpg applies to requests for any .jpg file in the images, images/product1, and images/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 and images/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:

Path pattern Files that match the path pattern

*.jpg

All .jpg files.

images/*.jpg

All .jpg files in the images directory and in subdirectories under the images directory.

a*.jpg

  • All .jpg files for which the file name begins with a, for example, apple.jpg and appalachian_trail_2012_05_21.jpg.

  • All .jpg files for which the file path begins with a, for example, abra/cadabra/magic.jpg.

a??.jpg

All .jpg files for which the file name begins with a and is followed by exactly two other characters, for example, ant.jpg and abe.jpg.

*.doc*

All files for which the file name extension begins with .doc, for example, .doc, .docx, and .docm files. You can't use the path pattern *.doc? in this case, because that path pattern wouldn't apply to requests for .doc files; the ? wildcard character replaces exactly one character.

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 file LOGO.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 select GET, 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 (the OPTIONS method is included in the cache key for OPTIONS requests). CloudFront does not cache responses to requests that use other methods.

Important

If you choose GET, HEAD, OPTIONS or GET, 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 use PUT, 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 the GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE methods. gRPC requires the POST method.

  • Select the gRPC checkbox that appears after you select the POST method.

  • For Supported HTTP versions, select HTTP/2.

For more information, see Using gRPC with CloudFront distributions.

Cache based on selected request headers

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, see HTTP 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.

Allowlist 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 choose Add. 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), see Quotas 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, choose