Skip to content

[Rules] Add ref field to Terraform and API examples #22963

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 11, 2025
Merged

[Rules] Add ref field to Terraform and API examples #22963

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c89a8b9
[Rules] Add `ref` field to Terraform and API examples
pedrosousa Jun 9, 2025
ff5cfbf
Add ref to cache rules example
pedrosousa Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion src/content/docs/cache/how-to/cache-rules/terraform-example.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ head:
content: Cache Rules — Terraform example
---

import { Details } from "~/components";
import { Details, Render } from "~/components";

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`.

Expand Down Expand Up @@ -82,6 +82,12 @@ resource "cloudflare_ruleset" "cache_rules_example" {
}
```

<Render
file="terraform-use-ref-field"
product="rules"
params={{ addDocsLocation: true }}
/>

</Details>

For additional guidance on using Terraform with Cloudflare, refer to [Terraform](/terraform/).
5 changes: 4 additions & 1 deletion src/content/docs/rules/compression-rules/examples/disable-all-brotli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Create a compression rule to turn off Brotli compression for all
incoming requests of a given zone.
---

import { Example, TabItem, Tabs, APIRequest } from "~/components";
import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

Expand Down Expand Up @@ -40,6 +40,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
json={{
rules: [
{
ref: "always_use_gzip",
expression: "true",
action: "compress_response",
action_parameters: {
Expand All @@ -50,4 +51,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</TabItem> </Tabs>
5 changes: 4 additions & 1 deletion src/content/docs/rules/compression-rules/examples/disable-compression-avif.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ description: Create a compression rule to turn off compression for AVIF images,
request.
---

import { Example, TabItem, Tabs, APIRequest } from "~/components";
import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

Expand Down Expand Up @@ -42,6 +42,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
json={{
rules: [
{
ref: "disable_compression_for_avif",
expression:
'http.response.content_type.media_type eq "image/avif" or http.request.uri.path.extension eq "avif"',
action: "compress_response",
Expand All @@ -53,4 +54,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</TabItem> </Tabs>
5 changes: 4 additions & 1 deletion src/content/docs/rules/compression-rules/examples/enable-zstandard.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: Enable Zstandard compression for default content types
description: Create a compression rule to turn on Zstandard compression for response content types where Cloudflare applies compression by default.
---

import { Example, TabItem, Tabs, APIRequest } from "~/components";
import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

Expand Down Expand Up @@ -38,6 +38,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
json={{
rules: [
{
ref: "use_zstd_compression",
expression:
'(http.response.content_type.media_type in {"text/html" "text/richtext" "text/plain" "text/css" "text/x-script" "text/x-component" "text/x-java-source" "text/x-markdown" "application/javascript" "application/x-javascript" "text/javascript" "text/js" "image/x-icon" "image/vnd.microsoft.icon" "application/x-perl" "application/x-httpd-cgi" "text/xml" "application/xml" "application/rss+xml" "application/vnd.api+json" "application/x-protobuf" "application/json" "multipart/bag" "multipart/mixed" "application/xhtml+xml" "font/ttf" "font/otf" "font/x-woff" "image/svg+xml" "application/vnd.ms-fontobject" "application/ttf" "application/x-ttf" "application/otf" "application/x-otf" "application/truetype" "application/opentype" "application/x-opentype" "application/font-woff" "application/eot" "application/font" "application/font-sfnt" "application/wasm" "application/javascript-binast" "application/manifest+json" "application/ld+json" "application/graphql+json" "application/geo+json"})',
action: "compress_response",
Expand All @@ -49,4 +50,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</TabItem> </Tabs>
5 changes: 4 additions & 1 deletion src/content/docs/rules/compression-rules/examples/gzip-for-csv.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Create a compression rule to set Gzip compression as the preferred
compression method for CSV files.
---

import { Example, TabItem, Tabs, APIRequest } from "~/components";
import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

Expand Down Expand Up @@ -40,6 +40,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
json={{
rules: [
{
ref: "use_gzip_for_csv",
expression: 'http.request.uri.path.extension eq "csv"',
action: "compress_response",
action_parameters: {
Expand All @@ -50,4 +51,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</TabItem> </Tabs>
5 changes: 4 additions & 1 deletion src/content/docs/rules/compression-rules/examples/only-brotli-url-path.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Create a compression rule to set Brotli as the only supported
compression algorithm for a specific URI path.
---

import { Example, TabItem, Tabs, APIRequest } from "~/components";
import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

Expand Down Expand Up @@ -42,6 +42,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
json={{
rules: [
{
ref: "use_only_brotli_for_assets_tar",
expression: 'http.request.uri.path eq "/download/assets.tar"',
action: "compress_response",
action_parameters: {
Expand All @@ -52,4 +53,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</TabItem> </Tabs>
6 changes: 6 additions & 0 deletions src/content/docs/rules/configuration-rules/create-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
json={{
rules: [
{
ref: "enable_email_obfuscation_bic",
expression: 'starts_with(http.request.uri.path, "/contact-us/")',
description:
"Obfuscates email addresses and enables BIC in contacts page",
Expand All @@ -56,6 +57,8 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</Details>

<Details header="Example: Add a rule that turns on Under Attack mode for the admin area">
Expand All @@ -68,6 +71,7 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
json={{
rules: [
{
ref: "enable_under_attack_in_admin",
expression: 'http.host eq "admin.example.com"',
description: "Turn on Under Attack mode for admin area",
action: "set_config",
Expand All @@ -79,6 +83,8 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</Details>

---
Expand Down
2 changes: 2 additions & 0 deletions ...cs/rules/configuration-rules/examples/define-single-configuration-terraform.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,6 @@ resource "cloudflare_ruleset" "http_config_rules_example" {
}
```

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

<Render file="terraform-additional-resources" />
5 changes: 4 additions & 1 deletion src/content/docs/rules/custom-errors/create-rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar:
order: 3
---

import { APIRequest } from "~/components";
import { APIRequest, Render } from "~/components";

## In the dashboard

Expand Down Expand Up @@ -111,6 +111,7 @@ This example configures a custom error rule returning a [previously created cust
json={{
rules: [
{
ref: "serve_500_template",
action: "serve_error",
action_parameters: {
asset_name: "500_error_template",
Expand All @@ -123,6 +124,8 @@ This example configures a custom error rule returning a [previously created cust
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.

## Required API token permissions
Expand Down
14 changes: 13 additions & 1 deletion src/content/docs/rules/custom-errors/example-rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar:
order: 4
---

import { Tabs, TabItem, APIRequest } from "~/components";
import { Tabs, TabItem, APIRequest, Render } from "~/components";

The provided examples use the following fields in their rule expressions:

Expand Down Expand Up @@ -48,6 +48,7 @@ This example configures a custom JSON error response for all 5XX errors (`500`-`
json={{
rules: [
{
ref: "json_response_for_5xx_errors",
action: "serve_error",
action_parameters: {
content: '{"message": "A server error occurred."}',
Expand All @@ -61,6 +62,8 @@ This example configures a custom JSON error response for all 5XX errors (`500`-`
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.

</TabItem> </Tabs>
Expand Down Expand Up @@ -103,6 +106,7 @@ This example configures a custom HTML error response for responses with a `500`
json={{
rules: [
{
ref: "html_response_500_to_503",
action: "serve_error",
action_parameters: {
content:
Expand All @@ -117,6 +121,8 @@ This example configures a custom HTML error response for responses with a `500`
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.

</TabItem> </Tabs>
Expand Down Expand Up @@ -154,6 +160,7 @@ This example configures a custom HTML error response for [Cloudflare error 1020]
json={{
rules: [
{
ref: "html_response_cf_1020",
action: "serve_error",
action_parameters: {
content:
Expand All @@ -167,6 +174,8 @@ This example configures a custom HTML error response for [Cloudflare error 1020]
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.

</TabItem> </Tabs>
Expand Down Expand Up @@ -204,6 +213,7 @@ This example configures a custom error rule returning a previously created custo
json={{
rules: [
{
ref: "serve_error_500_asset",
action: "serve_error",
action_parameters: {
asset_name: "500_error_template",
Expand All @@ -216,6 +226,8 @@ This example configures a custom error rule returning a previously created custo
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.

</TabItem> </Tabs>
3 changes: 3 additions & 0 deletions src/content/docs/rules/origin-rules/create-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
json={{
rules: [
{
ref: "override_sni_for_admin",
Copy link
Contributor

@windsurf-bot windsurf-bot bot Jun 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR adds a ref field to the API example, but there's no explanation in the documentation about what this field is used for or why it's important. Consider adding a brief explanation about the purpose and benefits of using the ref field in rules.

Copy link
Contributor Author

@pedrosousa pedrosousa Jun 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The explanation actually exists and is located in the Terraform docs. We're linking there using a partial.

expression: 'http.host eq "admin.example.com"',
description: "SNI Override for the admin area",
action: "route",
Expand All @@ -64,6 +65,8 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
}}
/>

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</Details>

---
Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/rules/origin-rules/examples/define-single-origin-terraform.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,6 @@ resource "cloudflare_ruleset" "http_origin_example" {
}
```

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

<Render file="terraform-additional-resources" />
12 changes: 12 additions & 0 deletions src/content/docs/rules/transform/request-header-modification/create-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
json={{
rules: [
{
ref: "add_header_source",
expression: '(starts_with(http.request.uri.path, "/en/"))',
description: "My first request header transform rule",
action: "rewrite",
Expand All @@ -71,6 +72,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
"version": "2",
"rules": [
{
"ref": "add_header_source",
"id": "<RULE_ID>",
"version": "1",
"action": "rewrite",
Expand All @@ -97,6 +99,8 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
}
```

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</Details>

<Details header="Example: Add an HTTP request header with a dynamic value">
Expand All @@ -109,6 +113,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
json={{
rules: [
{
ref: "add_header_bot_score",
expression: '(starts_with(http.request.uri.path, "/en/"))',
description: "My first request header transform rule",
action: "rewrite",
Expand All @@ -135,6 +140,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
"version": "2",
"rules": [
{
"ref": "add_header_bot_score",
"id": "<RULE_ID>",
"version": "1",
"action": "rewrite",
Expand All @@ -161,6 +167,8 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
}
```

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</Details>

<Details header="Example: Remove an HTTP request header">
Expand All @@ -173,6 +181,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
json={{
rules: [
{
ref: "remove_header_cf_connecting_ip",
expression: '(starts_with(http.request.uri.path, "/en/"))',
description: "My first request header transform rule",
action: "rewrite",
Expand All @@ -198,6 +207,7 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
"version": "2",
"rules": [
{
"ref": "remove_header_cf_connecting_ip",
"id": "<RULE_ID>",
"version": "1",
"action": "rewrite",
Expand All @@ -223,6 +233,8 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
}
```

<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />

</Details>

---
Expand Down
Loading