From e5ef87cb10a98df11f4b6733f133628856197f0f Mon Sep 17 00:00:00 2001
From: aadarshmunna221 <aadarshmunnacs@gmail.com>
Date: Wed, 29 Oct 2025 20:09:39 +0530
Subject: [PATCH] docs: add EnvoyPatchPolicy JSONPatch examples for Cluster
 (add external, tweak timeout) (#7306)

---
 .../tasks/extensibility/envoy-patch-policy.md | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)

diff --git a/site/content/en/v1.5/tasks/extensibility/envoy-patch-policy.md b/site/content/en/v1.5/tasks/extensibility/envoy-patch-policy.md
index 72b047e3bc4..2522062b508 100644
--- a/site/content/en/v1.5/tasks/extensibility/envoy-patch-policy.md
+++ b/site/content/en/v1.5/tasks/extensibility/envoy-patch-policy.md
@@ -432,6 +432,153 @@ $ curl -v --header "Host: www.example.com" http://localhost:8888/
 ...
 ```
 
+### Customize Cluster
+
+The following examples show how to use [EnvoyPatchPolicy][] to modify Envoy `Cluster` resources using JSONPatch semantics.
+
+{{< tabpane text=true >}}
+{{% tab header="Add an external Cluster (from stdin)" %}}
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyPatchPolicy
+metadata:
+  name: add-external-cluster
+  namespace: default
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: eg
+  type: JSONPatch
+  jsonPatches:
+    - type: "type.googleapis.com/envoy.config.cluster.v3.Cluster"
+      # Adds a new STRICT_DNS cluster named external-svc-cluster
+      name: external-svc-cluster
+      operation:
+        op: add
+        path: ""
+        value:
+          name: external-svc-cluster
+          type: STRICT_DNS
+          connect_timeout: 10s
+          lb_policy: ROUND_ROBIN
+          http2_protocol_options: {}
+          load_assignment:
+            cluster_name: external-svc-cluster
+            endpoints:
+              - lb_endpoints:
+                  - endpoint:
+                      address:
+                        socket_address:
+                          address: example.external.svc
+                          port_value: 8443
+EOF
+```
+
+{{% /tab %}}
+{{% tab header="Add an external Cluster (from file)" %}}
+Save and apply the following resource to your cluster:
+
+```yaml
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyPatchPolicy
+metadata:
+  name: add-external-cluster
+  namespace: default
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: eg
+  type: JSONPatch
+  jsonPatches:
+    - type: "type.googleapis.com/envoy.config.cluster.v3.Cluster"
+      # Adds a new STRICT_DNS cluster named external-svc-cluster
+      name: external-svc-cluster
+      operation:
+        op: add
+        path: ""
+        value:
+          name: external-svc-cluster
+          type: STRICT_DNS
+          connect_timeout: 10s
+          lb_policy: ROUND_ROBIN
+          http2_protocol_options: {}
+          load_assignment:
+            cluster_name: external-svc-cluster
+            endpoints:
+              - lb_endpoints:
+                  - endpoint:
+                      address:
+                        socket_address:
+                          address: example.external.svc
+                          port_value: 8443
+```
+
+{{% /tab %}}
+{{% tab header="Modify a route Cluster timeout (from stdin)" %}}
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyPatchPolicy
+metadata:
+  name: tweak-route-cluster-timeout
+  namespace: default
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: eg
+  type: JSONPatch
+  jsonPatches:
+    - type: "type.googleapis.com/envoy.config.cluster.v3.Cluster"
+      # For clusters generated from HTTPRoute, the default name is:
+      # httproute/<NAMESPACE>/<NAME>/rule/<RULE_NUMBER>
+      # e.g. httproute/default/backend/rule/0
+      name: httproute/default/backend/rule/0
+      operation:
+        op: replace
+        path: "/connect_timeout"
+        value: "5s"
+EOF
+```
+
+{{% /tab %}}
+{{% tab header="Modify a route Cluster timeout (from file)" %}}
+Save and apply the following resource to your cluster:
+
+```yaml
+---
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyPatchPolicy
+metadata:
+  name: tweak-route-cluster-timeout
+  namespace: default
+spec:
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: Gateway
+    name: eg
+  type: JSONPatch
+  jsonPatches:
+    - type: "type.googleapis.com/envoy.config.cluster.v3.Cluster"
+      # For clusters generated from HTTPRoute, the default name is:
+      # httproute/<NAMESPACE>/<NAME>/rule/<RULE_NUMBER>
+      # e.g. httproute/default/backend/rule/0
+      name: httproute/default/backend/rule/0
+      operation:
+        op: replace
+        path: "/connect_timeout"
+        value: "5s"
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
+
 ## Debugging
 
 ### Runtime