Docs / Reference / Rules

TransformRule

TransformRule manages one transform rule in a zone: a rewrite of the URL a request reaches the origin with, or a change to its request or response headers.

API version: kflare.dev/v1alpha1
Scope: Namespaced
Short name: cftransform
Token permission: Zone · Transform 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.

transformrule.yaml

apiVersion: kflare.dev/v1alpha1
kind: TransformRule
metadata:
  name: example-transformrule-url-rewrite
  namespace: default
spec:
  zoneRef:
    name: example-zone
  type: urlRewrite
  expression: http.request.uri.path eq "/old"
  description: Serve /old from /new
  uri:
    path:
      value: /new
      # expression: <expression>
    # query:
    #   expression: <expression>
    #   value: <value>
  # enabled: true
  # headers:
  #   - name: x-visitor-country
  #     operation: set  # one of: add, set, remove
  #     expression: ip.src.country
  #     value: <value>
  # priority: 1

Spec

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

Field	Description
`description` string	Description is shown with the rule in the Cloudflare dashboard. Limits: at most 4096 characters
`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
`headers` []object	Headers are the headers the rule changes, with types requestHeaders and responseHeaders. Cloudflare allows 30 in a rule (2026-10). Limits: at least 1 item Rule: must be one of: operation add with value; operation add with expression; operation set with value; operation set with expression; operation remove
`headers[].expression` string	Expression computes the header's value in Cloudflare's Rules language, for set and add, for example `ip.src`. Limits: at least 1 character
`headers[].name` stringrequired	Name is the header's name. Limits: at least 1 character
`headers[].operation` stringrequired	Operation is what the rule does to the header: set replaces its value, adding the header when the request or response has none; add adds a header even when one is there, in responses only; remove removes it. One of: `add`, `set`, `remove`
`headers[].value` string	Value is the header's value, a static string, for set and add. Set exactly one of value and expression, or neither for remove. Limits: at least 1 character
`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`
`type` stringrequiredimmutable	Type is what the rule transforms, which picks the Rulesets phase its rule is in: - urlRewrite: rewrites the URL's path or query, with uri (phase http_request_transform) - requestHeaders: sets or removes headers of the request to the origin, with headers (phase http_request_late_transform) - responseHeaders: adds, sets or removes headers of the response to the visitor, with headers (phase http_response_headers_transform) Immutable. One of: `urlRewrite`, `requestHeaders`, `responseHeaders`
`uri` object	URI rewrites the URL the request reaches the origin with: its path, its query, or both, with type urlRewrite. The visitor's URL does not change. Rule: must set at least one of path and query
`uri.path` object	Path rewrites the URL's path, to a static value or to what an expression computes. Rule: must set exactly one of expression and value
`uri.path.expression` string	Expression computes the new path, for example `concat("/new", http.request.uri.path)`. Free plans cannot use regex_replace. Limits: at least 1 character
`uri.path.value` string	Value is the new path, which starts with a slash. Limits: at least 1 character; matches `^/`
`uri.query` object	Query rewrites the URL's query string, to a static value or to what an expression computes. Rule: must set exactly one of expression and value
`uri.query.expression` string	Expression computes the new query string. Limits: at least 1 character
`uri.query.value` string	Value is the new query string, without its question mark. An empty one removes the query string.
`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 headers and uri
type urlRewrite takes uri and no headers
types requestHeaders and responseHeaders take headers and no uri
operation add is for response headers only

Status

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

Field	Description
`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 transformrules prints.

Column	Source
TYPE	.spec.type
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_transformrule.yaml

# Generated by kflare-gen from generator/generator.yaml. DO NOT EDIT.
#
# A transform rule of type urlRewrite: rewrites the URL's path or query, with
# uri.
apiVersion: kflare.dev/v1alpha1
kind: TransformRule
metadata:
  name: example-transformrule-url-rewrite
  namespace: default
spec:
  zoneRef:
    name: example-zone
  type: urlRewrite
  expression: http.request.uri.path eq "/old"
  description: Serve /old from /new
  uri:
    path:
      value: /new
---
#
# A transform rule of type requestHeaders: sets or removes headers of the
# request to the origin, with headers.
apiVersion: kflare.dev/v1alpha1
kind: TransformRule
metadata:
  name: example-transformrule-request-headers
  namespace: default
spec:
  zoneRef:
    name: example-zone
  type: requestHeaders
  expression: starts_with(http.request.uri.path, "/api/")
  description: Tell the origin which country a request comes from
  headers:
  - name: x-visitor-country
    operation: set
    expression: ip.src.country
---
#
# A transform rule of type responseHeaders: adds, sets or removes headers of the
# response to the visitor, with headers.
apiVersion: kflare.dev/v1alpha1
kind: TransformRule
metadata:
  name: example-transformrule-response-headers
  namespace: default
spec:
  zoneRef:
    name: example-zone
  type: responseHeaders
  expression: "true"
  description: Keep pages out of frames and stop revealing the server's stack
  headers:
  - name: x-frame-options
    operation: set
    value: DENY
  - name: x-powered-by
    operation: remove

On GitHub