Understand cache policies
You can use a cache policy to improve your cache hit ratio by controlling the values (URL query strings, HTTP headers, and cookies) that are included in the cache key. CloudFront provides some predefined cache policies, known as managed policies, for common use cases. You can use these managed policies, or you can create your own cache policy that's specific to your needs. For more information about the managed policies, see Use managed cache policies.
A cache policy contains the following settings, which are categorized into policy information, time to live (TTL) settings, and cache key settings.
Policy information
- Name
-
A name to identify the cache policy. In the console, you use the name to attach the cache policy to a cache behavior.
- Description
-
A comment to describe the cache policy. This is optional, but it can help you identify the purpose of the cache policy.
Time to live (TTL) settings
The time to live (TTL) settings work together with the Cache-Control
and Expires
HTTP headers (if they're in the origin response) to
determine how long objects in the CloudFront cache remain valid.
- Minimum TTL
-
The minimum amount of time, in seconds, that you want objects to stay in the CloudFront cache before CloudFront checks with the origin to see if the object has been updated. For more information, see Manage how long content stays in the cache (expiration).
- Maximum TTL
-
The maximum amount of time, in seconds, that objects stay in the CloudFront cache before CloudFront checks with the origin to see if the object has been updated. CloudFront uses this setting only when the origin sends
Cache-Control
orExpires
headers with the object. For more information, see Manage how long content stays in the cache (expiration). - Default TTL
-
The default amount of time, in seconds, that you want objects to stay in the CloudFront cache before CloudFront checks with the origin to see if the object has been updated. CloudFront uses this setting's value as the object's TTL only when the origin does not send
Cache-Control
orExpires
headers with the object. For more information, see Manage how long content stays in the cache (expiration).
Note
If the Minimum TTL, Maximum TTL, and Default TTL settings are all set to 0, this disables CloudFront caching.
Cache key settings
Cache key settings specify the values in viewer requests that CloudFront includes in the cache key. The values can include URL query strings, HTTP headers, and cookies. The values that you include in the cache key are automatically included in requests that CloudFront sends to the origin, known as origin requests. For information about controlling origin requests without affecting the cache key, see Control origin requests with a policy.
Cache key settings include:
- Headers
-
The HTTP headers in viewer requests that CloudFront includes in the cache key and in origin requests. For headers, you can choose one of the following settings:
-
None – The HTTP headers in viewer requests are not included in the cache key and are not automatically included in origin requests.
-
Include the following headers – You specify which of the HTTP headers in viewer requests are included in the cache key and automatically included in origin requests.
When you use the Include the following headers setting, you specify HTTP headers by their name, not their value. For example, consider the following HTTP header:
Accept-Language: en-US,en;q=0.5
In this case, you specify the header as
Accept-Language
, not asAccept-Language: en-US,en;q=0.5
. However, CloudFront includes the full header, including its value, in the cache key and in origin requests.You can also include certain headers generated by CloudFront in the cache key. For more information, see Add CloudFront request headers.
-
-
The cookies in viewer requests that CloudFront includes in the cache key and in origin requests. For cookies, you can choose one of the following settings:
-
None – The cookies in viewer requests are not included in the cache key and are not automatically included in origin requests.
-
All – All cookies in viewer requests are included in the cache key and are automatically included in origin requests.
-
Include specified cookies – You specify which of the cookies in viewer requests are included in the cache key and automatically included in origin requests.
-
Include all cookies except – You specify which of the cookies in viewer requests are not included in the cache key and are not automatically included in origin requests. All other cookies, except for the ones you specify, are included in the cache key and automatically included in origin requests.
When you use the Include specified cookies or Include all cookies except setting, you specify cookies by their name, not their value. For example, consider the following
Cookie
header:Cookie: session_ID=abcd1234
In this case, you specify the cookie as
session_ID
, not assession_ID=abcd1234
. However, CloudFront includes the full cookie, including its value, in the cache key and in origin requests. -
- Query strings
-
The URL query strings in viewer requests that CloudFront includes in the cache key and in origin requests. For query strings, you can choose one of the following settings:
-
None – The query strings in viewer requests are not included in the cache key and are not automatically included in origin requests.
-
All – All query strings in viewer requests are included in the cache key and are also automatically included in origin requests.
-
Include specified query strings – You specify which of the query strings in viewer requests are included in the cache key and automatically included in origin requests.
-
Include all query strings except – You specify which of the query strings in viewer requests are not included in the cache key and are not automatically included in origin requests. All other query strings, except for the ones you specify, are included in the cache key and automatically included in origin requests.
When you use the Include specified query strings or Include all query strings except setting, you specify query strings by their name, not their value. For example, consider the following URL path:
/content/stories/example-story.html?split-pages=false
In this case, you specify the query string as
split-pages
, not assplit-pages=false
. However, CloudFront includes the full query string, including its value, in the cache key and in origin requests. -
- Compression support
-
These settings enable CloudFront to request and cache objects that are compressed in the Gzip or Brotli compression formats, when the viewer supports it. These settings also allow CloudFront compression to work. Viewers indicate their support for these compression formats with the
Accept-Encoding
HTTP header.Note
The Chrome and Firefox web browsers support Brotli compression only when the request is sent using HTTPS. These browsers do not support Brotli with HTTP requests.
Enable these settings when any of the following are true:
-
Your origin returns Gzip compressed objects when viewers support them (requests contain the
Accept-Encoding
HTTP header withgzip
as a value). In this case, use the Gzip enabled setting (setEnableAcceptEncodingGzip
totrue
in the CloudFront API, AWS SDKs, AWS CLI, or AWS CloudFormation). -
Your origin returns Brotli compressed objects when viewers support them (requests contain the
Accept-Encoding
HTTP header withbr
as a value). In this case, use the Brotli enabled setting (setEnableAcceptEncodingBrotli
totrue
in the CloudFront API, AWS SDKs, AWS CLI, or AWS CloudFormation). -
The cache behavior that this cache policy is attached to is configured with CloudFront compression. In this case, you can enable caching for either Gzip or Brotli, or both. When CloudFront compression is enabled, enabling caching for both formats can help to reduce your costs for data transfer out to the internet.
Note
If you enable caching for one or both of these compression formats, do not include the
Accept-Encoding
header in an origin request policy that's associated with the same cache behavior. CloudFront always includes this header in origin requests when caching is enabled for either of these formats, so includingAccept-Encoding
in an origin request policy has no effect.If your origin server does not return Gzip or Brotli compressed objects, or the cache behavior is not configured with CloudFront compression, don't enable caching for compressed objects. If you do, it might cause a decrease in your cache hit ratio.
The following explains how these settings affect a CloudFront distribution. All of the following scenarios assume that the viewer request includes the
Accept-Encoding
header. When the viewer request does not include theAccept-Encoding
header, CloudFront doesn't include this header in the cache key and doesn't include it in the corresponding origin request.- When caching compressed objects is enabled for both compression formats
-
If the viewer supports both Gzip and Brotli—that is, if the
gzip
andbr
values are both in theAccept-Encoding
header in the viewer request—CloudFront does the following:-
Normalizes the header to
Accept-Encoding: br,gzip
and includes the normalized header in the cache key. The cache key doesn't include other values that were in theAccept-Encoding
header sent by the viewer. -
If the edge location has a Brotli or Gzip compressed object in the cache that matches the request and is not expired, the edge location returns the object to the viewer.
-
If the edge location doesn't have a Brotli or Gzip compressed object in the cache that matches the request and is not expired, CloudFront includes the normalized header (
Accept-Encoding: br,gzip
) in the corresponding origin request. The origin request doesn't include other values that were in theAccept-Encoding
header sent by the viewer.
If the viewer supports one compression format but not the other—for example, if
gzip
is a value in theAccept-Encoding
header in the viewer request butbr
is not—CloudFront does the following:-
Normalizes the header to
Accept-Encoding: gzip
and includes the normalized header in the cache key. The cache key doesn't include other values that were in theAccept-Encoding
header sent by the viewer. -
If the edge location has a Gzip compressed object in the cache that matches the request and is not expired, the edge location returns the object to the viewer.
-
If the edge location doesn't have a Gzip compressed object in the cache that matches the request and is not expired, CloudFront includes the normalized header (
Accept-Encoding: gzip
) in the corresponding origin request. The origin request doesn't include other values that were in theAccept-Encoding
header sent by the viewer.
To understand what CloudFront does if the viewer supports Brotli but not Gzip, replace the two compression formats with each other in the preceding example.
If the viewer does not support Brotli or Gzip—that is, the
Accept-Encoding
header in the viewer request does not containbr
orgzip
as values—CloudFront:-
Doesn't include the
Accept-Encoding
header in the cache key. -
Includes
Accept-Encoding: identity
in the corresponding origin request. The origin request doesn't include other values that were in theAccept-Encoding
header sent by the viewer.
-
- When caching compressed objects is enabled for one compression format, but not the other
-
If the viewer supports the format for which caching is enabled—for example, if caching compressed objects is enabled for Gzip and the viewer supports Gzip (
gzip
is one of the values in theAccept-Encoding
header in the viewer request)—CloudFront does the following:-
Normalizes the header to
Accept-Encoding: gzip
and includes the normalized header in the cache key. -
If the edge location has a Gzip compressed object in the cache that matches the request and is not expired, the edge location returns the object to the viewer.
-
If the edge location doesn't have a Gzip compressed object in the cache that matches the request and is not expired, CloudFront includes the normalized header (
Accept-Encoding: gzip
) in the corresponding origin request. The origin request doesn't include other values that were in theAccept-Encoding
header sent by the viewer.
This behavior is the same when the viewer supports both Gzip and Brotli (the
Accept-Encoding
header in the viewer request includes bothgzip
andbr
as values), because in this scenario, caching compressed objects for Brotli is not enabled.To understand what CloudFront does if caching compressed objects is enabled for Brotli but not Gzip, replace the two compression formats with each other in the preceding example.
If the viewer does not support the compression format for which caching is enabled (the
Accept-Encoding
header in the viewer request doesn't contain the value for that format), CloudFront:-
Doesn't include the
Accept-Encoding
header in the cache key. -
Includes
Accept-Encoding: identity
in the corresponding origin request. The origin request doesn't include other values that were in theAccept-Encoding
header sent by the viewer.
-
- When caching compressed objects is disabled for both compression formats
-
When caching compressed objects is disabled for both compression formats, CloudFront treats the
Accept-Encoding
header the same as any other HTTP header in the viewer request. By default, it's not included in the cache key and it's not included in origin requests. You can include it in the headers list in a cache policy or an origin request policy the same as any other HTTP header.
-