Skip to content
kflare
Documentation menu

Docs / Reference / Rules

CacheRule

CacheRule manages one cache rule in a zone: how Cloudflare caches the responses to the requests its expression matches, at the edge and in browsers.

API version
kflare.dev/v1alpha1
Scope
Namespaced
Short name
cfcache
Token permission
Zone · Cache Rules · Edit

Example

Every field, with the sample's values. The live lines are the repository's sample, which applies as it is; the commented ones are the other fields, filled from other samples where one sets them. Some exclude each other, so check the rules before you uncomment several.

cacherule.yaml
apiVersion: kflare.dev/v1alpha1
kind: CacheRule
metadata:
  name: example-cacherule
  namespace: default
spec:
  zoneRef:
    name: example-zone
  expression: http.request.uri.path.extension in {"css" "js" "png" "jpg" "svg" "woff2"}
  description: Cache static assets, whose names carry their version, for a day
  browserTTL:
    mode: override_origin
    default: 3600
  cache: true
  cacheKey:
    customKey:
      queryString:
        exclude:
          all: true
    # cacheByDeviceType: true
    # cacheDeceptionArmor: true
    # ignoreQueryStringsOrder: true
  edgeTTL:
    mode: override_origin
    default: 86400
    statusCodeTTL:
      - value: 60
        statusCode: 404
      - value: 0
        statusCodeRange:
          from: 500
      # - value: 60
      #   statusCode: 404
      #   statusCodeRange:
      #     from: 500
      #     to: 100
  vary:
    default:
      action: passthrough
    headers:
      - name: accept
        action: normalize
        mediaTypes:
          - image/avif
          - image/webp
      # - name: accept
      #   action: normalize  # one of: bypass, passthrough, normalize
      #   mediaTypes:
      #     - image/avif
      #     - image/webp
      #   languages:
      #     - <languages>
  # additionalCacheablePorts:
  #   - 1
  # cacheReserve:
  #   eligible: true
  #   minimumFileSize: 0
  # enabled: true
  # originCacheControl: true
  # originErrorPagePassthru: true
  # originRangeRequests:
  #   mode: "on"  # one of: on, off, default
  # priority: 1
  # respectStrongEtags: true
  # serveStale:
  #   disableStaleWhileUpdating: true

Spec

What you set, with the limits the API server enforces.

FieldDescription
additionalCacheablePorts
[]integer

AdditionalCacheablePorts are more ports Cloudflare caches responses on. Cloudflare's documentation lists them for Enterprise plans; Free zones accept and store them.

Limits: at least 1 item; at least 1 and at most 65535; format int64

browserTTL
object

BrowserTTL is how long browsers cache the response. A purge does not reach browsers, so a long one can leave them with stale content.

Rule: set default with mode override_origin, and only with it

browserTTL.default
integer

Default is the browser TTL, in seconds, with mode override_origin.

Limits: at least 0; format int64

browserTTL.mode
stringrequired

Mode is where the browser TTL comes from: respect_origin keeps the origin's, override_origin sets default's, bypass_by_default bypasses the browser cache unless the origin says otherwise, and bypass always bypasses it.

One of: respect_origin, bypass_by_default, override_origin, bypass

cache
boolean

Cache makes the response eligible for Cloudflare's cache. Whether it is cached still depends on its cache control headers and the zone's other cache settings.

cacheKey
object

Which components of the request are included in or excluded from the cache key Cloudflare uses to store the response in cache.

cacheKey.cacheByDeviceType
boolean

Whether to separate cached content based on the visitor's device type.

cacheKey.cacheDeceptionArmor
boolean

Whether to protect from web cache deception attacks, while allowing static assets to be cached.

cacheKey.customKey
object

CustomKey changes the request's parts the cache key holds. Free plans may only leave out the query string.

Rule: customKey sets queryString

cacheKey.customKey.queryString
object

QueryString leaves the query string out of the cache key.

Rule: queryString sets exclude

cacheKey.customKey.queryString.exclude
object

Which query string parameters to exclude from the cache key.

