[Rules] Update Origin Rules (#22659)

pedrosousa · web-flow · commit 3354bf90007a · 2025-05-27T17:12:52.000+01:00
diff --git a/src/content/docs/rules/origin-rules/create-api.mdx b/src/content/docs/rules/origin-rules/create-api.mdx
@@ -29,9 +29,9 @@ Make sure your API token has the [required permissions](#required-api-token-perm
 
 ## Example requests
 
-<Details header="Example: Add a rule that overrides the HTTP `Host` header">
+<Details header="Example: Add a rule that overrides the `Host` header of incoming requests and the resolved DNS record">
 
-<Render file="origin-rules-api-change-host-header" />
+<Render file="origin-rules-api-change-host-header-dns-record" />
 
 </Details>
 
@@ -66,66 +66,6 @@ The following example sets the rules of an existing phase ruleset (`$RULESET_ID`
 
 </Details>
 
-<Details header="Example: Add a rule that overrides the resolved DNS record and the `Host` header of incoming requests">
-
-The following example sets the rules of an existing phase ruleset (`$RULESET_ID`) to a single origin rule — overriding the resolved DNS record and the `Host` header of incoming requests — using the [Update a zone ruleset](/api/resources/rulesets/methods/update/) operation. The response will contain the complete definition of the ruleset you updated.
-
-<APIRequest
-	path="/zones/{zone_id}/rulesets/{ruleset_id}"
-	method="PUT"
-	json={{
-		rules: [
-			{
-				expression: 'starts_with(http.request.uri.path, "/hr-app/")',
-				description: "Origin rule for the company HR application",
-				action: "route",
-				action_parameters: {
-					host_header: "hr-server.example.com",
-					origin: {
-						host: "hr-server.example.com",
-					},
-				},
-			},
-		],
-	}}
-/>
-
-```json output
-{
-	"result": {
-		"id": "<RULESET_ID>",
-		"name": "Origin Rules ruleset",
-		"description": "Zone-level ruleset that will execute origin rules.",
-		"kind": "zone",
-		"version": "2",
-		"rules": [
-			{
-				"id": "<RULE_ID>",
-				"version": "1",
-				"action": "route",
-				"action_parameters": {
-					"host_header": "hr-server.example.com",
-					"origin": {
-						"host": "hr-server.example.com"
-					}
-				},
-				"expression": "starts_with(http.request.uri.path, \"/hr-app/\")",
-				"description": "Origin rule for the company HR application",
-				"last_updated": "2022-06-03T14:42:04.219025Z",
-				"ref": "<RULE_REF>"
-			}
-		],
-		"last_updated": "2022-06-03T14:42:04.219025Z",
-		"phase": "http_request_origin"
-	},
-	"success": true,
-	"errors": [],
-	"messages": []
-}
-```
-
-</Details>
-
 ---
 
 ## Required API token permissions
diff --git a/src/content/docs/rules/origin-rules/examples/change-http-host-header.mdx b/src/content/docs/rules/origin-rules/examples/change-http-host-header.mdx
@@ -1,39 +1,53 @@
 ---
 pcx_content_type: example
-summary: Create an origin rule to change the HTTP `Host` header.
+summary: Create an origin rule to change the HTTP `Host` header and DNS record.
 products:
   - Origin Rules
-title: Change the HTTP Host header
-description: Create an origin rule to change the HTTP `Host` header.
+title: Change the HTTP Host header and DNS record
+description: Create an origin rule to change the HTTP `Host` header and the resolved DNS record.
 ---
 
 import { Render, Tabs, TabItem, Example } from "~/components";
 
-The following origin rule overrides the HTTP `Host` header to `eu_server.example.net` for all requests containing `/eu/` in their URI path.
+The following origin rule overrides the HTTP `Host` header to `hr-server.example.com` for all requests with a URI path starting with `/hr-app/`. It also overrides the DNS record to the same hostname.
+
+The `Host` header override only updates the header value; the DNS record override will handle the rerouting of incoming requests. For more information on these overrides, refer to [Available settings](/rules/origin-rules/features/).
 
 <Tabs syncKey="dashPlusAPI">
 <TabItem label="Dashboard" no-code="true">
 
 <Example>
 
-Text in Expression Editor:
+Expression when using the Expression Builder:
+
+| Field    | Operator    | Value      |
+| -------- | ----------- | ---------- |
+| URI Path | starts with | `/hr-app/` |
+
+Expression when using the Expression Editor:
 
 ```txt
-http.request.uri.path contains "/eu/"
+(starts_with(http.request.uri.path, "/hr-app/"))
 ```
 
 Value after **Host Header** > **Rewrite to**:
 
 ```txt
-eu_server.example.net
+hr-server.example.com
+```
+
+Value after **DNS Record** > **Override to**:
+
+```txt
+hr-server.example.com
 ```
 
 </Example>
 
 </TabItem>
 <TabItem label="API" no-code="true">
 
-<Render file="origin-rules-api-change-host-header" />
+<Render file="origin-rules-api-change-host-header-dns-record" />
 
 </TabItem>
 </Tabs>
diff --git a/src/content/docs/rules/origin-rules/features.mdx b/src/content/docs/rules/origin-rules/features.mdx
@@ -20,7 +20,9 @@ A common use case for this functionality is when your content is hosted on a thi
 
 :::note[Notes]
 
-- An origin rule performing a Host header override will also update the Server Name Indication (SNI) value of the original request to the same value. To set an SNI value different from the Host header value, add an [SNI override](#server-name-indication-sni) in the same origin rule or create a separate origin rule for this purpose.
+- In most situations, when you rewrite the HTTP `Host` header you also need to configure a [DNS record override](#dns-record). The `Host` header override only updates the header value; the DNS record override will handle the rerouting of the request.
+
+- An origin rule performing a `Host` header override will also update the Server Name Indication (SNI) value of the original request to the same value. To set an SNI value different from the `Host` header value, add an [SNI override](#server-name-indication-sni) in the same origin rule or create a separate origin rule for this purpose.
 
 - If you have configured load balancing through Cloudflare and you wish to override the HTTP `Host` header per origin or for a given monitor, refer to [Override HTTP Host headers](/load-balancing/additional-options/override-http-host-headers/) in the Load Balancing documentation for more information.
 
@@ -30,10 +32,9 @@ A common use case for this functionality is when your content is hosted on a thi
 
 Allows you to override the Server Name Indication (SNI) [^1] value of a request. For more information, refer to [What is SNI (Server Name Indication)?](https://www.cloudflare.com/learning/ssl/what-is-sni/) in the Learning Center.
 
-The new SNI value must be a valid hostname on the same Cloudflare account (possibly on a different zone).
-
 :::note[Notes]
 
+- The new SNI value must be a valid hostname on the same Cloudflare account (possibly on a different zone).
 - Currently, you can only use a static value when overriding SNI.
 - An SNI override will take precedence over [SNI rewrites of custom origins](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/custom-origin/#sni-rewrites) when using Cloudflare for SaaS.
 
@@ -47,9 +48,13 @@ Allows you to override the resolved hostname of incoming requests. This function
 
 A common use case is when you are serving an application from the URI (for example, `mydomain.com/app`). In this case, the `app` may be hosted on a different server or by a third party. A DNS record override allows you to redirect requests to this endpoint to the server for that third-party application.
 
-You must specify a valid hostname in a DNS record override that is a hostname on the same Cloudflare account (possibly on a different zone).
+:::note
+
+- You must specify a valid hostname in a DNS record override that is a hostname on the same Cloudflare account (possibly on a different zone). You can [configure a DNS record](/dns/manage-dns-records/how-to/create-dns-records#create-dns-records) (a `CNAME`, `A`, or `AAAA` record) with a hostname pointing to a third-party hostname/IP address, either proxied by Cloudflare or not.
 
-You can [configure a DNS record](/dns/manage-dns-records/how-to/create-dns-records#create-dns-records) (a `CNAME`, `A`, or `AAAA` record) with a hostname pointing to a third-party hostname/IP address, either proxied by Cloudflare or not.
+- In most situations, when you configure a DNS record override you also need to configure a [`Host` header override](#host-header). The DNS record override handles the rerouting of the request; the `Host` header override updates the `Host` HTTP header value in the request. Defining a `Host` header override will also update the Server Name Indication (SNI) value of the original request to the same value. To set an SNI value different from the `Host` header value, add an [SNI override](#server-name-indication-sni) in the same origin rule or create a separate origin rule for this purpose.
+
+:::
 
 The following example DNS records configure a `resolve.example.com` hostname pointing to an external hostname and IP address using a `CNAME` record and an `A` record, respectively:
 
diff --git a/src/content/docs/rules/origin-rules/parameters.mdx b/src/content/docs/rules/origin-rules/parameters.mdx
@@ -17,7 +17,6 @@ Create [different overrides](/rules/origin-rules/features/) by including differe
 | DNS record override / Destination port override | [`origin` object](#dns-record-override-and-destination-port-override-parameters) |
 
 :::note
-
 The same origin rule can have different types of overrides. Refer to [Configuring several overrides in the same rule](#configuring-several-overrides-in-the-same-rule) for a syntax example.
 :::
 
diff --git a/src/content/partials/rules/origin-rules-api-change-host-header-dns-record.mdx b/src/content/partials/rules/origin-rules-api-change-host-header-dns-record.mdx
@@ -0,0 +1,61 @@
+---
+{}
+---
+
+import { APIRequest } from "~/components";
+
+The following example sets the rules of an existing phase ruleset (`$RULESET_ID`) to a single origin rule — overriding the `Host` header of incoming requests and the resolved DNS record — using the [Update a zone ruleset](/api/resources/rulesets/methods/update/) operation. The response will contain the complete definition of the ruleset you updated.
+
+<APIRequest
+	path="/zones/{zone_id}/rulesets/{ruleset_id}"
+	method="PUT"
+	json={{
+		rules: [
+			{
+				expression: 'starts_with(http.request.uri.path, "/hr-app/")',
+				description: "Origin rule for the company HR application",
+				action: "route",
+				action_parameters: {
+					host_header: "hr-server.example.com",
+					origin: {
+						host: "hr-server.example.com",
+					},
+				},
+			},
+		],
+	}}
+/>
+
+```json output
+{
+	"result": {
+		"id": "<RULESET_ID>",
+		"name": "Origin Rules ruleset",
+		"description": "Zone-level ruleset that will execute origin rules.",
+		"kind": "zone",
+		"version": "2",
+		"rules": [
+			{
+				"id": "<RULE_ID>",
+				"version": "1",
+				"action": "route",
+				"action_parameters": {
+					"host_header": "hr-server.example.com",
+					"origin": {
+						"host": "hr-server.example.com"
+					}
+				},
+				"expression": "starts_with(http.request.uri.path, \"/hr-app/\")",
+				"description": "Origin rule for the company HR application",
+				"last_updated": "2022-06-03T14:42:04.219025Z",
+				"ref": "<RULE_REF>"
+			}
+		],
+		"last_updated": "2022-06-03T14:42:04.219025Z",
+		"phase": "http_request_origin"
+	},
+	"success": true,
+	"errors": [],
+	"messages": []
+}
+```
diff --git a/src/content/partials/rules/origin-rules-api-change-host-header.mdx b/src/content/partials/rules/origin-rules-api-change-host-header.mdx
