From 9bab0054f8ee131f7288b9e69ca29abb48a51281 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Thu, 7 May 2026 09:56:36 +0100 Subject: [PATCH] [Cache] Simplify cache-rules docs and fix critical bugs Apply ELI5 analysis to 6 files (1 skipped as correct Terraform ref): - index.mdx: Tighten run-on sentence, add Oxford comma - order.mdx: Fix inconsistent Cache Rules capitalization, remove future tense - settings.mdx: Fix 3 invalid JSON examples (missing commas), fix misplaced hyphen in cache-control, fix first person (our/we), fix wordy phrasing - page-rules-migration.mdx: Add Cache Everything explanation, fix redundant note label - create-dashboard.mdx: Fix skipped step number (7 was missing), replace cloudflare.com with example.com per style guide - create-api.mdx: Fix wrong API link (pointed to Update ruleset instead of Update rule) --- .../cache/how-to/cache-rules/create-api.mdx | 2 +- .../how-to/cache-rules/create-dashboard.mdx | 10 +++++----- .../docs/cache/how-to/cache-rules/index.mdx | 4 ++-- .../docs/cache/how-to/cache-rules/order.mdx | 10 +++++----- .../cache-rules/page-rules-migration.mdx | 6 ++---- .../docs/cache/how-to/cache-rules/settings.mdx | 18 +++++++++--------- 6 files changed, 24 insertions(+), 26 deletions(-) diff --git a/src/content/docs/cache/how-to/cache-rules/create-api.mdx b/src/content/docs/cache/how-to/cache-rules/create-api.mdx index 1354c02c3637e17..1c928f1731cdfde 100644 --- a/src/content/docs/cache/how-to/cache-rules/create-api.mdx +++ b/src/content/docs/cache/how-to/cache-rules/create-api.mdx @@ -32,7 +32,7 @@ When creating a cache rule via API, make sure you: * kind: `zone` * phase: `http_request_cache_settings` 3. Use the [Update a zone ruleset](/api/resources/rulesets/methods/update/) operation to add a cache rule to the list of ruleset rules. Alternatively, include the rule in the [Create a zone ruleset](/api/resources/rulesets/methods/create/) request mentioned in the previous step. -4. (Optional) To update an existing cache rule, use the [Update a zone ruleset rule](/api/resources/rulesets/methods/update/) operation. For an example, refer to the section below. +4. (Optional) To update an existing cache rule, use the [Update a zone ruleset rule](/api/resources/rulesets/subresources/rules/methods/edit/) operation. For an example, refer to the section below. ## Example requests diff --git a/src/content/docs/cache/how-to/cache-rules/create-dashboard.mdx b/src/content/docs/cache/how-to/cache-rules/create-dashboard.mdx index feed28b48bd1e5f..0554af9eb020b1b 100644 --- a/src/content/docs/cache/how-to/cache-rules/create-dashboard.mdx +++ b/src/content/docs/cache/how-to/cache-rules/create-dashboard.mdx @@ -29,7 +29,7 @@ import { Render, DashButton } from "~/components"; -8. Following the selection of the field and operator, enter the corresponding value that will trigger the Cache Rule. For example, if the selected field is `Hostname` and the operator is `equals`, a value of `cloudflare.com` would mean the rule matches any request to that hostname. +7. Following the selection of the field and operator, enter the corresponding value that will trigger the Cache Rule. For example, if the selected field is `Hostname` and the operator is `equals`, a value of `example.com` would mean the rule matches any request to that hostname.
@@ -41,12 +41,12 @@ import { Render, DashButton } from "~/components"; Rules can be further customized by using the **Edit expression** option. You can find more information in [Edit expressions in the dashboard](/ruleset-engine/rules-language/expressions/edit-expressions/). ::: -9. Under **Then**, in the **Cache eligibility** section, select [**Bypass cache**](/cache/how-to/cache-rules/settings/#bypass-cache) if you want matching requests to not be cacheable, or **Eligible for cache** if you want Cloudflare to attempt to cache them. Note that [cache-control headers](/cache/concepts/cache-control/) can also impact cache eligibility. +8. Under **Then**, in the **Cache eligibility** section, select [**Bypass cache**](/cache/how-to/cache-rules/settings/#bypass-cache) if you want matching requests to not be cacheable, or **Eligible for cache** if you want Cloudflare to attempt to cache them. Note that [cache-control headers](/cache/concepts/cache-control/) can also impact cache eligibility. -10. If you selected **Eligible for cache** in the previous step, you can customize the options described in the [Available settings](/cache/how-to/cache-rules/settings/) section. +9. If you selected **Eligible for cache** in the previous step, you can customize the options described in the [Available settings](/cache/how-to/cache-rules/settings/) section. -11. Under **Place at**, from the dropdown, you can select the order of your rule. From the main page, you can also change the order of the rules you have created. +10. Under **Place at**, from the dropdown, you can select the order of your rule. From the main page, you can also change the order of the rules you have created. -12. To save and deploy your rule, select **Deploy**. If you are not ready to deploy your rule, select **Save as Draft**. +11. To save and deploy your rule, select **Deploy**. If you are not ready to deploy your rule, select **Save as Draft**. diff --git a/src/content/docs/cache/how-to/cache-rules/index.mdx b/src/content/docs/cache/how-to/cache-rules/index.mdx index 5fef58843218c26..bcfe6d321816225 100644 --- a/src/content/docs/cache/how-to/cache-rules/index.mdx +++ b/src/content/docs/cache/how-to/cache-rules/index.mdx @@ -8,9 +8,9 @@ products: import { FeatureTable, Render } from "~/components"; -Use Cache Rules to customize cache settings on Cloudflare. Cache Rules allows you to make adjustments to what is eligible to cache, how long it should be cached and where, as well as trigger specific interactions with Cloudflare's cache and other Rules products for matching requests. +Use Cache Rules to customize cache settings on Cloudflare. Cache Rules allows you to control what is eligible to cache, how long it is cached and where, and trigger specific interactions with Cloudflare's cache and other Rules products for matching requests. -Cache Rules can be created in the [dashboard](/cache/how-to/cache-rules/create-dashboard/), via [API](/cache/how-to/cache-rules/create-api/) or [Terraform](/cache/how-to/cache-rules/terraform-example/). +Cache Rules can be created in the [dashboard](/cache/how-to/cache-rules/create-dashboard/), via [API](/cache/how-to/cache-rules/create-api/), or [Terraform](/cache/how-to/cache-rules/terraform-example/). :::note[Notes] diff --git a/src/content/docs/cache/how-to/cache-rules/order.mdx b/src/content/docs/cache/how-to/cache-rules/order.mdx index 40377bc15fa1145..c5bb5cd9a7dbd08 100644 --- a/src/content/docs/cache/how-to/cache-rules/order.mdx +++ b/src/content/docs/cache/how-to/cache-rules/order.mdx @@ -14,15 +14,15 @@ head: import { Render } from "~/components" -Cache rules affect requests differently from Page Rules. This is how they are applied: +Cache Rules affect requests differently from Page Rules. The following rules determine how they are applied: -1. Cache Rules are stackable. This means that multiple matching rules can be combined and applied to the same request. For example, if multiple cache rules match the same URL, then the features set in those cache rules will all be applied in order. If several matching rules set a value for the same setting, the value in the last matching rule wins. For an example of a similar scenario where multiple rules match, refer to the [Origin Rules FAQ](/rules/origin-rules/faq/#what-happens-if-more-than-one-origin-rule-matches-the-current-request). +1. Cache Rules are stackable. This means that multiple matching rules can be combined and applied to the same request. For example, if multiple Cache Rules match the same URL, then the features set in those Cache Rules will all be applied in order. If several matching rules set a value for the same setting, the value in the last matching rule wins. For an example of a similar scenario where multiple rules match, refer to the [Origin Rules FAQ](/rules/origin-rules/faq/#what-happens-if-more-than-one-origin-rule-matches-the-current-request). -2. For conflicting settings (for example, bypass cache versus eligible for cache), the last matching rule wins. For example, if cache rule #1 is set to cache everything on `example.com/images` and cache rule #2 is set to bypass cache on `example.com`, then cache will be bypassed for all URLs that match `example.com`, since rule #2 is the last matching rule. +2. For conflicting settings (for example, bypass cache versus eligible for cache), the last matching rule wins. For example, if Cache Rule #1 is set to cache everything on `example.com/images` and Cache Rule #2 is set to bypass cache on `example.com`, then cache will be bypassed for all URLs that match `example.com`, since rule #2 is the last matching rule. -3. If you have Page Rules implemented for caching on the same path, Cache Rules will take precedence by design. +3. If you have Page Rules implemented for caching on the same path, Cache Rules take precedence by design. -4. Cache rules can be more specific than website-wide settings in the cache configuration tab, so they take precedence over website-wide settings on requests they match against. For example, if browser cache TTL is set to 4 hours for the entire website `example.com` and there is a cache rule matching requests with a path of `/feed` setting browser cache TTL to 10 seconds, the cache rule will override the website-wide setting for requests to `https://example.com/feed`. +4. Cache Rules can be more specific than website-wide settings in the cache configuration tab, so they take precedence over website-wide settings on requests they match against. For example, if browser cache TTL is set to 4 hours for the entire website `example.com` and there is a Cache Rule matching requests with a path of `/feed` setting browser cache TTL to 10 seconds, the Cache Rule overrides the website-wide setting for requests to `https://example.com/feed`. ## Execution order of Rules products diff --git a/src/content/docs/cache/how-to/cache-rules/page-rules-migration.mdx b/src/content/docs/cache/how-to/cache-rules/page-rules-migration.mdx index 6541177a91b6aa8..ce1fa13e48d61ba 100644 --- a/src/content/docs/cache/how-to/cache-rules/page-rules-migration.mdx +++ b/src/content/docs/cache/how-to/cache-rules/page-rules-migration.mdx @@ -17,7 +17,7 @@ import { TabItem, Tabs } from "~/components" If you are migrating from Page Rules, there is a behavior change between Page Rules and Cache Rules. -When you create a new Cache Rule and select **Eligible for cache**, the Cache Everything feature is enabled by default. With Page Rules, you had to specifically enable the Cache Everything option. +When you create a new Cache Rule and select **Eligible for cache**, the Cache Everything feature is enabled by default. This means Cloudflare caches all content matching the rule, including content types it does not cache by default (such as HTML). With Page Rules, you had to specifically enable the Cache Everything option. To maintain the same behavior you had with Page Rules (that is, not enabling Cache Everything), you need to create these two specific rules in this order before creating any additional rules. @@ -62,12 +62,10 @@ If you prefer, you can select **Edit expression** and paste the following expres -:::note[Note] - +:::note Remember to create the rules in the specified order: first, the `bypass everything` rule, and then the `cache all default cacheable file extensions` rule. ![Rules order](~/assets/images/cache/rule-order.png) - ::: diff --git a/src/content/docs/cache/how-to/cache-rules/settings.mdx b/src/content/docs/cache/how-to/cache-rules/settings.mdx index 325e0259940cbfd..8f1b27968625a24 100644 --- a/src/content/docs/cache/how-to/cache-rules/settings.mdx +++ b/src/content/docs/cache/how-to/cache-rules/settings.mdx @@ -90,11 +90,11 @@ If you use cache rules, image transformations, and zone versioning simultaneousl Edge Cache TTL refers to the maximum cache time-to-live (TTL), or how long an asset should be considered fresh or available to serve from Cloudflare’s cache in response to requests. This setting has three primary options: -- **Use cache control-header if present, bypass cache if not**: If a cache-control header is present on the response, follow its directives. If not, skip caching entirely. -- **Use cache-control header if present, use default Cloudflare caching behavior if not**: If a cache-control header is present on the response, follow its directives. If not, cache in accordance with our [default edge TTL settings](/cache/how-to/configure-cache-status-code/#edge-ttl). +- **Use cache-control header if present, bypass cache if not**: If a cache-control header is present on the response, follow its directives. If not, skip caching entirely. +- **Use cache-control header if present, use default Cloudflare caching behavior if not**: If a cache-control header is present on the response, follow its directives. If not, cache in accordance with the [default edge TTL settings](/cache/how-to/configure-cache-status-code/#edge-ttl). - **Ignore cache-control header and use this TTL**: Completely ignore any cache-control header on the response and instead cache the response for a duration specified in the timing dropdown. -Additionally, you can select how long you would like a particular matching status code's content to be cached in Cloudflare's global network. In **Status Code TTL** section you can define the TTL duration for one or more status codes of responses from the origin server. This setting can be applied to a _Single code_ status code, to a _Greater than or equal_ or _Less than or equal_ status code, or to a _Range_ of status codes. Status code TTLs are similar to **Ignore cache-control header and use this TTL** in that the cache-control header on the response will be ignored in favor of the TTL specified by the cache rule. For more information, refer to [Status code TTL](/cache/how-to/configure-cache-status-code/). +Additionally, you can select how long you would like a particular matching status code's content to be cached in Cloudflare's global network. In the **Status Code TTL** section, you can define the TTL duration for one or more status codes of responses from the origin server. This setting can be applied to a _Single code_ status code, to a _Greater than or equal_ or _Less than or equal_ status code, or to a _Range_ of status codes. Status code TTLs are similar to **Ignore cache-control header and use this TTL** in that the cache-control header on the response will be ignored in favor of the TTL specified by the cache rule. For more information, refer to [Status code TTL](/cache/how-to/configure-cache-status-code/).
@@ -104,7 +104,7 @@ API configuration object name: `"edge_ttl"`. | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `respect_origin` | Use cache-control header if present, use default [Cloudflare caching behavior](/cache/concepts/default-cache-behavior/) if not. | | `override_origin` | Ignore cache-control header and use this TTL. | -| `bypass_by_default` | Use cache control-header if present, bypass cache if not. | +| `bypass_by_default` | Use cache-control header if present, bypass cache if not. | | | | ```json title="API configuration example" @@ -197,7 +197,7 @@ Enterprise customers have these additional options for custom Cache Keys: - In the **Host** section, you can select **Use original host** and **Resolved host**. In the **User** section, you can select **Device type**, **Country**, and **Language**. Using **Resolved host** means the Cache Key will contain whatever hostname was used to resolve the origin IP which can be different depending on whether the [resolve override](/rules/origin-rules/features/#dns-record) feature is on or not. :::note -When [URL normalization](/rules/normalization/) is enabled, we recommend also enabling [Normalize URLs to origin](/rules/normalization/manage/), especially if you are setting custom Cache Keys or using cache by device type, which also modifies the Cache Key. This helps ensure the URL in the Cache Key matches the URL sent to the origin, preventing cache poisoning and ensuring consistent behavior. +When [URL normalization](/rules/normalization/) is enabled, Cloudflare recommends also enabling [Normalize URLs to origin](/rules/normalization/manage/), especially if you are setting custom Cache Keys or using cache by device type, which also modifies the Cache Key. This helps ensure the URL in the Cache Key matches the URL sent to the origin, preventing cache poisoning and ensuring consistent behavior. :::
@@ -273,7 +273,7 @@ API property name for enabling Cache Reserve: `"eligible"` (boolean). ```json title="API configuration example" "action_parameters": { - "cache": true + "cache": true, "cache_reserve": { "eligible": true, "minimum_file_size": 100000 @@ -304,7 +304,7 @@ API configuration property name: `"additional_cacheable_ports"` (array of intege ```json title="API configuration example" "action_parameters": { - "cache": true + "cache": true, "additional_cacheable_ports": [8443, 8080] } } @@ -394,7 +394,7 @@ Refer to [Create a cache rule via API](/cache/how-to/cache-rules/create-api/#exa #### Origin Cache Control (Enterprise-only) -When this option is enabled, Cloudflare will aim to strictly adhere to [RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234). Enterprise customers have the ability to select if Cloudflare will adhere to this behavior. Free, Pro, and Business customers have this option enabled by default and cannot disable it. +When this option is enabled, Cloudflare will aim to strictly adhere to [RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234). Enterprise customers can select whether Cloudflare adheres to this behavior. Free, Pro, and Business customers have this option enabled by default and cannot disable it.
@@ -402,7 +402,7 @@ API configuration property name: `"origin_cache_control"` (boolean). ```json title="API configuration example" "action_parameters": { - "cache": true + "cache": true, "origin_cache_control": true } ```