cacheKey.customKey.queryString.exclude.all
booleanrequired

All leaves every query string parameter out of the cache key.

One of: true

cacheKey.ignoreQueryStringsOrder
boolean

Whether to treat requests with the same query parameters the same, regardless of the order those query parameters are in.

cacheReserve
object

CacheReserve makes the response eligible for Cache Reserve, which needs the Cache Reserve add-on to take effect; Free zones accept and store it.

Rule: minimumFileSize needs eligible

cacheReserve.eligible
booleanrequired

Whether Cache Reserve is enabled. If this is true and a request meets eligibility criteria, Cloudflare will write the resource to Cache Reserve.

cacheReserve.minimumFileSize
integer

The minimum file size eligible for storage in Cache Reserve.

Limits: at least 0; format int64

description
string

Description is shown with the rule in the Cloudflare dashboard.

Limits: at most 4096 characters

edgeTTL
object

EdgeTTL is how long Cloudflare's edge caches the response.

Rule: set default with mode override_origin, and only with it

edgeTTL.default
integer

Default is the edge TTL, in seconds, with mode override_origin.

Limits: at least 0; format int64

edgeTTL.mode
stringrequired

Mode is where the edge TTL comes from: respect_origin keeps the origin's, override_origin sets default's, and bypass_by_default does not cache unless the origin says otherwise.

One of: respect_origin, bypass_by_default, override_origin

edgeTTL.statusCodeTTL
[]object

StatusCodeTTL sets the edge TTL of responses by their status code, each item for one code or a range of them. Cloudflare refuses ranges that overlap.

Limits: at least 1 item

Rule: must set at least 2 of value, statusCode and statusCodeRange

Rule: must set at most 2 of value, statusCode and statusCodeRange

edgeTTL.statusCodeTTL[].statusCode
integer

A single status code to apply the TTL to.

Limits: at least 100 and at most 999; format int64

edgeTTL.statusCodeTTL[].statusCodeRange
object

StatusCodeRange is the range of status codes the TTL is for: from and to, each optional, a range without one is open on that side.

Rule: must set at least one of from and to

Rule: from is below to

edgeTTL.statusCodeTTL[].statusCodeRange.from
integer

The lower bound of the range.

Limits: at least 100 and at most 999; format int64

edgeTTL.statusCodeTTL[].statusCodeRange.to
integer

The upper bound of the range.

Limits: at least 100 and at most 999; format int64

edgeTTL.statusCodeTTL[].value
integerrequired

Value is the TTL, in seconds: 0 for no-cache, -1 for no-store.

Limits: format int64

enabled
boolean

Enabled turns the rule on or off without deleting it.

Default: true

expression
stringrequired

Expression selects the requests the rule applies to, in Cloudflare's Rules language, for example http.request.uri.path eq "/admin". Cloudflare validates it; the fields and operators it may use depend on the zone's plan.

Limits: 1 to 4096 characters

originCacheControl
boolean

OriginCacheControl makes Cloudflare follow RFC 7234 strictly. Cloudflare's documentation lists it for Enterprise plans; Free zones accept and store it.

originErrorPagePassthru
boolean

Whether to generate Cloudflare error pages for issues from the origin server.

originRangeRequests
object

Controls whether Cloudflare fetches a large asset from the origin as a series of range requests instead of one whole-body request.

originRangeRequests.mode
stringrequired

Mode is whether Cloudflare fetches a large asset from the origin in ranges: on, off, or default, the zone's behavior without the rule. Quote on and off in YAML, which would read them as booleans.

One of: on, off, default

priority
integer

Priority orders the rules kflare manages in a zone and phase: lower runs first, and rules with the same priority run in order of namespace and name. Rules created outside kflare keep their place.

Limits: format int32

respectStrongEtags
boolean

Whether Cloudflare should respect strong ETag (entity tag) headers. If false, Cloudflare converts strong ETag headers to weak ETag headers.

serveStale
object

When to serve stale content from cache.

serveStale.disableStaleWhileUpdating
boolean

