# Control the cache key with a policy With a CloudFront *cache policy*, you can specify the HTTP headers, cookies, and query strings that CloudFront includes in the *cache key* for objects that are cached at CloudFront edge locations. The cache key is the unique identifier for every object in the cache, and it determines whether a viewer's HTTP request results in a *cache hit*. A cache hit occurs when a viewer request generates the same cache key as a prior request, and the object for that cache key is in the edge location's cache and valid. When there's a cache hit, the object is served to the viewer from a CloudFront edge location, which has the following benefits: + Reduced load on your origin server + Reduced latency for the viewer Including fewer values in the cache key increases the likelihood of a cache hit. This can get you better performance from your website or application because there's a higher *cache hit ratio* (a higher proportion of viewer requests that result in a cache hit). For more information, see [Understand the cache key](understanding-the-cache-key.md). To control the cache key, you use a CloudFront *cache policy*. You attach a cache policy to one or more cache behaviors in a CloudFront distribution. You can also use the cache policy to specify time to live (TTL) settings for objects in the CloudFront cache, and enable CloudFront to request and cache compressed objects. **Note** Cache settings don't affect gRPC requests because gRPC traffic can't be cached. For more information, see [Using gRPC with CloudFront distributions](distribution-using-grpc.md). **Topics** + [ # Understand cache policies ](cache-key-understand-cache-policy.md) + [ # Create cache policies ](cache-key-create-cache-policy.md) + [ # Use managed cache policies ](using-managed-cache-policies.md) + [ # Understand the cache key ](understanding-the-cache-key.md) # 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](using-managed-cache-policies.md). 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)](Expiration.md). If your minimum TTL is greater than 0, CloudFront will cache content for at least the duration specified in the cache policy's minimum TTL, even if the `Cache-Control: no-cache`, `no-store`, or `private` directives are present in the origin headers. **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` or `Expires` headers with the object. For more information, see [Manage how long content stays in the cache (expiration)](Expiration.md). **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` or `Expires` headers with the object. For more information, see [Manage how long content stays in the cache (expiration)](Expiration.md). **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](controlling-origin-requests.md). Cache key settings include: + [Headers](#cache-policy-headers) + [Cookies](#cache-policy-cookies) + [Query strings](#cache-policy-query-strings) + [Compression support](#cache-policy-compressed-objects) **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 as `Accept-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](adding-cloudfront-headers.md). **Cookies** 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 as `session_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 as `split-pages=false`. However, CloudFront includes the full query string, including its value, in the cache key and in origin requests. For the cache key settings, CloudFront treats the asterisk character (`*`) for the headers, query strings, and cookies as a literal string, not as a wildcard. **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](ServingCompressedFiles.md) to work. Viewers indicate their support for these compression formats with the `Accept-Encoding` HTTP header. 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 with `gzip` as a value). In this case, use the **Gzip enabled** setting (set `EnableAcceptEncodingGzip` to `true` in the CloudFront API, AWS SDKs, AWS CLI, or CloudFormation). + Your origin returns Brotli compressed objects when viewers support them (requests contain the `Accept-Encoding` HTTP header with `br` as a value). In this case, use the **Brotli enabled** setting (set `EnableAcceptEncodingBrotli` to `true` in the CloudFront API, AWS SDKs, AWS CLI, or CloudFormation). + The cache behavior that this cache policy is attached to is configured with [CloudFront compression](ServingCompressedFiles.md). 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. If you enable caching for one or both of these compression formats, do not include the `Accept-Encoding` header in an [origin request policy](controlling-origin-requests.md) 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 including `Accept-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](cache-hit-ratio.md). 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 the `Accept-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` and `br` values are both in the `Accept-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 the `Accept-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 the `Accept-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 the `Accept-Encoding` header in the viewer request but `br` 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 the `Accept-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 the `Accept-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 contain `br` or `gzip` 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 the `Accept-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 the `Accept-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 the `Accept-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 both `gzip` *and* `br` 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 the `Accept-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. # Create 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. You can create a cache policy in the CloudFront console, with the AWS Command Line Interface (AWS CLI), or with the CloudFront API. After you create a cache policy, you attach it to one or more cache behaviors in a CloudFront distribution. ------ #### [ Console ] **To create a cache policy (console)** 1. Sign in to the AWS Management Console and open the **Policies** page in the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home?#/policies](https://console.aws.amazon.com/cloudfront/v4/home?#/policies). 1. Choose **Create cache policy**. 1. Choose the desired setting for this cache policy. For more information, see [Understand cache policies](cache-key-understand-cache-policy.md). 1. When finished, choose **Create**. After you create a cache policy, you can attach it to a cache behavior. **To attach a cache policy to an existing distribution (console)** 1. Open the **Distributions** page in the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home#/distributions](https://console.aws.amazon.com/cloudfront/v4/home#/distributions). 1. Choose the distribution to update, then choose the **Behaviors** tab. 1. Choose the cache behavior to update, then choose **Edit**. Or, to create a new cache behavior, choose **Create behavior**. 1. In the **Cache key and origin requests** section, make sure that **Cache policy and origin request policy** is chosen. 1. For **Cache policy**, choose the cache policy to attach to this cache behavior. 1. At the bottom of the page, choose **Save changes**. **To attach a cache policy to a new distribution (console)** 1. Open the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home). 1. Choose **Create distribution**. 1. In the **Cache key and origin requests** section, make sure that **Cache policy and origin request policy** is chosen. 1. For **Cache policy**, choose the cache policy to attach to this distribution's default cache behavior. 1. Choose the desired settings for the origin, default cache behavior, and other distribution settings. For more information, see [All distribution settings reference](distribution-web-values-specify.md). 1. When finished, choose **Create distribution**. ------ #### [ CLI ] To create a cache policy with the AWS Command Line Interface (AWS CLI), use the **aws cloudfront create-cache-policy** command. You can use an input file to provide the command's input parameters, rather than specifying each individual parameter as command line input. **To create a cache policy (CLI with input file)** 1. Use the following command to create a file named `cache-policy.yaml` that contains all of the input parameters for the **create-cache-policy** command. ``` aws cloudfront create-cache-policy --generate-cli-skeleton yaml-input > cache-policy.yaml ``` 1. Open the file named `cache-policy.yaml` that you just created. Edit the file to specify the cache policy settings that you want, then save the file. You can remove optional fields from the file, but don't remove the required fields. For more information about the cache policy settings, see [Understand cache policies](cache-key-understand-cache-policy.md). 1. Use the following command to create the cache policy using input parameters from the `cache-policy.yaml` file. ``` aws cloudfront create-cache-policy --cli-input-yaml file://cache-policy.yaml ``` Make note of the `Id` value in the command's output. This is the cache policy ID, and you need it to attach the cache policy to a CloudFront distribution's cache behavior. **To attach a cache policy to an existing distribution (CLI with input file)** 1. Use the following command to save the distribution configuration for the CloudFront distribution that you want to update. Replace *distribution\$1ID* with the distribution's ID. ``` aws cloudfront get-distribution-config --id distribution_ID --output yaml > dist-config.yaml ``` 1. Open the file named `dist-config.yaml` that you just created. Edit the file, making the following changes to each cache behavior that you are updating to use a cache policy. + In the cache behavior, add a field named `CachePolicyId`. For the field's value, use the cache policy ID that you noted after creating the policy. + Remove the `MinTTL`, `MaxTTL`, `DefaultTTL`, and `ForwardedValues` fields from the cache behavior. These settings are specified in the cache policy, so you can't include these fields and a cache policy in the same cache behavior. + Rename the `ETag` field to `IfMatch`, but don't change the field's value. Save the file when finished. 1. Use the following command to update the distribution to use the cache policy. Replace *distribution\$1ID* with the distribution's ID. ``` aws cloudfront update-distribution --id distribution_ID --cli-input-yaml file://dist-config.yaml ``` **To attach a cache policy to a new distribution (CLI with input file)** 1. Use the following command to create a file named `distribution.yaml` that contains all of the input parameters for the **create-distribution** command. ``` aws cloudfront create-distribution --generate-cli-skeleton yaml-input > distribution.yaml ``` 1. Open the file named `distribution.yaml` that you just created. In the default cache behavior, in the `CachePolicyId` field, enter the cache policy ID that you noted after creating the policy. Continue editing the file to specify the distribution settings that you want, then save the file when finished. For more information about the distribution settings, see [All distribution settings reference](distribution-web-values-specify.md). 1. Use the following command to create the distribution using input parameters from the `distribution.yaml` file. ``` aws cloudfront create-distribution --cli-input-yaml file://distribution.yaml ``` ------ #### [ API ] To create a cache policy with the CloudFront API, use [CreateCachePolicy](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateCachePolicy.html). For more information about the fields that you specify in this API call, see [Understand cache policies](cache-key-understand-cache-policy.md) and the API reference documentation for your AWS SDK or other API client. After you create a cache policy, you can attach it to a cache behavior, using one of the following API calls: + To attach it to a cache behavior in an existing distribution, use [UpdateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateDistribution.html). + To attach it to a cache behavior in a new distribution, use [CreateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateDistribution.html). For both of these API calls, provide the cache policy's ID in the `CachePolicyId` field, inside a cache behavior. For more information about the other fields that you specify in these API calls, see [All distribution settings reference](distribution-web-values-specify.md) and the API reference documentation for your AWS SDK or other API client. ------ # Use managed cache policies CloudFront provides a set of managed cache policies that you can attach to any of your distribution's cache behaviors. With a managed cache policy, you don't need to write or maintain your own cache policy. The managed policies use settings that are optimized for specific use cases. To use a managed cache policy, you attach it to a cache behavior in your distribution. The process is the same as when you create a cache policy, but instead of creating a new one, you just attach one of the managed cache policies. You attach the policy either by name (with the console) or by ID (with the AWS CLI or SDKs). The names and IDs are listed in the following section. For more information, see [Create cache policies](cache-key-create-cache-policy.md). The following topics describe the managed cache policies that you can use. **Topics** + [ ## Amplify ](#managed-cache-policy-amplify) + [ ## CachingDisabled ](#managed-cache-policy-caching-disabled) + [ ## CachingOptimized ](#managed-cache-caching-optimized) + [ ## CachingOptimizedForUncompressedObjects ](#managed-cache-caching-optimized-uncompressed) + [ ## Elemental-MediaPackage ](#managed-cache-policy-mediapackage) + [ ## UseOriginCacheControlHeaders ](#managed-cache-policy-origin-cache-headers) + [ ## UseOriginCacheControlHeaders-QueryStrings ](#managed-cache-policy-origin-cache-headers-query-strings) ## Amplify [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/2e54312d-136d-493c-8eb9-b001f22f67d2) This policy is designed for use with an origin that is an [AWS Amplify](https://aws.amazon.com/amplify/) web app. When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `2e54312d-136d-493c-8eb9-b001f22f67d2` This policy has the following settings: + **Minimum TTL:** 2 seconds + **Maximum TTL:** 600 seconds (10 minutes) + **Default TTL:** 2 seconds + **Headers included in cache key:** + `Authorization` + `CloudFront-Viewer-Country` + `Host` The normalized `Accept-Encoding` header is also included because the cache compressed objects setting is enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). + **Cookies included in cache key:** All cookies are included. + **Query strings included in cache key:** All query strings are included. + **Cache compressed objects setting:** Enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). **Warning** Because this policy has a minimum TTL greater than 0, CloudFront will cache content for at least the duration specified in the cache policy's minimum TTL, even if the `Cache-Control: no-cache`, `no-store`, or `private` directives are present in the origin headers. ### AWS Amplify Hosting cache policies Amplify uses the following managed cache policies to optimize the default cache configuration for customers' applications: + [Amplify-Default](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/4d1d2f1d-3a71-49ad-9e08-7ea5d843a556) + [Amplify-DefaultNoCookies](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/a6bad946-36c3-4c33-aa98-362c74a7fb13) + [Amplify-ImageOptimization](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/1c6db51a-a33f-469a-8245-dae26771f530) + [Amplify-StaticContent](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/7e5fad67-ee98-4ad0-b05a-394999eefc1a) **Note** These policies are only used by Amplify. We don't recommend that you use these policies for your distributions. For more information about managing cache configuration for your Amplify hosted application, see [Managing cache configuration](https://docs.aws.amazon.com/amplify/latest/userguide/caching.html) in the *Amplify Hosting User Guide*. ## CachingDisabled [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/4135ea2d-6df8-44a3-9df3-4b5a84be39ad) This policy disables caching. This policy is useful for dynamic content and for requests that are not cacheable. When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `4135ea2d-6df8-44a3-9df3-4b5a84be39ad` This policy has the following settings: + **Minimum TTL:** 0 seconds + **Maximum TTL:** 0 seconds + **Default TTL:** 0 seconds + **Headers included in the cache key:** None + **Cookies included in the cache key:** None + **Query strings included in the cache key:** None + **Cache compressed objects setting:** Disabled ## CachingOptimized [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/658327ea-f89d-4fab-a63d-7e88639e58f6) This policy is designed to optimize cache efficiency by minimizing the values that CloudFront includes in the cache key. CloudFront doesn't include any query strings or cookies in the cache key, and only includes the normalized `Accept-Encoding` header. This enables CloudFront to separately cache objects in the Gzip and Brotli compressions formats when the origin returns them or when [CloudFront edge compression](ServingCompressedFiles.md) is enabled. When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `658327ea-f89d-4fab-a63d-7e88639e58f6` This policy has the following settings: + **Minimum TTL:** 1 second. + **Maximum TTL:** 31,536,000 seconds (365 days). + **Default TTL:** 86,400 seconds (24 hours). + **Headers included in the cache key:** None are explicitly included. The normalized `Accept-Encoding` header is included because the cache compressed objects setting is enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). + **Cookies included in the cache key:** None. + **Query strings included in the cache key:** None. + **Cache compressed objects setting:** Enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). **Warning** Because this policy has a minimum TTL greater than 0, CloudFront will cache content for at least the duration specified in the cache policy's minimum TTL, even if the `Cache-Control: no-cache`, `no-store`, or `private` directives are present in the origin headers. ## CachingOptimizedForUncompressedObjects [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/b2884449-e4de-46a7-ac36-70bc7f1ddd6d) This policy is designed to optimize cache efficiency by minimizing the values included in the cache key. No query strings, headers, or cookies are included. This policy is identical to the previous one, but it disables the cache compressed objects setting. When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `b2884449-e4de-46a7-ac36-70bc7f1ddd6d` This policy has the following settings: + **Minimum TTL:** 1 second + **Maximum TTL:** 31,536,000 seconds (365 days) + **Default TTL:** 86,400 seconds (24 hours) + **Headers included in the cache key:** None + **Cookies included in the cache key:** None + **Query strings included in the cache key:** None + **Cache compressed objects setting:** Disabled **Warning** Because this policy has a minimum TTL greater than 0, CloudFront will cache content for at least the duration specified in the cache policy's minimum TTL, even if the `Cache-Control: no-cache`, `no-store`, or `private` directives are present in the origin headers. ## Elemental-MediaPackage [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/08627262-05a9-4f76-9ded-b50ca2e3a84f) This policy is designed for use with an origin that is an AWS Elemental MediaPackage endpoint. When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `08627262-05a9-4f76-9ded-b50ca2e3a84f` This policy has the following settings: + **Minimum TTL:** 0 seconds + **Maximum TTL:** 31,536,000 seconds (365 days) + **Default TTL:** 86,400 seconds (24 hours) + **Headers included in the cache key:** + `Origin` The normalized `Accept-Encoding` header is also included because the cache compressed objects setting is enabled for Gzip. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). + **Cookies included in the cache key:** None + **Query strings included in the cache key:** + `aws.manifestfilter` + `start` + `end` + `m` + **Cache compressed objects setting:** Enabled for Gzip. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). ## UseOriginCacheControlHeaders [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/83da9c7e-98b4-4e11-a168-04f0df8e2c65) This policy is designed for use with an origin that returns `Cache-Control` HTTP response headers and does not serve different content based on values present in the query string. If your origin serves different content based on values present in the query string, consider using [UseOriginCacheControlHeaders-QueryStrings](#managed-cache-policy-origin-cache-headers-query-strings). When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `83da9c7e-98b4-4e11-a168-04f0df8e2c65` This policy has the following settings: + **Minimum TTL:** 0 seconds + **Maximum TTL:** 31,536,000 seconds (365 days) + **Default TTL:** 0 seconds + **Headers included in the cache key:** + `Host` + `Origin` + `X-HTTP-Method-Override` + `X-HTTP-Method` + `X-Method-Override` The normalized `Accept-Encoding` header is also included because the cache compressed objects setting is enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). + **Cookies included in the cache key:** All cookies are included. + **Query strings included in the cache key:** None. + **Cache compressed objects setting:** Enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). ## UseOriginCacheControlHeaders-QueryStrings [View this policy in the CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home#/policies/cache/4cc15a8a-d715-48a4-82b8-cc0b614638fe) This policy is designed for use with an origin that returns `Cache-Control` HTTP response headers and serves different content based on values present in the query string. If your origin does not serve different content based on values present in the query string, consider using [UseOriginCacheControlHeaders](#managed-cache-policy-origin-cache-headers). When using CloudFormation, the AWS CLI, or the CloudFront API, the ID for this policy is: `4cc15a8a-d715-48a4-82b8-cc0b614638fe` This policy has the following settings: + **Minimum TTL:** 0 seconds + **Maximum TTL:** 31,536,000 seconds (365 days) + **Default TTL:** 0 seconds + **Headers included in the cache key:** + `Host` + `Origin` + `X-HTTP-Method-Override` + `X-HTTP-Method` + `X-Method-Override` The normalized `Accept-Encoding` header is also included because the cache compressed objects setting is enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). + **Cookies included in the cache key:** All cookies are included. + **Query strings included in the cache key:** All query strings are included. + **Cache compressed objects setting:** Enabled. For more information, see [Compression support](cache-key-understand-cache-policy.md#cache-policy-compressed-objects). # Understand the cache key The *cache key* determines whether a viewer request to a CloudFront edge location results in a *cache hit*. The cache key is the unique identifier for an object in the cache. Each object in the cache has a unique cache key. A cache hit occurs when a viewer request generates the same cache key as a prior request, and the object for that cache key is in the edge location’s cache and valid. When there’s a cache hit, the requested object is served to the viewer from a CloudFront edge location, which has the following benefits: + Reduced load on your origin server + Reduced latency for the viewer You can get better performance from your website or application when you have a higher *cache hit ratio* (a higher proportion of viewer requests that result in a cache hit). One way to improve your cache hit ratio is to include only the minimum necessary values in the cache key. For more information, see the following sections. You can modify the values (URL query strings, HTTP headers, and cookies) in the cache key by using a [cache policy](controlling-the-cache-key.md). (You can also modify the cache key by using a [Lambda@Edgefunction](lambda-at-the-edge.md) or a [CloudFront Function](cloudfront-functions.md) on a viewer request.) Before modifying the cache key, it’s important to understand how your application is designed and when and how it might serve different responses based on characteristics of the viewer request. When a value in the viewer request determines the response that your origin returns, you should include that value in the cache key. But if you include a value in the cache key that doesn’t affect the response that your origin returns, you might end up caching duplicate objects. ## Default cache key By default, the cache key for a CloudFront distribution includes the following information: + The domain name of the CloudFront distribution (for example, d111111abcdef8.cloudfront.net) + The URL path of the requested object (for example, `/content/stories/example-story.html`) **Note** The `OPTIONS` method is included in the cache key for `OPTIONS` requests. This means that responses to `OPTIONS` requests are cached separately from responses to `GET` and `HEAD` requests. Other values from the viewer request are not included in the cache key, by default. Consider the following HTTP request from a web browser. ``` GET /content/stories/example-story.html?ref=0123abc&split-pages=false HTTP/1.1 Host: d111111abcdef8.cloudfront.net User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/68.0 Accept: text/html,*/* Accept-Language: en-US,en Cookie: session_id=01234abcd Referer: https://news.example.com/ ``` When a viewer request like this example comes in to a CloudFront edge location, CloudFront uses the cache key to determine if there’s a cache hit. By default, only the following components of the request are included in the cache key: `/content/stories/example-story.html` and `d111111abcdef8.cloudfront.net`. If the requested object is not in the cache (a cache miss), then CloudFront sends a request to the origin to get the object. After getting the object, CloudFront returns it to the viewer and stores it in the edge location’s cache. When CloudFront receives another request for the same object, as determined by the cache key, CloudFront serves the cached object to the viewer immediately, without sending a request to the origin. For example, consider the following HTTP request that comes in after the previous request. ``` GET /content/stories/example-story.html?ref=xyz987&split-pages=true HTTP/1.1 Host: d111111abcdef8.cloudfront.net User-Agent: Mozilla/5.0 AppleWebKit/537.36 Chrome/83.0.4103.116 Accept: text/html,*/* Accept-Language: en-US,en Cookie: session_id=wxyz9876 Referer: https://rss.news.example.net/ ``` This request is for the same object as the previous request, but is different from the previous request. It has a different URL query string, different `User-Agent` and `Referer` headers, and a different `session_id` cookie. However, none of these values are part of the cache key by default, so this second request results in a cache hit. ## Customize the cache key In some cases, you might want to include more information in the cache key, even though doing so might result in fewer cache hits. You specify what to include in the cache key by using a [cache policy](controlling-the-cache-key.md). For example, if your origin server uses the `Accept-Language` HTTP header in viewer requests to return different content based on the viewer’s language, you might want to include this header in the cache key. When you do that, CloudFront uses this header to determine cache hits, and includes the header in *origin requests* (requests that CloudFront sends to the origin when there’s a cache miss). One potential consequence of including additional values in the cache key is that CloudFront might end up caching duplicate objects because of the variation that can occur in viewer requests. For example, viewers might send any of the following values for the `Accept-Language` header: + `en-US,en` + `en,en-US` + `en-US, en` + `en-US` All of these different values indicate that the viewer’s language is English, but the variation can cause CloudFront to cache the same object multiple times. This can reduce cache hits and increase the number of origin requests. You could avoid this duplication by not including the `Accept-Language` header in the cache key, and instead configuring your website or application to use different URLs for content in different languages (for example, `/en-US/content/stories/example-story.html`). For any given value that you intend to include in the cache key, you should make sure that you understand how many different variations of that value might appear in viewer requests. For certain request values, it rarely makes sense to include them in the cache key. For example, the `User-Agent` header can have thousands of unique variations, so it’s generally not a good candidate for including in the cache key. Cookies that have user-specific or session-specific values and are unique across thousands (or even millions) of requests are also not good candidates for cache key inclusion. If you do include these values in the cache key, each unique variation results in another copy of the object in the cache. If these copies of the object are not unique, or if you end up with such a large number of slightly different objects that each object only gets a small number of cache hits, you might want to consider a different approach. You can exclude these highly variable values from the cache key, or you can mark objects as non-cacheable. Use caution when customizing the cache key. Sometimes it’s desirable, but it can have unintended consequences such as caching duplicate objects, lowering your cache hit ratio, and increasing the number of origin requests. If your origin website or application needs to receive certain values from viewer requests for analytics, telemetry, or other uses, but these values don’t change the object that the origin returns, use an [origin request policy](controlling-origin-requests.md) to include these values in origin requests but *not* include them in the cache key.