Cache Rules
Use Cache Rules to customize cache properties of your HTTP requests. For example, create a rule to specify how long to cache a resource in the Cloudflare global network.
Availability
The following table describes Cache Rules availability per plan.
Free | Pro | Business | Enterprise | |
Availability | Yes | Yes | Yes | Yes |
Number of rules | 10 | 25 | 50 | 125 |
Order and priority
Cache rules are unique, unlike Page Rules. This is how they are applied:
Cache Rules are stackable. This means that multiple matching rules will be combined and applied. So if multiple cache rules match the same URL, then the features set in those cache rules will all be applied. 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.
For conflicting settings (for example, bypass cache vs. 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 onexample.com
, then cache will be bypassed for all URLs that matchexample.com
, since rule #2 is the last matching rule.If you have Page Rules implemented for caching on the same path, Cache Rules will take precedence by design. In the near future, Cloudflare plans on releasing a one-click migration tool for Page Rules.
Create Cache Rules in the dashboard
To create a new cache rule:
- Log in to the Cloudflare dashboard and select your account and domain.
- Go to Caching > Cache Rules.
- Select Create cache rule.
- Enter a descriptive name for the rule in Rule name.
- Under When incoming requests match, define the rule expression. Use the Field drop-down list to choose an HTTP property (refer to Available fields for the list of available fields). For each request, the value of the property you choose for Field is compared to the value you specify for Value using the operator selected in Operator.
To create a wildcard rule that applies to everything under a URI directory (for example,
/images
), select the option URI in Field, starts with in Operator, and/images
in Value. - Under Then, in the Cache status section, select Bypass cache, if matching requests will bypass cache and fetch a response from the origin server or Eligible for cache if requests will be eligible for cache. Note that proper origin cache-control headers are also required for cache eligibility.
- If you select Eligible for cache, you can customize the following options:
Edge TTL
Select Respect origin if matching requests will respect cache headers received from the origin server, or Override origin. If you wish to override the Edge TTL value, you need to select how long you want to cache resources in the Cloudflare global network.
- In Status code TTL you can define the cache time-to-live (TTL) duration for one or more response status codes received from the origin server. This setting can be applied to a Single code status code, to a Greater than or Less than status code or to a Range of status codes. For more information, refer to Status code TTL.
Browser TTL
Select if you want to Respect origin or Override origin. If you wish to override the browser TTL value, define how long resources cached by client browsers will remain valid. For more information, refer to Browser Cache TTL.
Cache Key
Define the request components used to define a custom cache key. A cache key is an identifier that Cloudflare uses for a file stored in the cache. These are the options that you can customize:
- You can switch on or off Cache by device type, Cache deception armor, and Ignore query string order.
- In the Query string section, you can select All query string parameters, All query string parameters except and enter an exception, Only these parameters and enter the parameters, or Ignore query string.
- In the Headers section, you can include headers names and their values, check the presence of another header, and Include origin header.
- In the Cookie section, you can include cookie names and their values, and check the presence of another cookie.
- 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.
Serve stale content
Enable or disable serving stale content while updating from the origin server. If serving stale content is disabled, origin cache-control headers will be used to tell Cloudflare how to handle content from the origin.
Respect Strong ETags
Turn on or off byte-for-byte equivalency checks between the Cloudflare cache and the origin server. When enabled, Cloudflare will use strong ETag header validation to ensure that resources in the Cloudflare cache and on the origin server are byte-by-byte identical. If disabled, Cloudflare converts ETag headers into weak ETag headers.
Origin error page pass-thru
Turn on or off Cloudflare error pages generated from issues sent from the origin server. If enabled, this setting triggers error pages issued by the origin.
- To save and deploy your rule, select Deploy. If you are not ready to deploy your rule, select Save as Draft.
Available fields
These are the fields available for Cache Rule expressions:
- Cookie -
http.cookie
- Hostname -
http.host
- Referer -
http.referer
- SSL/HTTPS -
ssl
- URI Full -
http.request.full_uri
- URI -
http.request.uri
- URI Path -
http.request.uri.path
- URI Query String -
http.request.uri.query
- User Agent -
http.user_agent
- X-Forwarded-For -
http.x_forwarded_for
Refer to Fields for reference information on these fields.
Create Cache Rules via API
Use the Rulesets API to create a Cache Rule via API.
When creating a Configuration Rule via API, make sure you:
- Set the rule action to
set_cache_settings
. - Define the parameters in the
action_parameters
field according to the settings you wish to override for matching requests. - You deploy the cache rule to the
http_request_cache_settings
phase entry point ruleset.
Create a Cache Rule
- Use the List existing rulesets method to obtain the list of rules already present in the
http_request_cache_settings
phase entry point ruleset. - If the phase ruleset does not exist, create it using the Create ruleset method with the zone-level endpoint. In the new ruleset properties, set the following values:
- kind:
zone
- phase:
http_request_cache_settings
- kind:
- Alternatively, you can also use the Update ruleset method to add a Cache Rule to the list of ruleset rules.
Required API token permissions
The API token used in API requests to manage Cache Rules must have the following permissions:
- Zone > Config Rules > Edit
- Account Rulesets > Edit
- Account Filter Lists > Edit
API examples
These examples are setting all the Cache Rules of a zone to a single rule, since using these examples directly will cause any existing rules to be deleted. In this setting, you can choose either to In this second example, For In this second example, In this example, In this example, In this example, In this example, Edge cache TTL
respect_origin
(first example) or override_origin
(second example). In this first example, edge_ttl
is set to respect_origin
and cache TTL is set by status code 404
with a duration of 30 seconds.status_code_ttl
is set to override_origin
and cache TTL is set by status code 404
with a duration of 30 seconds. Instead of a single status code, you can also define a range.Browser Cache TTL
set_cache_settings
, you can choose either to respect_origin
(first example) or override_origin
(second example).override_origin
is selected, so you need to define how long resources cached by client browsers will remain valid, in this case 30 seconds.Cache Key
cache_deception_armor
and ignore_query_strings_order
parameters are set to true
. query_string
is set to query all query string parameters. The header
parameter is set to include header1
, check presence of header_1
and the origin header
is also included. The cookie
parameter is set to include cookie1
, check the presence of cookie_1
and the origin header
is also included. The parameter host : resolved
is set to false
, geo
, and lang
are also set to false
.Serve stale content
serve_stale
is set to not serve stale content while updating from the origin server.Respect strong ETags
respect_strong_etags
is set to true
to ensure that resources in the Cloudflare cache and on the origin server are byte-by-byte identical.Origin error page pass-thru
origin_error_page_passthru
is set to true
to trigger error pages issued by the origin.
Terraform example
The following example defines a single cache rule for a zone using Terraform. The rule configures several cache settings and sets a custom cache key for incoming requests addressed at example.net
.Terraform
cloudflare_ruleset
resource
For additional guidance on using Terraform with Cloudflare, refer to Terraform.