docs(gateway-api): document custom backendRef and backend-specific filters for HTTPRoute

Signed-off-by: kahirokunn <okinakahiro@gmail.com>

Author: kahirokunn

docs/gitbook/tutorials/gatewayapi-progressive-delivery.md

@@ -242,12 +242,12 @@ When the canary analysis starts, Flagger will call the pre-rollout webhooks befo
 After a couple of seconds Flagger will create the canary objects:
 
 ```bash
-# applied 
+# applied
 deployment.apps/podinfo
 horizontalpodautoscaler.autoscaling/podinfo
 canary.flagger.app/podinfo
 
-# generated 
+# generated
 deployment.apps/podinfo-primary
 horizontalpodautoscaler.autoscaling/podinfo-primary
 service/podinfo
@@ -404,7 +404,7 @@ While Flagger can perform weighted routing and A/B testing individually, with Ga
 release with session affinity.
 For more information you can read the [deployment strategies docs](../usage/deployment-strategies.md#canary-release-with-session-affinity).
 
-> **Note:** The implementation must have support for the [`ResponseHeaderModifier`](https://github.com/kubernetes-sigs/gateway-api/blob/3d22aa5a08413222cb79e6b2e245870360434614/apis/v1beta1/httproute_types.go#L651) API. 
+> **Note:** The implementation must have support for the [`ResponseHeaderModifier`](https://github.com/kubernetes-sigs/gateway-api/blob/3d22aa5a08413222cb79e6b2e245870360434614/apis/v1beta1/httproute_types.go#L651) API.
 
 Create a canary custom resource \(replace www.example.com with your own domain\):
 
@@ -728,3 +728,72 @@ With the above configuration, Flagger will run a canary release with the followi
 * send notification with the canary analysis result
 
 The above procedures can be extended with [custom metrics](../usage/metrics.md) checks, [webhooks](../usage/webhooks.md), [manual promotion](../usage/webhooks.md#manual-gating) approval and [Slack or MS Teams](../usage/alerting.md) notifications.
+
+## Custom backends and backend-specific filters (Gateway API)
+
+Flagger can configure custom `backendRef` and backend-specific `filters` on the generated `HTTPRoute` when using the Gateway API provider. This allows you to:
+
+* override the default `Service` backend with an arbitrary backend object reference
+* attach filters that are executed only when a specific backend is selected by routing (e.g., per-backend header modifiers)
+
+This is controlled via `spec.service.primaryBackend` and `spec.service.canaryBackend` fields of the `Canary` resource. When set, Flagger will use these values to populate `rules[].backendRefs[]` for the primary and canary targets respectively.
+
+Example:
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: Canary
+metadata:
+  name: podinfo
+  namespace: test
+spec:
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: podinfo
+  service:
+    port: 9898
+    hosts:
+      - www.example.com
+    gatewayRefs:
+      - name: gateway
+        namespace: istio-ingress
+    # Optional: override backends and add backend-specific filters
+    primaryBackend:
+      backendRef:
+        group: ""
+        kind: Service
+        name: podinfo-primary
+        port: 9898
+      filters:
+        - type: ResponseHeaderModifier
+          responseHeaderModifier:
+            add:
+              - name: X-Primary-Backend
+                value: "true"
+    canaryBackend:
+      backendRef:
+        group: ""
+        kind: Service
+        name: podinfo-canary
+        port: 9898
+      filters:
+        - type: ResponseHeaderModifier
+          responseHeaderModifier:
+            add:
+              - name: X-Canary-Backend
+                value: "true"
+  analysis:
+    interval: 1m
+    threshold: 5
+    maxWeight: 50
+    stepWeight: 10
+```
+
+Notes:
+
+* Backend-specific filters attached via `primaryBackend.filters` and `canaryBackend.filters` are only evaluated when requests are forwarded to that particular backend.
+* If the backend references a cross-namespace resource, Flagger will automatically create and maintain `ReferenceGrant` objects to allow the `HTTPRoute` to reference it across namespaces.
+* You can continue to use route-level filters through the existing `service.headers`, `service.rewrite`, and `service.mirror` fields; those apply regardless of which backend is selected.
+
+This feature is supported only with the Gateway API provider. Other providers ignore `primaryBackend` and `canaryBackend`.