Whether Cloudflare should disable serving stale content while getting the latest content from the origin.

vary
object

Vary is how a response's Vary header shapes the cache key: default for every header, and headers for some of them.

Rule: must set at least one of default and headers

Rule: headers need a default

vary.default
object

Controls how response Vary headers without a per-header override contribute to the cache key.

vary.default.action
stringrequired

How the header value is treated when building the cache key.

One of: bypass, passthrough, normalize

vary.headers
[]object

Headers are what the cache key takes from some request headers, at most 50.

Limits: at most 50 items

Rule: languages are for the accept-language header only

Rule: mediaTypes are for the accept header only

vary.headers[].action
stringrequired

How the header value is treated when building the cache key.

One of: bypass, passthrough, normalize

vary.headers[].languages
[]string

The set of languages to normalize against. Only valid for the accept-language header.

Limits: at most 20 items; 1 to 64 characters; matches ^[ -~]+$

vary.headers[].mediaTypes
[]string

The set of media types to normalize against. Only valid for the accept header.

Limits: at most 10 items; 1 to 255 characters; matches ^[ -~]+$

vary.headers[].name
stringrequired

Name is the request header's name, in lower case.

Limits: at least 1 character; matches ^[^A-Z]+$

zoneRef
objectrequiredimmutable

ZoneRef references the Zone, in the same namespace, the rule belongs to. Immutable after creation.

zoneRef.name
string

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

Default: ""

Rules

Checked across fields when the resource is applied.

  • must set at least one of additionalCacheablePorts, browserTTL, cache, cacheKey, cacheReserve, edgeTTL, originCacheControl, originErrorPagePassthru, originRangeRequests, respectStrongEtags, serveStale and vary

Status

What kflare reports. conditions holds the Ready condition, whose reason says why a resource isn't ready.

FieldDescription
cloudflareMetadata
object

CloudflareMetadata identifies the rule in Cloudflare.

cloudflareMetadata.ref
string

Ref is the rule's ref, which kflare derives from the resource's kind, namespace and name. kflare finds the rule it manages by its ref.

cloudflareMetadata.ruleID
string

RuleID is the rule's Cloudflare ID.

cloudflareMetadata.rulesetID
string

RulesetID is the zone's entry point ruleset for the rule's phase.

cloudflareMetadata.version
string

Version is the rule's version, which Cloudflare increments whenever the rule changes.

cloudflareMetadata.zoneID
string

ZoneID is the Cloudflare zone the rule is in.

conditions
[]object

Conditions represent the latest available observations of the rule's state.

kubectl get

The columns kubectl get cacherules prints.

ColumnSource
PRIORITY.spec.priority
RULE ID.status.cloudflareMetadata.ruleID
READY.status.conditions[?(@.type=="Ready")].status
AGE.metadata.creationTimestamp

Samples

From the repository's config/samples, comments included.

cloudflare_v1alpha1_cacherule.yaml
# Generated by kflare-gen from generator/generator.yaml. DO NOT EDIT.
#
# CacheRule is the Schema for the cacherules API.
# It manages one cache rule in a zone: how Cloudflare caches the responses
# to the requests its expression matches, at the edge and in browsers.
apiVersion: kflare.dev/v1alpha1
kind: CacheRule
metadata:
  name: example-cacherule
  namespace: default
spec:
  zoneRef:
    name: example-zone
  expression: http.request.uri.path.extension in {"css" "js" "png" "jpg" "svg" "woff2"}
  description: Cache static assets, whose names carry their version, for a day
  browserTTL:
    mode: override_origin
    default: 3600
  cache: true
  cacheKey:
    customKey:
      queryString:
        exclude:
          all: true
  edgeTTL:
    mode: override_origin
    default: 86400
    statusCodeTTL:
    - value: 60
      statusCode: 404
    - value: 0
      statusCodeRange:
        from: 500
  vary:
    default:
      action: passthrough
    headers:
    - name: accept
      action: normalize
      mediaTypes:
      - image/avif
      - image/webp

On GitHub